__  ___     __        ________              
   /  |/  /__  / /_____ _/ ____/ /___ __      __
  / /|_/ / _ \/ __/ __ `/ /   / / __ `/ | /| / /
 / /  / /  __/ /_/ /_/ / /___/ / /_/ /| |/ |/ / 
/_/  /_/\___/\__/\__,_/\____/_/\__,_/ |__/|__/  

MetaClaw is a personal AI Assistant built from the ground up in Go. It originated as a fork of PicoClaw (which was inspired by nanobot), and has since evolved into a distinct project with its own architecture and design philosophy.

Where PicoClaw focuses on ultra-lightweight deployment, MetaClaw focuses on meta-cognition — the agent's ability to reason about its own thinking.

The name "Meta" reflects exactly what makes this project different:

• Meta-cognition — The 3-phase architecture (Analyse → Execute → Reflect) is fundamentally about an agent that thinks about how to think
• Meta-data driven — Intent, tags, CoT prompts — everything is structured metadata about the conversation itself
• Meta-programming — Built through AI self-bootstrapping, where the agent drove its own architectural evolution

Core principles:

• Go-native — Single self-contained binary, no external runtime, runs on RISC-V / ARM / x86
• Layered, not monolithic — Each phase is a separate, testable component
• Security-first — 4-layer filesystem sandbox + command guard with allow/deny patterns
• Channel-agnostic — Same agent logic serves CLI, Telegram, Feishu, and more
• Extension-first — Optional capabilities (voice) plug in via a unified lifecycle framework

Every user interaction flows through three distinct phases. This separation allows specialized models, observable intermediate states, and efficient token usage.

┌──────────────────────────────────────────────────────────┐
│                     Entry Points                          │
│              Telegram · Feishu · CLI                        │
└────────────────────────┬─────────────────────────────────┘
                         │  MessageBus (pub/sub)
                         ▼
┌──────────────────────────────────────────────────────────┐
│                    AgentLoop                              │
│                                                          │
│  ┌──────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │ Phase 1  │  │   Phase 2    │  │     Phase 3      │   │
│  │ Analyse  │→ │   Execute    │→ │     Reflect      │   │
│  │          │  │              │  │                  │   │
│  │ intent   │  │ LLM ↔ Tools │  │ score + persist  │   │
│  │ tags     │  │ iterations   │  │ TurnStore        │   │
│  │ CoT      │  │ multi-agent  │  │ ActiveContext    │   │
│  └──────────┘  └──────────────┘  └──────────────────┘   │
└──────────────────────────────────────────────────────────┘
          │                    │                │
  ┌───────────┐       ┌──────────────┐  ┌────────────┐
  │   Tools   │       │    Memory    │  │   Skills   │
  │ Registry  │       │  TurnStore   │  │   3-layer  │
  │ (+ MCP)   │       │  KVCache     │  │   loader   │
  └───────────┘       │  Digest      │  └────────────┘
                      └──────────────┘

A fast, cheap auxiliary model classifies the user's intent and extracts tags before the main LLM runs.

• Extracts { intent, tags[], cot_prompt } from the user message
• Matches skills by keywords → injects a Tool Execution Plan
• Generates a tailored Chain-of-Thought strategy for Phase 2
• Injects historical usage stats to keep the analyser consistent

The primary model handles core reasoning with tool calling in an iterative loop.

• Assembles context: system prompt + Active Context + Instant Memory (relevant past turns) + user message
• History messages are annotated with [turn intent=code tags=[go]] for cross-turn awareness
• CoT prompt from Phase 1 is injected as a ## Thinking Strategy section
• Multi-agent routing via AgentRegistry for specialized tasks

Post-turn evaluation, synchronous scoring + async persistence.

• Sync (<2ms): Turn scoring determines if the turn is "always kept" in future contexts
• Async: TurnStore.Insert() → SQLite with tag inverted index (no LIKE '%tag%' scans)
• Background MemoryDigestWorker extracts durable facts into long-term memory

git clone https://github.com/user/metaclaw.git
cd metaclaw && task deps && task build

git clone https://github.com/user/metaclaw.git && cd metaclaw
docker compose -f docker/docker-compose.yml --profile gateway up   # first run: generates config
vim docker/data/config.json                                        # set API keys
docker compose -f docker/docker-compose.yml --profile gateway up -d # start

1. Initialize

metaclaw onboard

2. Configure (~/.metaclaw/config.json)

{
  "model_list": [
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "your-api-key"
    }
  ],
  "agents": {
    "defaults": {
      "model_name": "gpt4"
    }
  }
}

Use vendor/model format (e.g. zhipu/glm-4.7, anthropic/claude-sonnet-4.6) — zero code changes for new providers.

3. Chat

metaclaw agent -m "What is 2+2?"

All webhook channels share a single Gateway HTTP server (127.0.0.1:18790 by default).

Config file: ~/.metaclaw/config.json

Load balancing: Configure multiple endpoints for the same model_name — MetaClaw round-robins automatically.

MetaClaw enforces a layered security model where every file and command operation passes through multiple validation layers:

File operations:
  tildeExpandFs          ~ → $HOME expansion
    → whitelistFs        Config allow_read_paths / allow_write_paths
      → sandboxFs        os.Root workspace restriction (kernel-level)
        → hostFs         Direct filesystem access

Command execution:
  denyPatterns           Block rm -rf, format, dd, shutdown, fork bombs
  allowPatterns          Custom overrides (e.g. git push origin)
  customAllowPatterns    Exempt specific commands from deny checks
  path traversal guard   Blocks .. and absolute paths outside workspace

• Kernel-level sandbox: Uses Go 1.23+ os.Root API — path escape is blocked at the OS level, not just string matching
• Whitelist paths: allow_read_paths / allow_write_paths grant access to specific paths outside workspace without disabling the sandbox
• Command guard: Multi-layer pattern matching (deny → custom allow → allow → workspace restriction)
• Consistent boundary: Main agent, subagents, spawned tasks, and heartbeat all inherit the same restriction — no bypass via delegation

MetaClaw is a fork of PicoClaw that has diverged in focus:

We gratefully acknowledge PicoClaw and the Sipeed team for the foundation that made MetaClaw possible.

PRs welcome! The codebase is intentionally small and readable. 🤗

MIT