NanoClaw Core

NanoClaw Core is the agent runtime that powers goClaw. It handles task scheduling, LLM invocation, MCP tool execution, and sandboxed agent contexts. It is deliberately lightweight — no heavy orchestration framework, no vector databases, no Kubernetes.

What NanoClaw Core does

• Receives tasks from the task scheduler or inbound channel messages
• Loads agent context: persona, goals, relevant knowledge, conversation history
• Invokes Claude (Sonnet or Haiku depending on task complexity)
• Executes MCP tools as directed by the agent
• Writes results back to the CRM and task queue
• Files curiosity items for knowledge gaps encountered during execution

Task scheduler

NanoClaw Core includes a SQLite-backed task scheduler. Tasks are used for:

Task type	Example
follow_up	Schedule a follow-up email in 3 days
research	Queue a background research run on a prospect
knowledge_research	Process a curiosity queue batch nightly
channel_check	Poll IMAP for new inbound email
custom	Any agent-defined recurring task

Tasks are created by the agent during execution (via MCP tools) or by the admin dashboard directly.

// Example: agent creates a follow-up task
await mcp.tool("crm_schedule_followup", {
  contact_id: contact.id,
  channel: "email",
  delay_days: 3,
  context: "Sent intro email. Awaiting response.",
});

LLM routing

NanoClaw Core routes to different Claude models based on task type:

Task	Model	Rationale
Primary reasoning, response generation	Claude Sonnet 4.6	Best balance of capability and cost
Classification, CRM lookups, short tasks	Claude Haiku 4.5	Fast and cheap for simple operations
Complex multi-step planning, rare cases	Claude Opus 4.6	Reserved for highest-complexity tasks
Web search synthesis	GPT-4o-mini	Cost-efficient for research pipelines

Batch-eligible tasks (async research, knowledge indexing) are routed through Anthropic's batch API at a 50% cost discount.

MCP tool execution

The agent accesses all platform capabilities through MCP (Model Context Protocol) tools. This is the same interface used by Claude Code and other Anthropic-compatible clients — goClaw exposes its internal capabilities as MCP tools.

Core MCP tools

CRM tools:

• crm_search — search contacts by name, email, company, or tags
• crm_get_contact — retrieve full contact record with thread history
• crm_create_contact — create a new contact
• crm_update_contact — update contact fields, add tags
• crm_add_note — attach a note to a contact record
• crm_get_threads — retrieve conversation threads for a contact
• crm_schedule_followup — schedule a follow-up task

Knowledge tools:

• knowledge_search — full-text search across the knowledge base (FTS5)
• knowledge_get — retrieve a specific knowledge file by path
• knowledge_file_curiosity — file a curiosity item for nightly research

Channel tools:

• send_email — send an email via Resend
• send_sms — send an SMS via Twilio
• send_telegram — send a Telegram message
• send_whatsapp — send a WhatsApp message

Research tools:

• web_search — search the web (via OpenAI function calling)
• web_fetch — retrieve a specific URL's content

Skills system

Skills are Markdown files with YAML frontmatter that define step-by-step procedures. The agent reads, executes, and — crucially — creates and updates its own skills.

---
skill: prospect_outreach
version: 3
created: 2026-02-15
updated: 2026-03-01
tags: [gtm, outreach, email]
---

# Prospect Outreach Skill

## Steps
1. Search CRM for existing contact record
2. If no record exists, create one with available context
3. Research the company using web_search
4. Draft a personalized opening email based on company context and ICP
5. Send via email channel
6. Schedule follow-up task for 3 business days
7. Log skill execution to contact notes

When the agent encounters a new procedure it doesn't have a skill for, it drafts a new skill file and adds it to the skills directory. On next execution of a similar task, it references the skill.

Execution context

Each agent invocation loads a full execution context:

interface AgentContext {
  persona: string;           // From agent.yaml
  goals: string[];           // From agent.yaml
  message: NormalizedMessage; // Inbound message (if applicable)
  contact: ContactRecord;    // Full CRM contact record
  threads: ThreadRecord[];   // Conversation history
  knowledge: string[];       // Relevant knowledge files (retrieved by semantic search)
  skills: string[];          // Relevant skill files
  group: GroupConfig;        // Permission group settings
}

Context is assembled before invoking the LLM. Knowledge and skills are retrieved by semantic similarity to the current task — not all files are loaded into every prompt.

Sandboxed execution

NanoClaw Core supports two isolation modes:

Process-level isolation (default)

Each agent group runs in its own Node.js worker thread with scoped access to:

• Its own knowledge mount paths
• Its allowlisted MCP tools only
• Its own CRM view (filtered by group tags)

Container isolation (optional)

When sandbox.container: true is set in permissions.yaml, agent execution moves into a Docker container with:

• Read-only filesystem mount of allowed knowledge directories
• Network allowlist (only configured channel endpoints)
• Non-root execution (UID 1000)
• No access to host credentials (only runtime tokens passed via env)

Container mode is recommended for multi-tenant deployments or when agents have access to sensitive tooling.