cc-mesh

Spawn and orchestrate full-power Claude Code / Codex instances from your terminal. A local relay (port 19800) handles peer messaging, terminal injection (AppleScript / tmux), node registry, and a shared KV blackboard.

Install

npm install -g @aster110/cc-mesh

Requires Node.js >= 18, tmux, and a C++ toolchain for better-sqlite3 (Xcode CLT on macOS). On macOS, spawning into iTerm tabs requires iTerm2.

Quick Start

# 1. Install the Claude Code skill (optional but recommended)
mesh skill install

# 2. Start the local relay
mesh relay start
mesh relay status

# 3. Create an agent profile (machine-local config)
mkdir -p ~/.ccmesh/agents
cat > ~/.ccmesh/agents/tcc.json <<'EOF'
{
  "name": "tcc",
  "launcher": "cc",
  "cwd": "/path/to/your/workspace",
  "terminal": "tmux",
  "autoInit": true
}
EOF

# 4. Register yourself, then spawn a worker
mesh init main "lead"        # run inside an interactive iTerm/tmux session
export MESH_NODE=<printed nodeId>
mesh spawn --agent tcc

mesh spawn only performs the naming + handshake. After the worker reports [bootstrap][ready], dispatch work explicitly:

mesh send <worker-nodeId> "your task..."

Commands

mesh send / inbox / status / broadcast / context / devices
mesh init / register / unregister / heartbeat
mesh spawn --agent <profile> [--on <device>] [--window] [--dir <path>] [--lead <nodeId>]
mesh kv set / get / list / del
mesh relay start / stop / restart / status / logs
mesh skill install [--force]

Multi-machine Hub (optional)

By default cc-mesh runs in local-only mode and connects to nothing. To join multiple machines, deploy your own hub (WS routing center) and point the relay at it:

echo 'ws://<your-hub-host>:19900' > ~/.ccmesh/hub-url
mesh relay restart

Or set MESH_HUB_URL (empty string = explicitly disabled). Cross-region nodes can route the uplink through a local HTTP proxy via MESH_HTTPS_PROXY.

Data

All runtime state lives in ~/.ccmesh/: db/mesh.db (SQLite audit + KV), context/, agents/, relay.pid, hub-url.