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.

CLI commands

| Command | What it does | |---------|--------------| | wanman send <agent> <msg> | Send a message to an agent (--steer interrupts the target). | | wanman recv [--agent <name>] | Receive and mark pending messages as delivered. | | wanman agents | List registered agents and their current states. | | wanman context get / context set | Read or write shared key/value context. | | wanman escalate <msg> | Escalate to the CEO agent. | | wanman task … | Manage the task pool: create, list, get, update, done. Supports --after dependencies. | | wanman initiative … | Manage long-lived initiatives: create, list, get, update. | | wanman capsule … | Manage change capsules: create, list, mine, get, update. | | wanman artifact … | Store and retrieve structured artifacts: put, list, get. | | wanman hypothesis … | Track hypotheses with status transitions: create, list, update. | | wanman watch | Live-stream supervisor and agent activity. | | wanman run <goal> | Start a matrix against a one-shot goal. | | wanman takeover <path> | Take over an existing git repo with the full agent matrix. | | wanman skill:check [path] | Validate that skill docs reference only real 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

| Env var | Meaning | |---------|---------| | WANMAN_URL | Supervisor HTTP URL for the CLI (default http://localhost:3120). | | WANMAN_AGENT_NAME | Identifies the current agent; used as default sender/receiver inside agent processes. | | WANMAN_RUNTIME | claude (default) or codex — selects the per-agent CLI adapter. | | WANMAN_MODEL, WANMAN_CODEX_MODEL, WANMAN_CODEX_REASONING_EFFORT | Per-runtime model overrides. | | WANMAN_CODEX_FAST | When set, biases the Codex adapter toward lower-latency defaults. | | WANMAN_SKILL_SNAPSHOTS_DIR | Override where the runtime materializes skill-activation snapshots (default: sibling of the shared-skills dir, falling back to $TMPDIR/wanman-skill-snapshots). |

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.