English | 中文 | 日本語

Agent Matrix framework — run a supervised network of Claude Code or Codex agents that collaborate on your machine.

wanman is an open-source local-mode agent matrix framework. Runs a supervised network of Claude Code or Codex agents on your machine, coordinated through a JSON-RPC supervisor.

The name wanman comes from the Japanese ワンマン電車 / one-man train: a train operated by one driver without a conductor. wanman's design goal is similar in spirit: the human user steps back into an observer role and watches the agent matrix run automatically from every angle.

wanman.ai provides the fully automated 24/7 sandbox edition of wanman, running for free on Sandbank Cloud's sandbox cloud.

• Coordinates multiple agents (CEO, dev, devops, marketing, feedback, etc.) through an async message bus with steer/follow-up priorities.
• Runs each agent as a real Claude Code or Codex CLI subprocess — you bring your own CLI auth, wanman orchestrates spawning, prompting, and lifecycle.
• Isolates every agent in a per-agent worktree and per-agent $HOME, so agents never mutate your dirty checkout or shell profile.
• Is CLI-first: everything is scriptable, observable, and reproducible through wanman commands and a JSON-RPC supervisor.

wanman.ai adds hosted-only capabilities:

• Isolates each agent runtime group in its own sandbox environment, supporting large-scale, high-concurrency task execution.
• Dynamically configures agent roles, including automatically extracting roles from high-quality agent role catalogs on the internet.
• Supports dynamic skill self-evolution.
• Supports db9-powered global search and story retrieval.

# Prerequisites: Node 20+, pnpm 9+, git, a logged-in Claude Code or Codex CLI.
git clone git@github.com:chekusu/wanman.git wanman.dev
cd wanman.dev
pnpm install
pnpm build
# Run from source; no npm package publish is required.
pnpm --filter @wanman/cli exec wanman takeover /path/to/any/git/repo

If you want a single-file CLI bundle instead:

pnpm --filter @wanman/cli standalone
node packages/cli/dist/wanman.mjs takeover /path/to/any/git/repo

If wanman is already on your PATH, you can also run wanman takeover . from inside the target repository.

See docs/quickstart.md for the full walkthrough.

Run wanman --help for the full, current list.

+----------------+ +--------------------+ +-----------------+
| wanman CLI | JSON | Supervisor | spawn | Agent process |
| (host shell) | ---RPC-->| (local process) | -------> | (Claude/Codex) |
| | /rpc | message/context/ | | per-agent $HOME|
| | | task/artifact | | per-agent wt |
+----------------+ +--------------------+ +-----------------+
 | |
 v v
 +--------------------+ +-----------------+
 | files + SQLite | | worktree |
 +--------------------+ +-----------------+

• wanman <subcommand> speaks JSON-RPC 2.0 to a Supervisor process.
• The Supervisor owns the message store, context store, task pool, artifact store, and spawns one child process per agent.
• Each agent child is a local Claude Code or Codex subprocess bound to a per-agent worktree and isolated $HOME.

Deep dive: docs/architecture.md.

An optional @sandbank.dev/db9 brain adapter can be attached for cross-run memory — see docs/architecture.md.

Agent definitions live in a single JSON file:

{
 "agents": [
 { "name": "echo", "lifecycle": "24/7", "model": "standard", "systemPrompt": "..." },
 { "name": "ping", "lifecycle": "on-demand", "model": "standard", "systemPrompt": "..." }
 ],
 "dbPath": ".wanman/wanman.db",
 "port": 3120,
 "workspaceRoot": ".wanman/agents"
}

Each agent entry has:

• name — unique identifier used on the message bus.
• lifecycle — 24/7 (continuous respawn loop), on-demand (idle until triggered), or idle_cached (idle until triggered, but the prior Claude session_id is preserved across triggers via claude --resume so context survives idle periods). idle_cached is Claude-only: pairing it with runtime: codex (or WANMAN_RUNTIME=codex) is rejected at startup since Codex has no equivalent resume mechanism in this runtime.
• model — usually an abstract tier (high or standard); the runtime adapter maps it to Claude or Codex defaults, with environment overrides available.
• systemPrompt — baked-in persona/mission; agents also auto-discover shared skill files at ~/.claude/skills/.
• Optional cron, events, and tools fields — see the architecture doc for the full schema.

pnpm typecheck
pnpm test
pnpm exec vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary --coverage.exclude='**/dist/**'

The current coverage target is at least 90% line coverage. The latest verified local run reports Lines: 90.17%; the machine-readable summary is written to coverage/coverage-summary.json.

wanman.dev/
 packages/
 cli/ wanman CLI (send/recv/task/artifact/run/takeover/...)
 core/ Shared types, JSON-RPC protocol, skills (core/skills/)
 host-sdk/ Host-side SDK for embedding wanman into other tools
 runtime/ Supervisor, agent process manager, SQLite stores, adapters
 docs/ Architecture and quickstart guides

Shared skills shipped today (packages/core/skills/):

• artifact-naming, artifact-quality — conventions for agent-produced artifacts.
• cross-validation — CEO consistency checks across agent outputs.
• research-methodology — market/data research methodology.
• wanman-cli — CLI command reference consumed by agents at runtime.
• workspace-conventions — file-system conventions inside agent workspaces.

• Quickstart — first-run walkthrough against any git repo.
• Architecture — agent lifecycle, JSON-RPC, stores, adapters.
• Contributing — tests, typecheck, commit conventions.

Apache-2.0 — see LICENSE.