mirror of https://github.com/Ark0N/Codeman.git synced 2026-09-30 20:49:41 +02:00

Files

T

arkonandClaude Opus 4.5 1cb5e62cc2 docs: extract respawn and spawn protocol details into dedicated docs

Condense CLAUDE.md by moving detailed state machine diagrams and spawn
protocol specs into docs/respawn-state-machine.md and docs/spawn-protocol.md.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-24 19:47:07 +01:00

2.9 KiB

Raw Blame History

Spawn1337 Protocol (Autonomous Agents)

Spawned agents are full-power Claude sessions running in their own screen sessions. They communicate via a filesystem-based message bus and signal completion via RalphTracker's <promise> mechanism.

Primary Interface: MCP Server

The claudeman-mcp binary exposes spawn tools to Claude Code via MCP protocol, replacing the legacy terminal-tag-parsing approach (SpawnDetector).

MCP Tools

Tool	Description
`spawn_agent`	Spawn a new autonomous agent (builds task spec from parameters)
`list_agents`	List all agents (active + completed + queued)
`get_agent_status`	Get detailed agent status + progress
`get_agent_result`	Read a completed agent's result
`send_agent_message`	Send a message to a running agent
`cancel_agent`	Cancel a running agent

Environment Variables

Variable	Description
`CLAUDEMAN_API_URL`	Base URL for the Claudeman API (default: `http://localhost:3000`)
`CLAUDEMAN_SESSION_ID`	Session ID of the calling Claude session

Protocol Flow

Claude calls spawn_agent MCP tool
  → MCP server builds task spec YAML
  → POST /api/spawn/trigger with task spec
  → SpawnOrchestrator creates agent directory: ~/claudeman-cases/spawn-<agentId>/
  → Spawns interactive Claude session in screen
  → Injects initial prompt via writeViaScreen()
  → Agent works autonomously, writes progress to spawn-comms/
  → RalphTracker detects <promise>PHRASE</promise> on child
  → Orchestrator reads result.md, notifies parent via SSE

Agent Directory Structure

Each agent gets: ~/claudeman-cases/spawn-<agentId>/

spawn-<agentId>/
├── CLAUDE.md              # Generated from spawn-claude-md.ts
├── spawn-comms/
│   ├── task.md            # Task specification
│   ├── progress.json      # Current progress state
│   ├── result.md          # Final result (on completion)
│   └── messages/          # Inter-agent messaging
└── workspace/             # Symlinked context files

Resource Governance

Limit	Value
Max concurrent agents	5
Max depth	3
Default timeout	30min
Max timeout	120min
Budget warning	80%
Graceful shutdown	100%
Force kill	110%

Agent Tree

Agents can spawn children. Sessions track parentAgentId and childAgentIds. Cancelling a parent cascades to all children.

Key Source Files

File	Purpose
`src/mcp-server.ts`	MCP server binary exposing spawn tools
`src/spawn-orchestrator.ts`	Full agent lifecycle: spawn, monitor, budget, queue, cleanup
`src/spawn-claude-md.ts`	Generates CLAUDE.md for spawned agent sessions
`src/spawn-types.ts`	Types, YAML parser, factory functions
`src/spawn-detector.ts`	Legacy: detects `<spawn1337>` tags in terminal output

2.9 KiB Raw Blame History