clawdie/clawdie-ai
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
clawdie-ai/docs/SPEC.md
Clawdie 170480cbc8 Introduce Warden runtime naming
2026-03-08 09:43:33 +01:00

25 KiB
Raw Blame History

Clawdie Specification

A personal AI assistant accessible via messaging channels, with persistent memory per conversation, scheduled tasks, and integrations.

Table of Contents

  1. Architecture
  2. Folder Structure
  3. Configuration
  4. Memory System
  5. Session Management
  6. Message Flow
  7. Commands
  8. Scheduled Tasks
  9. MCP Servers
  10. Deployment
  11. Security Considerations

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        HOST (macOS)                                  │
│                   (Main Node.js Process)                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────┐                     ┌────────────────────┐        │
│  │  Telegram    │────────────────────▶│   SQLite Database  │        │
│  │  (grammy)    │◀────────────────────│   (messages.db)    │        │
│  └──────────────┘   store/send        └─────────┬──────────┘        │
│                                                  │                   │
│         ┌────────────────────────────────────────┘                   │
│         │                                                            │
│         ▼                                                            │
│  ┌──────────────────┐    ┌──────────────────┐    ┌───────────────┐  │
│  │  Message Loop    │    │  Scheduler Loop  │    │  IPC Watcher  │  │
│  │  (polls SQLite)  │    │  (checks tasks)  │    │  (file-based) │  │
│  └────────┬─────────┘    └────────┬─────────┘    └───────────────┘  │
│           │                       │                                  │
│           └───────────┬───────────┘                                  │
│                       │ spawns jail                                  │
│                       ▼                                              │
├─────────────────────────────────────────────────────────────────────┤
│               WARDEN RUNTIME (FREEBSD JAIL)                            │
├─────────────────────────────────────────────────────────────────────┤
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                    WARDEN WORKER                              │   │
│  │                                                                │   │
│  │  Working directory: /workspace/group (mounted from host)       │   │
│  │  Volume mounts:                                                │   │
│  │    • groups/{name}/ → /workspace/group                         │   │
│  │    • groups/global/ → /workspace/global/ (non-main only)        │   │
│  │    • data/sessions/{group}/.agent/ → /home/node/.agent/      │   │
│  │    • Additional dirs → /workspace/extra/*                      │   │
│  │                                                                │   │
│  │  Tools (all groups):                                           │   │
│  │    • Bash (safe - sandboxed in jail!)                          │   │
│  │    • Read, Write, Edit, Glob, Grep (file operations)           │   │
│  │    • WebSearch, WebFetch (internet access)                     │   │
│  │    • agent-browser (browser automation)                        │   │
│  │    • mcp__nanoclaw__* (scheduler tools via IPC)                │   │
│  │                                                                │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

Technology Stack

Component Technology Purpose
Telegram Connection Node.js (grammy) Connect to Telegram, send/receive messages
Message Storage SQLite (better-sqlite3) Store messages for polling
Jail Runtime FreeBSD jails Isolated environments for agent execution
Warden Runtime Clawdie execution layer Project-specific name for jailed agent execution
Agent pi / PI coding agent Run the coding agent with tools and MCP servers
Browser Automation agent-browser + Chromium Web interaction and screenshots
Runtime Node.js 20+ Host process for routing and scheduling

Warden Naming

Warden is the Clawdie name for the isolated execution layer.

  • FreeBSD jail remains the correct operating-system term
  • Bastille remains the host-side jail manager
  • Warden runtime refers to Clawdie's jailed execution model and worker dispatch

Folder Structure

nanoclaw/
├── AGENTS.md                     # Project context for the coding agent
├── docs/
│   ├── SPEC.md                    # This specification document
│   ├── REQUIREMENTS.md            # Architecture decisions
│   └── SECURITY.md                # Security model
├── README.md                      # User documentation
├── package.json                   # Node.js dependencies
├── tsconfig.json                  # TypeScript configuration
├── .mcp.json                      # MCP server configuration (reference)
├── .gitignore
│
├── src/
│   ├── index.ts                   # Orchestrator: state, message loop, agent invocation
│   ├── channels/
│   │   └── telegram.ts            # Telegram connection and send/receive
│   ├── ipc.ts                     # IPC watcher and task processing
│   ├── router.ts                  # Message formatting and outbound routing
│   ├── config.ts                  # Configuration constants
│   ├── types.ts                   # TypeScript interfaces (includes Channel)
│   ├── logger.ts                  # Pino logger setup
│   ├── db.ts                      # SQLite database initialization and queries
│   ├── group-queue.ts             # Per-group queue with global concurrency limit
│   ├── mount-security.ts          # Mount allowlist validation for jails
│   ├── telegram-auth.ts           # Standalone Telegram token verification
│   ├── task-scheduler.ts          # Runs scheduled tasks when due
│   └── jail-runner.ts             # Spawns Warden workers in jails
│
├── jail/
│   ├── agent-runner/              # Code that runs inside the Warden jail worker
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   └── src/
│   │       ├── index.ts           # Entry point (query loop, IPC polling, session resume)
│   │       └── ipc-mcp-stdio.ts   # Stdio-based MCP server for host communication
│   └── skills/
│       └── agent-browser.md       # Browser automation skill
│
├── dist/                          # Compiled JavaScript (gitignored)
│
├── .agent/
│   └── skills/
│       ├── setup/SKILL.md              # /setup - First-time installation
│       ├── customize/SKILL.md          # /customize - Add capabilities
│       ├── debug/SKILL.md              # /debug - Jail debugging
│       ├── add-telegram/SKILL.md       # /add-telegram - Telegram channel
│       ├── add-gmail/SKILL.md          # /add-gmail - Gmail integration
│       ├── add-voice-transcription/    # /add-voice-transcription - Whisper
│       ├── x-integration/SKILL.md      # /x-integration - X/Twitter
│       └── add-parallel/SKILL.md       # /add-parallel - Parallel agents
│
├── groups/
│   ├── AGENTS.md                 # Global memory (all groups read this)
│   ├── main/                      # Self-chat (main control channel)
│   │   ├── AGENTS.md             # Main channel memory
│   │   └── logs/                  # Task execution logs
│   └── {Group Name}/              # Per-group folders (created on registration)
│       ├── AGENTS.md             # Group-specific memory
│       ├── logs/                  # Task logs for this group
│       └── *.md                   # Files created by the agent
│
├── store/                         # Local data (gitignored)
│   ├── messages.db                # SQLite database
│   └── messages.db                # SQLite database (messages, chats, scheduled_tasks, task_run_logs, registered_groups, sessions, router_state)
│
├── data/                          # Application state (gitignored)
│   ├── sessions/                  # Per-group session data (.agent/ dirs with JSONL transcripts)
│   ├── env/env                    # Copy of .env for jail-side auth bootstrap
│   └── ipc/                       # Jail IPC (messages/, tasks/)
│
├── logs/                          # Runtime logs (gitignored)
│   ├── nanoclaw.log               # Host stdout
│   └── nanoclaw.error.log         # Host stderr
│   # Note: Per-jail logs are in groups/{folder}/logs/jail-*.log
│
└── launchd/
    └── com.nanoclaw.plist         # macOS service configuration

Configuration

Configuration constants are in src/config.ts:

import path from 'path';

export const ASSISTANT_NAME = process.env.ASSISTANT_NAME || 'Andy';
export const POLL_INTERVAL = 2000;
export const SCHEDULER_POLL_INTERVAL = 60000;

// Paths are absolute (required for jail mounts)
const PROJECT_ROOT = process.cwd();
export const STORE_DIR = path.resolve(PROJECT_ROOT, 'store');
export const GROUPS_DIR = path.resolve(PROJECT_ROOT, 'groups');
export const DATA_DIR = path.resolve(PROJECT_ROOT, 'data');

// Jail configuration
export const JAIL_TIMEOUT = parseInt(process.env.JAIL_TIMEOUT || '1800000', 10); // 30min default
export const IPC_POLL_INTERVAL = 1000;
export const IDLE_TIMEOUT = parseInt(process.env.IDLE_TIMEOUT || '1800000', 10); // 30min — keep jail alive after last result
export const MAX_CONCURRENT_JAILS = Math.max(1, parseInt(process.env.MAX_CONCURRENT_JAILS || '5', 10) || 5);

export const TRIGGER_PATTERN = new RegExp(`^@${ASSISTANT_NAME}\\b`, 'i');

Note: Paths must be absolute for jail mounts to work correctly.

Jail Configuration

Groups can have additional directories mounted via jailConfig in the SQLite registered_groups table (stored as JSON in the jail_config column). Example registration:

registerGroup("1234567890@g.us", {
  name: "Dev Team",
  folder: "dev-team",
  trigger: "@Andy",
  added_at: new Date().toISOString(),
  jailConfig: {
    additionalMounts: [
      {
        hostPath: "~/projects/webapp",
        jailPath: "webapp",
        readonly: false,
      },
    ],
    timeout: 600000,
  },
});

Additional mounts appear at /workspace/extra/{jailPath} inside the jail.

Mount syntax note: Read-write mounts use -v host:container, but readonly mounts require --mount "type=bind,source=...,target=...,readonly" (the :ro suffix may not work on all runtimes).

Provider Authentication

Configure provider credentials in a .env file in the project root. Example:

OPENROUTER_API_KEY=sk-or-...
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-...

Only the provider variables needed by the selected runtime are passed into the jail worker. This ensures unrelated environment variables in .env are not exposed to the agent.

Changing the Assistant Name

Set the ASSISTANT_NAME environment variable:

ASSISTANT_NAME=Bot npm start

Or edit the default in src/config.ts. This changes:

  • The trigger pattern (messages must start with @YourName)
  • The response prefix (YourName: added automatically)

Placeholder Values in launchd

Files with {{PLACEHOLDER}} values need to be configured:

  • {{PROJECT_ROOT}} - Absolute path to your nanoclaw installation
  • {{NODE_PATH}} - Path to node binary (detected via which node)
  • {{HOME}} - User's home directory

Memory System

Clawdie uses a hierarchical memory system based on AGENTS.md files.

Memory Hierarchy

Level Location Read By Written By Purpose
Global groups/global/AGENTS.md All groups Main only Preferences, facts, context shared across all conversations
Group groups/{name}/AGENTS.md That group That group Group-specific context, conversation memory
Files groups/{name}/*.md That group That group Notes, research, documents created during conversation

How Memory Works

  1. Agent Context Loading

    • Agent runs with cwd set to groups/{group-name}/
    • The agent runtime loads:
      • ../global/AGENTS.md or /workspace/global/AGENTS.md (global memory)
      • ./AGENTS.md (group memory)

  2. Writing Memory

    • When user says "remember this", agent writes to ./AGENTS.md
    • When user says "remember this globally" (main channel only), agent writes to the global AGENTS.md
    • Agent can create files like notes.md, research.md in the group folder

  3. Main Channel Privileges

    • Only the "main" group (self-chat) can write to global memory
    • Main can manage registered groups and schedule tasks for any group
    • Main can configure additional directory mounts for any group
    • All groups have Bash access (safe because it runs inside the jail)

Session Management

Sessions enable conversation continuity - the agent remembers what you talked about.

How Sessions Work

  1. Each group has a session ID stored in SQLite (sessions table, keyed by group_folder)
  2. Session ID is passed to the runtime's resume option
  3. The agent continues the conversation with full context
  4. Session transcripts are stored as JSONL files in data/sessions/{group}/.agent/

Message Flow

Incoming Message Flow

1. User sends a Telegram message
   │
   ▼
2. Telegram bot receives the message via the Bot API
   │
   ▼
3. Message stored in SQLite (store/messages.db)
   │
   ▼
4. Message loop polls SQLite (every 2 seconds)
   │
   ▼
5. Router checks:
   ├── Is chat_jid in registered groups (SQLite)? → No: ignore
   └── Does message match trigger pattern? → No: store but don't process
   │
   ▼
6. Router catches up conversation:
   ├── Fetch all messages since last agent interaction
   ├── Format with timestamp and sender name
   └── Build prompt with full conversation context
   │
   ▼
7. Router invokes the jail-side agent runtime:
   ├── cwd: groups/{group-name}/
   ├── prompt: conversation history + current message
   ├── resume: session_id (for continuity)
   └── mcpServers: nanoclaw (scheduler)
   │
   ▼
8. Agent processes message:
   ├── Reads AGENTS.md files for context
   └── Uses tools as needed (search, email, etc.)
   │
   ▼
9. Router prefixes response with assistant name and sends via the channel
   │
   ▼
10. Router updates last agent timestamp and saves session ID

Trigger Word Matching

Messages must start with the trigger pattern (default: @Andy):

  • @Andy what's the weather? → ✅ Triggers Claude
  • @andy help me → ✅ Triggers (case insensitive)
  • Hey @Andy → ❌ Ignored (trigger not at start)
  • What's up? → ❌ Ignored (no trigger)

Conversation Catch-Up

When a triggered message arrives, the agent receives all messages since its last interaction in that chat. Each message is formatted with timestamp and sender name:

[Jan 31 2:32 PM] John: hey everyone, should we do pizza tonight?
[Jan 31 2:33 PM] Sarah: sounds good to me
[Jan 31 2:35 PM] John: @Andy what toppings do you recommend?

This allows the agent to understand the conversation context even if it wasn't mentioned in every message.

Commands

Commands Available in Any Group

Command Example Effect
@Assistant [message] @Andy what's the weather? Talk to Claude

Commands Available in Main Channel Only

Command Example Effect
@Assistant add group "Name" @Andy add group "Family Chat" Register a new group
@Assistant remove group "Name" @Andy remove group "Work Team" Unregister a group
@Assistant list groups @Andy list groups Show registered groups
@Assistant remember [fact] @Andy remember I prefer dark mode Add to global memory

Scheduled Tasks

NanoClaw has a built-in scheduler that runs tasks as full agents in their group's context.

How Scheduling Works

  1. Group Context: Tasks created in a group run with that group's working directory and memory
  2. Full Agent Capabilities: Scheduled tasks have access to all tools (WebSearch, file operations, etc.)
  3. Optional Messaging: Tasks can send messages to their group using the send_message tool, or complete silently
  4. Main Channel Privileges: The main channel can schedule tasks for any group and view all tasks

Schedule Types

Type Value Format Example
cron Cron expression 0 9 * * 1 (Mondays at 9am)
interval Milliseconds 3600000 (every hour)
once ISO timestamp 2024-12-25T09:00:00Z

Creating a Task

User: @Andy remind me every Monday at 9am to review the weekly metrics

Claude: [calls mcp__nanoclaw__schedule_task]
        {
          "prompt": "Send a reminder to review weekly metrics. Be encouraging!",
          "schedule_type": "cron",
          "schedule_value": "0 9 * * 1"
        }

Claude: Done! I'll remind you every Monday at 9am.

One-Time Tasks

User: @Andy at 5pm today, send me a summary of today's emails

Claude: [calls mcp__nanoclaw__schedule_task]
        {
          "prompt": "Search for today's emails, summarize the important ones, and send the summary to the group.",
          "schedule_type": "once",
          "schedule_value": "2024-01-31T17:00:00Z"
        }

Managing Tasks

From any group:

  • @Andy list my scheduled tasks - View tasks for this group
  • @Andy pause task [id] - Pause a task
  • @Andy resume task [id] - Resume a paused task
  • @Andy cancel task [id] - Delete a task

From main channel:

  • @Andy list all tasks - View tasks from all groups
  • @Andy schedule task for "Family Chat": [prompt] - Schedule for another group

MCP Servers

NanoClaw MCP (built-in)

The nanoclaw MCP server is created dynamically per agent call with the current group's context.

Available Tools:

Tool Purpose
schedule_task Schedule a recurring or one-time task
list_tasks Show tasks (group's tasks, or all if main)
get_task Get task details and run history
update_task Modify task prompt or schedule
pause_task Pause a task
resume_task Resume a paused task
cancel_task Delete a task
send_message Send a message to the group

Deployment

NanoClaw runs as a single macOS launchd service.

Startup Sequence

When NanoClaw starts, it:

  1. Ensures jail runtime is ready - Checks jail tooling and reports stale jail artifacts from previous runs
  2. Initializes the SQLite database (migrates from JSON files if they exist)
  3. Loads state from SQLite (registered groups, sessions, router state)
  4. Connects to Telegram:
    • Starts the scheduler loop
    • Starts the IPC watcher for jail messages
    • Sets up the per-group queue with processGroupMessages
    • Recovers any unprocessed messages from before shutdown
    • Starts the message polling loop

Service: com.nanoclaw

launchd/com.nanoclaw.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "...">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.nanoclaw</string>
    <key>ProgramArguments</key>
    <array>
        <string>{{NODE_PATH}}</string>
        <string>{{PROJECT_ROOT}}/dist/index.js</string>
    </array>
    <key>WorkingDirectory</key>
    <string>{{PROJECT_ROOT}}</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>{{HOME}}/.local/bin:/usr/local/bin:/usr/bin:/bin</string>
        <key>HOME</key>
        <string>{{HOME}}</string>
        <key>ASSISTANT_NAME</key>
        <string>Andy</string>
    </dict>
    <key>StandardOutPath</key>
    <string>{{PROJECT_ROOT}}/logs/nanoclaw.log</string>
    <key>StandardErrorPath</key>
    <string>{{PROJECT_ROOT}}/logs/nanoclaw.error.log</string>
</dict>
</plist>

Managing the Service

# Install service
cp launchd/com.nanoclaw.plist ~/Library/LaunchAgents/

# Start service
launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist

# Stop service
launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist

# Check status
launchctl list | grep nanoclaw

# View logs
tail -f logs/nanoclaw.log

Security Considerations

Jail Isolation

All agents run inside containers (lightweight Linux VMs), providing:

  • Filesystem isolation: Agents can only access mounted directories
  • Safe Bash access: Commands run inside the jail, not on the host
  • Network isolation: Can be configured per-jail if needed
  • Process isolation: Container processes can't affect the host
  • Non-root user: Container runs as unprivileged node user (uid 1000)

Prompt Injection Risk

Incoming channel messages could contain malicious instructions attempting to manipulate the agent's behavior.

Mitigations:

  • Jail isolation limits blast radius
  • Only registered groups are processed
  • Trigger word required (reduces accidental processing)
  • Agents can only access their group's mounted directories
  • Main can configure additional directories per group
  • Claude's built-in safety training

Recommendations:

  • Only register trusted groups
  • Review additional directory mounts carefully
  • Review scheduled tasks periodically
  • Monitor logs for unusual activity

Credential Storage

Credential Storage Location Notes
Claude CLI Auth data/sessions/{group}/.agent/ Per-group isolation, mounted to /home/node/.agent/
Telegram Bot Token .env Verified via setup/telegram-auth.ts

File Permissions

The groups/ folder contains personal memory and should be protected:

chmod 700 groups/

Troubleshooting

Common Issues

Issue Cause Solution
No response to messages Service not running Check `launchctl list
"Agent process exited with code 1" Jail runtime failed to start Check logs; Clawdie reports jail startup failures in logs/clawdie.log
"Agent process exited with code 1" Session mount path wrong Ensure mount is to /home/node/.agent/ not /root/.agent/
Session not continuing Session ID not saved Check SQLite: sqlite3 store/messages.db "SELECT * FROM sessions"
Session not continuing Mount path mismatch Container user is node with HOME=/home/node; sessions must be at /home/node/.agent/
"TELEGRAM_BOT_TOKEN is not set" Telegram bot token missing Set TELEGRAM_BOT_TOKEN in .env and restart
"No groups registered" Haven't added groups Use @Andy add group "Name" in main

Log Location

  • logs/nanoclaw.log - stdout
  • logs/nanoclaw.error.log - stderr

Debug Mode

Run manually for verbose output:

npm run dev
# or
node dist/index.js