wanman

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.

About wanman

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.

What it does

• 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.
• Includes an experimental @wanman/finops toolkit for API credential inventory, provider cost sync, Stripe revenue sync, and product/company ROI summaries.

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.

Quickstart

# 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.

For cost and revenue accounting, see docs/finops.md. The local FinOps review app runs with pnpm --filter @wanman/finops dev -- --host 127.0.0.1 --port 4173.

CLI commands

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

Architecture

+----------------+          +--------------------+          +-----------------+
|  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.

Configuration

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

Agent configs

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.

Testing

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.

Project structure

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.

Further reading

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

License

Apache-2.0 — see LICENSE.