claude-operator
TypeScript MCP server that turns any Claude Code session into an autonomous operator — decomposes goals, spawns and coordinates worker sessions across multiple projects, manages persistent two-tier memory, enforces guardrails, and learns from retrospective human review.
Install
npm install -g claude-operator
claude-operator init
claude-operator start
init scaffolds ~/.claude-operator/ (SQLite DB, bus dir, config).
start launches the MCP server on stdio + dashboard at http://localhost:7373.
Wire into Claude Code
Add to your ~/.claude/settings.json:
{
"mcpServers": {
"claude-operator": {
"command": "claude-operator",
"args": ["start", "--mcp"]
}
}
}
Or point at the local dev build:
{
"mcpServers": {
"claude-operator": {
"command": "node",
"args": ["/path/to/claude-operator/packages/server/dist/server.js"]
}
}
}
Architecture
Operator session (Claude Code)
│ MCP tools (10)
▼
┌─────────────────────────────────┐
│ claude-operator MCP server │
│ ┌──────────┐ ┌─────────────┐ │
│ │ SQLite │ │ File bus │ │
│ │ WAL+FTS5│ │ heartbeat │ │
│ └──────────┘ └─────────────┘ │
│ ┌──────────────────────────┐ │
│ │ Monitor loop (30s poll) │ │
│ └──────────────────────────┘ │
└────────────┬────────────────────┘
│ spawn / bus read-write
┌────────┴────────┐
▼ ▼
Worker A Worker B
(git worktree) (git worktree)
operator/w-abc operator/w-def
Two-tier memory — tier-1 (volatile, auto-expire 30d) and tier-2 (durable, human-confirmed). Operator proposes classification; human confirms in dashboard (pending_classification=TRUE).
File bus — primary worker↔operator state channel. Workers write heartbeats to <bus-dir>/<worker-id>.json; monitor loop detects stale workers (no heartbeat >2min) and marks them failed.
Guardrails — JSON rules enforced before any tool call. Set via set_guardrail, inspected via get_guardrails.
Tool Reference
| Tool | Description |
|---|---|
assign_task | Create a task with goal, project path, priority, constraints |
spawn_worker | Launch a Claude Code worker (named or headless) on an isolated git worktree |
get_worker_status | Poll worker state, heartbeat age, current task |
complete_task | Mark task done, merge worktree branch, clean up |
search_memory | FTS5 full-text search across operator memory |
update_memory | Write/update a memory entry with tier + confidence |
set_guardrail | Add or update a guardrail rule |
get_guardrails | List active guardrail rules |
inject_instruction | Send an instruction to a running worker via file bus |
log_judgment_call | Record a human judgment call for retrospective learning |
Dashboard
http://localhost:7373 — task board, worker status, guardrail editor, memory browser, judgment call log, SSE log stream.
CLI
claude-operator init # scaffold config + DB
claude-operator start # start MCP server + dashboard
claude-operator status # print active workers + tasks
claude-operator retro # open judgment call log
Dev
git clone https://github.com/MoyGulati/claude-operator
cd claude-operator
pnpm install
pnpm build
pnpm test # 39 tests
./verify.sh # full gate (build + test)
Requirements: Node 24+, pnpm 10+.
License
MIT