SeedClaw

Small seed. Infinite skills. Sharp claws.

A minimal claw — a personal AI agent system that runs Claude Code CLI in Docker containers, orchestrated from your terminal.

~1,800 lines of TypeScript. One runtime dependency (Zod). No config files.

My use case

I work on many projects in different languages (TypeScript, Zig, ...) and domains (web, embedded, ...), each with its own toolchain. I'm often on the go without access to my MacBook but I still want to talk to agents that have my projects checked out, tools installed, and are ready to work.

SeedClaw gives each project its own isolated container with persistent state. I connect from wherever I am through whatever client I want. No uncontrolled processes on my laptop, no need for a dedicated machine.

Why another claw?

OpenClaw pioneered the concept but has a large surface area — big config files, lots of code, hard to audit. It wasn't clear to me how to use it with a Claude Code subscription without violating the terms of service (vs. pay-per-use API access).

NanoClaw brought great ideas: small codebase, Docker isolation, skills over features. But it uses the Claude Agent SDK under the hood, which isn't covered by a Claude Code subscription. It also bakes in WhatsApp support where I wanted something more modular.

SeedClaw takes the best ideas and strips them down further:

• Subscription-safe. Uses claude -p (the CLI), not the SDK. Works with your existing Claude Code subscription — no API key, no extra cost, no risk of violating terms.
• Tiny and auditable. You can read the entire codebase in an afternoon. REQUIREMENTS.md documents every invariant, so you (and your agents) know exactly how the system should behave.
• Docker-isolated. Every agent runs in its own persistent container. Install tools, configure environments — it all survives across restarts.
• Skills, not features. Need a web UI? A WhatsApp client? Don't wait for a PR — use a skill to have your agent generate it as a plugin. Each installation grows into something unique.

How it works

You ──► CLI ──► Host ──► Docker container ──► claude -p
                 │
                 ├── Agent management (create, delete, reset)
                 ├── Plugin loader (client-*)
                 └── IPC (file-based, Zod-validated)

The host is a Node.js process that manages agents and routes messages. Each agent runs Claude Code CLI inside a Docker container. Communication between host and containers happens through atomic file-based IPC — no shared runtime state.

A built-in CLI client is included for terminal interaction. Additional clients (web, WhatsApp, Telegram, ...) are added as plugins — generated by agents using skills, not hand-coded into the core.

Interaction

All input goes through whichever client you're using (CLI, web, WhatsApp, ...):

• @agent message to talk to a specific agent
• Bare text goes to @main (auto-created, permanent)
• /help to see all available commands (create/delete agents, reload plugins, ...)

Skills and plugins

Skills are instruction files (.claude/skills/<name>/SKILL.md) that tell agents how to generate plugins. For example, the included create-client-web skill lets the main agent generate a browser-based chat UI as a plugin — complete with WebSocket streaming and a dark-themed interface.

Plugins live in plugins/ (gitignored). They're self-contained packages with their own dependencies. A broken plugin logs an error and is skipped — it never crashes the host.

This means: no complex configs, no generic features trying to cover every use case. Your agents write the code you need, and you can customize or regenerate it anytime. Code generation is cheap — personalization is the point.

Agents and personality

The main agent is created automatically and receives all messages not addressed to a specific agent. It comes with its own CLAUDE.md that defines its role. All other agents start with an empty CLAUDE.md — you shape their personality by talking to them. Just ask an agent to write instructions to its CLAUDE.md and they'll persist across restarts (until you delete the agent).

IPC

Host and containers don't share a runtime — they communicate through atomic file-based IPC. The host delivers a startup payload via stdin when starting a container. The agent writes event files (results, session IDs, log messages) to its IPC output directory; the host polls and drains them. All files are written atomically (write to .tmp, rename to .json) and validated with Zod on both sides. IPC is output-only — there are no host→container messages after startup.

Persistent containers

Agent containers are created once and reused across sessions. Anything an agent installs (git, language runtimes, dev tools) persists until the agent is deleted. Future skills could automate common setups (e.g., a setup-github skill that configures auth and SSH keys).

Getting started

Prerequisites: Node.js 24+, Docker

macOS users: Docker Desktop runs containers inside a VM with limited resources. Claude Code needs significant memory to install and run. Open Docker Desktop settings and increase RAM to at least half your system memory, and assign enough CPU cores to keep things responsive.

1. Install and authenticate Claude Code

npm install -g @anthropic-ai/claude-code
claude login    # subscription — or set ANTHROPIC_API_KEY for API access

2. Clone, install, and build

git clone https://github.com/clebert/seedclaw.git
cd seedclaw
npm install
npm run build:container

3. Start

npm start

SeedClaw resolves credentials at startup and fails immediately if none are found.

4. Implement the Web Client

SeedClaw ready.
> Hello please implement the /create-client-web skill
> /status
[main] config: model=default
  active: yes (container running)
  session: fa75d515-299c-4b40-951b-fb3146ef5921
  context: 0%
[main] Running npm install in plugins/client-web/
[main] npm install completed in plugins/client-web/
[main] Done. The `client-web` plugin has been generated with three files:

- `plugins/client-web/package.json` — declares the `ws` and `seedclaw` dependencies
- `plugins/client-web/src/index.ts` — HTTP + WebSocket server; subscribes to host broadcasts and routes incoming messages to `host.handleInput`
- `plugins/client-web/ui/index.html` — single-file dark UI with chat bubbles, activity bar with pulsing dot, auto-resize textarea, Enter-to-send, and auto-reconnecting WebSocket

npm install has been triggered on the host. Next steps:

1. Type `/reload-plugins` in your client to load the plugin
2. Open `http://localhost:3000` in a browser
> /reload-plugins
Reloading plugins...
Web client listening at http://localhost:3000
Plugin loaded: client-web
Plugins reloaded.

Development

npm start                # run
npm run dev              # run with hot reload
npm run check            # TypeScript type-check
npm run build:container  # rebuild agent container image

# Both start and dev accept a log level flag (default: info):
npm start -- --log-level=debug    # debug | info | warn | error
npm run dev -- --log-level=debug

Stack

• TypeScript on Node.js 24+ (native execution via --experimental-strip-types, no build step)
• Zod for schema validation (the only runtime dependency)
• SQLite via node:sqlite (built-in)
• Docker for agent isolation

Architecture reference

See REQUIREMENTS.md for the full list of invariants that govern authentication, IPC, container lifecycle, cleanup, and plugin loading.