git clone git@github.com:chekusu/wanman.git wanman.dev
cd wanman.dev
pnpm install
pnpm build

# Run the CLI directly
pnpm --filter @wanman/cli exec wanman takeover /path/to/any/git/repo

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

# Example: add to PATH via shell profile
export PATH="$PATH:/path/to/wanman.dev/packages/cli/dist"
# Then from inside any git repo:
wanman takeover .

# Supervisor HTTP URL for the CLI (default: http://localhost:3120)
export WANMAN_URL=http://localhost:3120

# Identifies the current agent (set inside agent processes)
export WANMAN_AGENT_NAME=dev

# Select runtime: 'claude' (default) or 'codex'
export WANMAN_RUNTIME=claude

# Model overrides
export WANMAN_MODEL=claude-opus-4-5
export WANMAN_CODEX_MODEL=o4-mini
export WANMAN_CODEX_REASONING_EFFORT=high

# Bias Codex adapter toward lower-latency defaults
export WANMAN_CODEX_FAST=1

# Override where runtime materializes skill-activation snapshots
export WANMAN_SKILL_SNAPSHOTS_DIR=/tmp/my-skill-snapshots

{
  "agents": [
    {
      "name": "ceo",
      "lifecycle": "24/7",
      "model": "high",
      "systemPrompt": "You are the CEO agent. Coordinate all other agents, prioritize tasks, and escalate blockers."
    },
    {
      "name": "dev",
      "lifecycle": "on-demand",
      "model": "standard",
      "systemPrompt": "You are the dev agent. Implement features, fix bugs, and write tests."
    },
    {
      "name": "devops",
      "lifecycle": "on-demand",
      "model": "standard",
      "systemPrompt": "You are the devops agent. Manage CI/CD, infrastructure, and deployments."
    },
    {
      "name": "researcher",
      "lifecycle": "idle_cached",
      "model": "standard",
      "systemPrompt": "You are the research agent. Gather market data and synthesize findings."
    }
  ],
  "dbPath": ".wanman/wanman.db",
  "port": 3120,
  "workspaceRoot": ".wanman/agents"
}

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

# From inside the repo you want agents to work on:
cd /path/to/my-project
wanman takeover .

# Watch the agents coordinate in real time:
wanman watch

# Launch agents against a specific goal
wanman run "Refactor the authentication module to use JWT tokens"

# In another terminal, watch activity stream
wanman watch

# Check agent states
wanman agents

# Escalate to CEO if blocked
wanman escalate "Dev agent is stuck on the JWT library choice, please decide"

# Send a normal message to the dev agent
wanman send dev "Please add unit tests for the UserService class"

# Send a steering (interrupt) message to the dev agent
wanman send dev --steer "STOP current task. Critical bug in auth — fix login endpoint first"

# Receive messages as the dev agent
WANMAN_AGENT_NAME=dev wanman recv

# Receive all pending messages for any agent
wanman recv

# Create a task with a dependency on task ID abc123
wanman task create \
  --title "Write integration tests" \
  --description "Cover all API endpoints with integration tests" \
  --agent dev \
  --after abc123

# List all tasks and their statuses
wanman task list

# Get details of a specific task
wanman task get <task-id>

# Update task status
wanman task update <task-id> --status in-progress

# Mark complete
wanman task done <task-id>

# Store shared context accessible to all agents
wanman context set api_base_url "https://api.example.com/v2"
wanman context set target_environment "staging"

# Read context values
wanman context get api_base_url

# Agents read context in their prompts automatically via the supervisor

# Store a structured artifact (e.g., research output)
wanman artifact put \
  --name "market-analysis-q2" \
  --type "report" \
  --content "$(cat analysis.md)"

# List artifacts
wanman artifact list

# Retrieve a specific artifact
wanman artifact get <artifact-id>

# Create a hypothesis for agents to validate
wanman hypothesis create \
  --title "Switching to Bun runtime reduces build time by 40%" \
  --description "Based on benchmarks from similar TypeScript projects"

# List hypotheses and their validation status
wanman hypothesis list

# Update after validation
wanman hypothesis update <id> --status confirmed --evidence "Build time dropped from 45s to 26s"

# Create a change capsule (bounded unit of work/change)
wanman capsule create \
  --title "Auth JWT migration" \
  --description "Migrate session-based auth to JWT"

# List all capsules
wanman capsule list

# List capsules owned by the current agent
WANMAN_AGENT_NAME=dev wanman capsule mine

# Get details
wanman capsule get <capsule-id>

import { WanmanClient } from '@wanman/host-sdk';

// Connect to a running supervisor
const client = new WanmanClient({
  url: process.env.WANMAN_URL ?? 'http://localhost:3120',
});

// Send a message programmatically
await client.send({
  agent: 'dev',
  message: 'Please review the PR and add inline comments',
  steer: false,
});

// Create a task
const task = await client.task.create({
  title: 'Fix flaky tests',
  description: 'Tests in auth.test.ts fail intermittently under CI',
  agent: 'dev',
});

// Poll for agent status
const agents = await client.agents.list();
for (const agent of agents) {
  console.log(`${agent.name}: ${agent.state}`);
}

// Store an artifact
await client.artifact.put({
  name: 'perf-baseline',
  type: 'benchmark',
  content: JSON.stringify(perfResults),
});

// Read shared context
const env = await client.context.get('target_environment');

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/
    quickstart.md
    architecture.md
  CONTRIBUTING.md

# Check that skill docs only reference real CLI commands
wanman skill:check
wanman skill:check packages/core/skills/wanman-cli.md

# Type checking
pnpm typecheck

# Run all tests
pnpm test

# Run tests with coverage (target: 90%+ line coverage)
pnpm exec vitest run \
  --coverage \
  --coverage.reporter=text-summary \
  --coverage.reporter=json-summary \
  --coverage.exclude='**/dist/**'

# Coverage summary written to: coverage/coverage-summary.json

# Check if supervisor is running on expected port
curl http://localhost:3120/rpc

# Override URL if running on a non-default port
export WANMAN_URL=http://localhost:4000
wanman agents

# Check agent states
wanman agents

# Send a steer message to interrupt and redirect
wanman send <agent-name> --steer "Reset and await new instructions"

# Escalate to CEO for intervention
wanman escalate "Agent 'dev' appears stuck on task <task-id>, please reassign"

# Watch live activity to diagnose
wanman watch

Error: idle_cached lifecycle requires Claude runtime; codex has no resume mechanism

# Stop all wanman processes
pkill -f wanman

# Remove WAL files if present
rm .wanman/wanman.db-wal .wanman/wanman.db-shm

# Restart supervisor
wanman takeover .

# Run skill:check to find references to non-existent commands
wanman skill:check

# Output will show which skill files reference invalid commands
# Update the skill markdown to use only real wanman CLI commands