Understanding LLM Execution

LLMs operate in a turn-based execution model, similar to a game of chess or a D&D session.

↓ scroll down for details ↓

Anatomy of a Turn

Turn Limits & Session Resume

To prevent runaway agents and control costs, Captain enforces max turns per task:

if (err instanceof MaxTurnsError) {
  await taskQueue.updateMetadata(task.id, {
    resumeSessionId: err.sessionId,  // Claude SDK session
    lastTurnsUsed: err.turnsUsed,
  });
  await taskQueue.requeue(task.id, "max_turns", 5);
}

The Agent Fleet

Captain orchestrates four specialized agent types, each with distinct responsibilities:

↓ scroll down for each agent ↓

Coordinator

# User submits task
captain add "Add user authentication"

# Coordinator creates epic
{
  id: "task-abc123",
  type: "epic",
  title: "Add user authentication",
  status: "pending",
  priority: 2
}

Planner

{
  "tasks": [
    {
      "title": "Create User model",
      "type": "task",
      "group": "auth-models",
      "acceptance": "User model with email, hash"
    },
    {
      "title": "Add JWT middleware",
      "depends_on": ["Create User model"],
      "group": "auth-middleware"
    },
    {
      "title": "Create login endpoint",
      "depends_on": ["Add JWT middleware"]
    }
  ]
}

Worker

.captain/
├── worktrees/
│   ├── worker-0/   # Full repo checkout
│   │   └── src/
│   ├── worker-1/   # Full repo checkout
│   │   └── src/
│   └── worker-2/   # Full repo checkout
│       └── src/
└── session-state/

Validator

{
  "decision": "approve",
  "reasoning": "Implementation matches spec...",
  "discoveries": [
    {
      "type": "pattern",
      "content": "Auth middleware uses...",
      "files": ["src/middleware/auth.ts"]
    }
  ],
  "suggestions": []
}

System Architecture

↓ scroll down for detailed data flow ↓

Data Flow

Task Dependencies

The planner creates a dependency graph. Tasks execute in parallel when their blockers are resolved.

↓ scroll down for details ↓

How Dependencies Work

{
  "tasks": [
    {
      "id": "A",
      "title": "Create Schema",
      "depends_on": []
    },
    {
      "id": "B",
      "title": "User Model",
      "depends_on": ["A"],
      "group": "models"
    },
    {
      "id": "C",
      "title": "Auth Service",
      "depends_on": ["A"],
      "group": "auth"
    },
    {
      "id": "D",
      "title": "Login Endpoint",
      "depends_on": ["B", "C"]
    }
  ]
}

Beads Integration

↓ scroll down for workflow details ↓

Beads: Creating Issues

# Captain creates a task with labels
captain add "Implement user authentication" --labels=backend,security

# Beads issue is created automatically with full metadata
bd show captain-42

# Output:
# ┌─────────────────────────────────────────────────────────────┐
# │ captain-42: Implement user authentication                   │
# ├─────────────────────────────────────────────────────────────┤
# │ Status:    in_progress                                      │
# │ Type:      epic                                             │
# │ Priority:  P2 (medium)                                      │
# │ Labels:    backend, security                                │
# │ Created:   2024-01-15 10:30:00                             │
# │                                                             │
# │ Blocks:    captain-50, captain-51 (downstream tasks)        │
# │ Subtasks:  captain-43, captain-44, captain-45               │
# └─────────────────────────────────────────────────────────────┘

Beads: Viewing Dependencies

# View all issues with dependency tree
bd list --all --pretty

# Output with visual dependency graph:
# ┌──────────────────────────────────────────────────────────────────────────────┐
# │ ID           Status        Title                              Labels        │
# ├──────────────────────────────────────────────────────────────────────────────┤
# │ captain-42   in_progress   Implement user authentication      backend       │
# │ ├─ captain-43   done       Create User model                  backend,db    │
# │ ├─ captain-44   done       Add password hashing               backend       │
# │ ├─ captain-45   working    Implement JWT middleware           backend,auth  │
# │ │  └─ captain-46 blocked   Create login endpoint              backend,api   │
# │ │     └─ captain-47 pending  Add session management           backend       │
# │ └─ captain-48   pending    Write auth tests                   test          │
# │                                                                              │
# │ captain-50   blocked       Add user profile page              frontend      │
# │   └─ (blocked by captain-42)                                                │
# └──────────────────────────────────────────────────────────────────────────────┘
#
# Legend: done=green, working=cyan, pending=gray, blocked=yellow

The tree view shows task hierarchy and blocking relationships at a glance.

Beads: Workflow Commands

# What's ready to work on?
bd ready
# captain-48: Write auth tests
#   (all blockers resolved)

# Filter by label
bd list --labels=backend --status=open

# See what's blocked
bd blocked
# captain-46: blocked by captain-45
# captain-50: blocked by captain-42

# Add a dependency
bd dep add captain-47 captain-46
# captain-47 now depends on captain-46

# Close completed work
bd close captain-45 --reason="JWT impl done"

# Sync to git (persists state)
bd sync --flush-only
# Exported 8 issues to .beads/issues.jsonl

ChunkHound Integration

↓ scroll down to see MCP server in action ↓

MCP Server: Tool Calls

When an agent needs to understand existing code, the Claude SDK makes MCP tool calls:

// Agent: "I need to find how authentication is implemented"
{
  "tool": "mcp__ChunkHound__search_semantic",
  "input": { "query": "user authentication middleware JWT", "page_size": 5 }
}

// ChunkHound responds with ranked results:
{
  "results": [
    { "file": "src/middleware/auth.ts", "score": 0.92, "lines": "45-52",
      "chunk": "export async function verifyToken(req)..." },
    { "file": "src/utils/tokens.ts", "score": 0.87,
      "chunk": "export function generateAccessToken(user)..." }
  ]
}

MCP Server: Research Mode

For complex questions, agents use the code_research tool for deep analysis:

// Planner needs to understand the entire auth system architecture
{
  "tool": "mcp__ChunkHound__code_research",
  "input": {
    "query": "How does the authentication system work? What are the main components?"
  }
}

// ChunkHound performs multi-step analysis and returns markdown report:
{
  "analysis": "## Authentication System Architecture\n\n### Components\n1. **JWT Middleware** - Validates Bearer tokens...\n2. **Token Service** - Generates access/refresh tokens...\n3. **Login Endpoint** - POST /api/login...\n\n### Data Flow\nRequest → auth middleware → verify JWT → attach user → handler\n\n### Related Files\n- src/models/User.ts, src/config/jwt.ts, tests/auth.test.ts"
}

MCP Server: Regex Search

// Find all usages of a specific function
{
  "tool": "mcp__ChunkHound__search_regex",
  "input": {
    "pattern": "verifyToken\\(",
    "path": "src/",
    "output_mode": "content"
  }
}

// Response:
{
  "matches": [
    "src/middleware/auth.ts:47: verifyToken(req)",
    "src/routes/profile.ts:12: verifyToken(ctx.req)",
    "src/routes/settings.ts:8: verifyToken(ctx.req)"
  ],
  "count": 3
}

// Validator extracts patterns for indexing
{
  "discovery": {
    "type": "pattern",
    "content": "Auth uses Bearer tokens with 15min expiry. Refresh tokens stored in httpOnly cookies.",
    "files": [
      "src/middleware/auth.ts",
      "src/utils/tokens.ts"
    ]
  }
}

// Future agents can find this via:
// "how does token refresh work?"