Skip to content
NanoClaw
On Trove · from Matan Marudi

NanoClaw

The Complete Agent Developer's Guide

A definitive reference for building, customizing, and operating NanoClaw v2 agents.

Read a preview

You can read the contents and the first 2,000 characters.
Free accounts get the whole book.

  • By Matan Marudi
  • 27 chapters
  • Updated Nov 1, 2026
  • 49 readers

What’s inside

  • What is NanoClaw?
  • The Core Architecture
  • Entity Model and Data Model
  • Claude Integration
  • Your First Agent
  • Agent Identity (CLAUDE.md)

What is NanoClaw?

A definitive reference for building, customizing, and operating NanoClaw v2 agents. Covers architecture, entity model, Claude integration, multi-agent orchestration, memory, security, and the full skills ecosystem.

markdown · Listed May 17, 2026

  • nano-claw

From the first page

Last updated: 2026-06-14 · Scope of validity: NanoClaw v2 (≈ v2.0.64, May 2026); Anthropic model/pricing facts current as of 2026-06-14. Review cadence: model, pricing, and breaking-changes pages quarterly or on any Anthropic model release; architecture/skills pages on each NanoClaw minor version. Maintainer: see CONTRIBUTING.md in the NanoClaw repository.

Preview · 2,000 of 179,090 characters

Building Your Agent Team: A Practitioner's Guide to Multi-Agent AI Systems
UI/UX Design Principles for AI Agents
Blender 3D Mastery: A Complete Reference for Claude Code with Blender MCP
X Algorithm Growth Hacking: A Complete Guide Based on the Open-Source Code

Contents

  1. 01NanoClaw: The Complete Agent Developer's Guidep.1
  2. 02Decision Matrixp.2
  3. 03What is NanoClaw?p.3
    1. Philosophyp.3
    2. v1 vs v2p.3
    3. How NanoClaw differsp.3
    4. When to use NanoClawp.3
  4. 04The Core Architecturep.4
    1. Agent rulesp.4
  5. 05Entity Model and Data Modelp.5
    1. Users and rolesp.5
    2. Agent groups, messaging groups, and wiringsp.5
    3. Sessionsp.5
    4. Other central tablesp.5
    5. Querying databasesp.5
  6. 06Claude Integrationp.6
    1. The Anthropic Agent SDKp.6
    2. Continuationp.6
    3. The prompt/context flowp.6
    4. Model selection for NanoClawp.6
    5. Effort levelsp.6
    6. Provider alternativesp.6
  7. 07Your First Agentp.7
    1. Prerequisitesp.7
    2. Create the agent groupp.7
    3. Write the identityp.7
    4. Create a messaging group and wire itp.7
    5. Testp.7
    6. Debugging startupp.7
  8. 08Agent Identity (CLAUDE.md)p.8
    1. Structurep.8
    2. System prompt assembly orderp.8
    3. CLAUDE.local.mdp.8
    4. The pruning rulep.8
    5. What goes wherep.8
    6. Module fragmentsp.8
    7. Common mistakesp.8
See all 27 parts
  1. 09Container Configurationp.9
    1. The schemap.9
    2. Editing via nclp.9
    3. MCP serversp.9
    4. Packages: apt and npmp.9
    5. Additional mounts and mount securityp.9
    6. cli_scopep.9
    7. Skill configurationp.9
  2. 10Channel Integrationp.10
    1. How adapters workp.10
    2. Installing channelsp.10
    3. InboundEvent formatp.10
    4. Multi-channel wiringp.10
    5. Channel topology in promptsp.10
    6. Platform IDs and threadingp.10
  3. 11Memory Architecturep.11
    1. Why files, not vectorsp.11
    2. Four memory typesp.11
    3. MEMORY.md (the index)p.11
    4. Post-conversation memory extractionp.11
    5. The Dream processp.11
    6. Shared CLAUDE.md vs personal memoryp.11
    7. Cross-referencesp.11
  4. 12Multi-Agent Systemsp.12
    1. When to use multiple agentsp.12
    2. Template vs Instance patternp.12
    3. Tool scoping for blast radiusp.12
    4. The Visibility Principlep.12
    5. Inter-agent message typesp.12
    6. Policy enforcementp.12
    7. The GroupQueue patternp.12
    8. Agent failure modesp.12
  5. 13Human-in-the-Loopp.13
    1. The approval primitivep.13
    2. Approval handler registrationp.13
    3. OneCLI credential approvalp.13
    4. Sender approvalp.13
    5. Interactive questionsp.13
    6. Three approval modes per agentp.13
    7. Building trust progressivelyp.13
  6. 14Scheduling and Automationp.14
    1. The `schedule` MCP toolp.14
    2. One-shot vs recurringp.14
    3. Drift preventionp.14
    4. Task managementp.14
    5. Webhook processingp.14
    6. The `on_wake` message patternp.14
  7. 15Self-Modificationp.15
    1. What can be self-modifiedp.15
    2. Host-side authorization for `create_agent`p.15
    3. The flowp.15
    4. Why approval is requiredp.15
    5. Common use casesp.15
  8. 16Skills Developmentp.16
    1. The four skill typesp.16
    2. SKILL.md formatp.16
    3. Progressive disclosurep.16
    4. Container skills vs host skillsp.16
    5. Registry-backed skills (channels and providers)p.16
    6. Testing skillsp.16
  9. 17Model Selection and Context Economicsp.17
    1. Context is finitep.17
    2. The five context-management layersp.17
    3. Static / dynamic system prompt splitp.17
    4. Tiered model strategyp.17
    5. When to reach above Opus 4.8 (Fable 5)p.17
    6. Token budget trackingp.17
  10. 18Prompt Engineering for NanoClaw Agentsp.18
    1. Three layers of agent qualityp.18
    2. System prompt assembly orderp.18
    3. Hard constraints vs soft guidancep.18
    4. "Lead with the finding"p.18
    5. The parallel tool calling blockp.18
    6. Anti-patternsp.18
  11. 19Tool Design for NanoClaw Agentsp.19
    1. Ten principlesp.19
    2. Poka-yoke principlesp.19
    3. MCP server design for NanoClawp.19
  12. 20Multi-Agent Orchestration Patternsp.20
    1. The five patternsp.20
    2. The coordinator mode four-phase workflowp.20
    3. Continue vs spawn decision matrixp.20
    4. Verification agent patternp.20
    5. Session Separation Testingp.20
    6. Sub-agents for knowledge retrievalp.20
    7. WorkTree parallel developmentp.20
  13. 21Security Modelp.21
    1. OS-level container isolationp.21
    2. Mount allowlistp.21
    3. OneCLI credential injectionp.21
    4. Egress lockdownp.21
    5. cli_scope enforcementp.21
    6. Prompt injection defensesp.21
    7. The permission spectrump.21
  14. 22Monitoring and Debuggingp.22
    1. Log filesp.22
    2. The `/debug` skillp.22
    3. Session inspectionp.22
    4. The heartbeat filep.22
    5. Common issuesp.22
    6. Inter-agent message auditp.22
  15. 23Best Practices and Anti-Patternsp.23
    1. Best practicesp.23
    2. Anti-patternsp.23
  16. 24The NanoClaw Skills Ecosystemp.24
    1. Feature / capability skills (channels & providers are registry-backed; install by additive fetch — see Ch. 24)p.24
    2. Operational skills (instruction-only, always on `main`)p.24
    3. Utility skills (with code)p.24
    4. Container skills (runtime, mounted into every agent)p.24
  17. 25Anthropic API Deep Referencep.25
    1. 23.1 Model Referencep.25
    2. 23.2 Choosing the Right Modelp.25
    3. 23.3 Effort Levels: What They Actually Changep.25
    4. 23.4 Thinking Modesp.25
    5. 23.5 Universal Prompting Techniquesp.25
    6. 23.6 Model-Specific Behaviors and Fixesp.25
    7. 23.7 Agentic Patterns for NanoClawp.25
    8. 23.8 Tool Use Referencep.25
    9. +5 more sections
  18. 26The Skills Customization Contractp.26
    1. 24.1 The problem and the betp.26
    2. 24.2 A fork is a recipe of skillsp.26
    3. 24.3 Two kinds of skillsp.26
    4. 24.4 Skill anatomyp.26
    5. 24.5 Change shapes, in safety orderp.26
    6. 24.6 Registry branches: additive fetch, never mergep.26
    7. 24.7 A test for every integration pointp.26
    8. 24.8 The anti-patterns registerp.26
    9. +2 more sections
  19. 27Appendicesp.27
    1. Appendix A: Key Database Queriesp.27
    2. Appendix B: Environment Variables Referencep.27
    3. Appendix C: Container Configuration Referencep.27
    4. Appendix D: ncl CLI Referencep.27
    5. Appendix E: Glossaryp.27
    6. The Edit/Reaction API: Contract and Rate Limitsp.27
    7. Prompt-Level Injection Containment: The Data/Instruction Boundaryp.27
    8. Chapter 25: Proposed Extensions (Design Guidance, Not Implemented)p.27