Skip to main content

​
Start Planning

POST /api/projects/:projectId/plan
Starts a new planning session. Claude will explore the codebase and generate tasks. Request Body: 
{
  "topic": "Build an authentication system with OAuth2 and JWT",
  "model": "sonnet",
  "effort": "medium",
  "granularity": "balanced",
  "context": "Express.js backend, React frontend"
}
FieldTypeDefaultDescription
topicstringrequiredWhat to plan — the main feature or goal
modelstringsonnetClaude model: haiku, sonnet, opus
effortstringmediumThinking budget: low, medium, high
granularitystringbalancedTask detail: high-level, balanced, detailed
contextstring""Additional context about tech stack or constraints
Response: 
{
  "planId": "plan-1-1711234567890",
  "status": "started"
}
Returns 409 if a planning session is already active for the project.

​
Get Status

GET /api/projects/:projectId/plan/status
Check whether a planning session is currently running. Response (active): 
{
  "active": true,
  "planId": "plan-1-1711234567890",
  "elapsed": 12340,
  "tokens": { "input": 15000, "output": 3200 },
  "toolCalls": 8,
  "turns": 3,
  "phase": "exploring",
  "topic": "Build an authentication system"
}
Response (inactive): 
{
  "active": false,
  "planId": null
}

​
Cancel Planning

POST /api/projects/:projectId/plan/cancel
Stops the active planning session and kills the Claude process. Response: 
{
  "status": "cancelled"
}
Returns 404 if no active planning session exists.

​
WebSocket Events

Planning progress is streamed via Socket.IO events:

​
plan:started

Emitted when a planning session begins. 
{
  "projectId": 1,
  "planId": "plan-1-1711234567890",
  "topic": "Build authentication",
  "model": "sonnet",
  "effort": "medium"
}

​
plan:phase

Emitted when the planning phase changes. 
{
  "projectId": 1,
  "planId": "plan-1-1711234567890",
  "phase": "exploring"
}
Phases: starting → exploring → writing → (completed)

​
plan:progress

Emitted when Claude produces text output. 
{
  "projectId": 1,
  "planId": "plan-1-1711234567890",
  "type": "text",
  "content": "I'll start by examining the project structure..."
}

​
plan:log

Emitted for tool calls and results. 
{
  "projectId": 1,
  "planId": "plan-1-1711234567890",
  "type": "tool",
  "message": "Read \u2192 src/app.js",
  "tool": "Read"
}
Types: tool, result, error, phase

​
plan:stats

Emitted after each Claude turn with updated usage stats. 
{
  "projectId": 1,
  "planId": "plan-1-1711234567890",
  "elapsed": 8500,
  "tokens": { "input": 12000, "output": 2400 },
  "toolCalls": 5,
  "turns": 2
}

​
plan:completed

Emitted when planning finishes. Contains the created tasks. 
{
  "projectId": 1,
  "planId": "plan-1-1711234567890",
  "tasks": [
    { "id": 42, "title": "Set up auth middleware", "task_type": "feature", "task_key": "FTR-CB-1042" }
  ],
  "stats": {
    "elapsed": 45000,
    "tokens": { "input": 25000, "output": 8000 },
    "toolCalls": 12,
    "turns": 4,
    "exitCode": 0
  }
}

​
plan:cancelled

Emitted when a planning session is manually cancelled. 
{
  "projectId": 1,
  "planId": "plan-1-1711234567890"
}