Executors API

/api/executors - Executor management endpoints

Overview

Executors are the underlying AI coding agent runtimes, such as Claude Code, Gemini, etc. The Executors API provides executor discovery, availability checking, and session management functionality.

Endpoints

Method	Path	Description
GET	/api/executors	List available executors
GET	/api/executors/:type/discover-sessions	Discover executor sessions
GET	/api/executors/:type/sessions/:sid/messages	Read session messages

---

Detailed Description

GET /api/executors

List all available executors and their status.

Query Parameters:

Parameter	Type	Required	Default	Description
workspace_path	string	No	-	Workspace path
include_global	bool	No	true	Whether to include global configuration

Response:

{
  "executors": [
    {
      "type": "CLAUDE_CODE",
      "name": "Claude Code",
      "description": "Anthropic Claude Code CLI",
      "is_available": true,
      "availability": {
        "available": true,
        "reason": null,
        "version": "1.0.0"
      },
      "supports_mcp": true,
      "supports_streaming": true,
      "supports_tools": true,
      "features": ["chat", "code", "tools", "streaming", "mcp"]
    },
    {
      "type": "GEMINI",
      "name": "Gemini",
      "description": "Google Gemini CLI",
      "is_available": false,
      "availability": {
        "available": false,
        "reason": "CLI not installed"
      }
    }
  ]
}

---

GET /api/executors/:type/discover-sessions

Discover existing sessions for a specified executor type.

Path Parameters:

• type: Executor type (e.g., CLAUDE_CODE, CODEX)

Query Parameters:

Parameter	Type	Required	Default	Description
workspace_path	string	No	-	Filter by workspace path

Response:

{
  "sessions": [
    {
      "session_id": "abc123",
      "workspace_path": "/path/to/project",
      "created_at": "2024-01-01T10:00:00Z",
      "last_active": "2024-01-01T14:30:00Z",
      "message_count": 42,
      "title": "Feature implementation"
    }
  ]
}

Session Storage Locations:

Executor	Storage Path
CLAUDE_CODE	~/.claude/projects/<encoded-path>/<session-id>.jsonl
CODEX	~/.codex/sessions/<session-id>/

---

GET /api/executors/:type/sessions/:sid/messages

Read the message history of an executor session.

Path Parameters:

• type: Executor type
• sid: Session ID

Query Parameters:

Parameter	Type	Required	Default	Description
workspace_path	string	No	-	Workspace path
include_subagents	bool	No	true	Whether to include subagent messages

Response:

{
  "messages": [
    {
      "id": "msg-1",
      "role": "user",
      "content": "Analyze this code",
      "timestamp": "2024-01-01T10:00:00Z"
    },
    {
      "id": "msg-2",
      "role": "assistant",
      "content": "I'll analyze the code...",
      "timestamp": "2024-01-01T10:00:05Z",
      "tool_calls": [
        {
          "type": "Task",
          "subagent_type": "Explore",
          "status": "completed",
          "result": "..."
        }
      ]
    }
  ],
  "subagent_messages": {
    "task-abc123": [
      {
        "id": "sub-msg-1",
        "role": "assistant",
        "content": "Exploring codebase..."
      }
    ]
  }
}

Subagent Messages:

When include_subagents=true, the API recursively loads subagent session messages generated by Task tool calls. This is useful for understanding complex multi-agent interactions.

---

Executor Types

Type	Name	CLI Command	MCP Support
CLAUDE_CODE	Claude Code	claude	Yes
AMP	AMP	amp	Yes
GEMINI	Gemini	gemini	-
CODEX	Codex	codex	-
OPENCODE	OpenCode	opencode	-
CURSOR_AGENT	Cursor	cursor	Yes
QWEN_CODE	Qwen Code	qwen	-
COPILOT	Copilot	copilot	-
DROID	Droid	droid	-

---

Availability Checking

Executor availability checking logic:

1. Check if the CLI command exists in PATH
2. Check if necessary configuration files exist
3. Check if API keys are configured (if required)

{
  "available": true,
  "reason": null,
  "version": "1.0.0",
  "cli_path": "/usr/local/bin/claude"
}

{
  "available": false,
  "reason": "CLI not found in PATH",
  "suggestion": "Install with: npm install -g @anthropic-ai/claude-code"
}

---

Related Endpoints

• Agents API - Agent management
• Sessions API - Session management