Agent Client Protocol (ACP) Integration¶

CodeGraph supports the Agent Client Protocol (ACP) for seamless IDE integration with Zed, JetBrains IDEs, VS Code, and other ACP-compatible editors.

Overview¶

ACP is a standardized protocol for communication between code editors and AI coding agents. CodeGraph implements ACP to provide intelligent code analysis directly within your IDE.

Transports¶

CodeGraph supports three transport mechanisms:

Transport	Use Case	Endpoint
stdio	Local subprocess (IDE spawned)	`codegraph-acp` command
HTTP	Remote REST API	`POST /api/v1/acp/rpc`
WebSocket	Real-time streaming	`WS /api/v1/acp/ws`

Supported Methods¶

Baseline Methods (Required)¶

Method	Description
`initialize`	Capability negotiation
`authenticate`	JWT token authentication
`session/new`	Create new session
`session/prompt`	Send user message
`session/cancel`	Cancel ongoing operation

Optional Methods¶

Method	Description
`session/load`	Resume existing session
`fs/read_text_file`	Read file from filesystem
`fs/write_text_file`	Write file to filesystem
`terminal/create`	Create terminal session
`terminal/output`	Get terminal output
`terminal/wait_for_exit`	Wait for command completion
`terminal/kill`	Kill running command
`terminal/release`	Release terminal resources

Agent Capabilities¶

CodeGraph advertises the following capabilities:

{
  "loadSession": true,
  "setMode": false,
  "promptCapabilities": {
    "image": false,
    "audio": false,
    "embeddedContext": true
  },
  "mcp": {
    "stdio": true,
    "http": true,
    "sse": false
  },
  "authMethods": ["bearer"]
}

Session Lifecycle¶

1. Initialize
   Client -> initialize -> Agent
   Agent -> capabilities -> Client

2. Create Session
   Client -> session/new {cwd} -> Agent
   Agent -> {sessionId} -> Client

3. Send Prompt
   Client -> session/prompt {sessionId, prompt} -> Agent
   Agent -> session/update (plan) -> Client
   Agent -> session/update (tool_call) -> Client
   Agent -> session/update (agent_message_chunk) -> Client
   Agent -> {stopReason} -> Client

4. Close
   Client -> session/cancel -> Agent

API Endpoints¶

HTTP Transport¶

POST /api/v1/acp/rpc

Single JSON-RPC endpoint for all ACP method calls.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": 1,
    "clientCapabilities": {},
    "clientInfo": {"name": "my-ide", "version": "1.0"}
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {...},
    "agentInfo": {
      "name": "codegraph",
      "version": "0.1.0",
      "title": "CodeGraph Code Analysis Agent"
    }
  }
}

WebSocket Transport¶

WS /api/v1/acp/ws?token=

Streaming endpoint with real-time session updates.

Supports bidirectional messaging: - Client -> Agent: JSON-RPC requests - Agent -> Client: JSON-RPC responses + notifications

Health Check¶

GET /api/v1/acp/health

Returns agent status and capabilities.

GET /api/v1/acp/info

Returns agent metadata for discovery.

Session Updates¶

During prompt processing, CodeGraph sends session/update notifications:

Plan Update¶

{
  "sessionUpdate": "plan",
  "plan": {
    "entries": [
      {"id": "1", "title": "Classifying intent", "status": "completed"},
      {"id": "2", "title": "Querying code graph", "status": "in_progress"},
      {"id": "3", "title": "Generating response", "status": "pending"}
    ]
  }
}

Tool Call Update¶

{
  "sessionUpdate": "tool_call",
  "toolCallId": "tc_abc123",
  "title": "Security Analysis",
  "kind": "search",
  "status": "in_progress"
}

Message Chunk¶

{
  "sessionUpdate": "agent_message_chunk",
  "chunk": "Based on my analysis..."
}

Tool Call Kinds¶

CodeGraph maps its scenarios to ACP tool kinds:

Scenario	Tool Kind
Security Analysis	search
Code Review	read
Performance Analysis	search
Refactoring	edit
Documentation	read
Architecture Analysis	think

Authentication¶

For HTTP/WebSocket transports, authentication is optional but recommended:

Authorization: Bearer <jwt_token>

Authenticated sessions have: - Persistent dialogue history - User-specific settings - Rate limit quotas

Error Codes¶

Code	Meaning
-32700	Parse error
-32600	Invalid request
-32601	Method not found
-32602	Invalid params
-32603	Internal error
-32002	Agent not initialized

Examples¶

Initialize and Create Session¶

# Initialize
curl -X POST http://localhost:8000/api/v1/acp/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": 1,
      "clientCapabilities": {},
      "clientInfo": {"name": "curl-client"}
    }
  }'

# Create session
curl -X POST http://localhost:8000/api/v1/acp/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "session/new",
    "params": {"cwd": "/path/to/project"}
  }'

Send Prompt¶

curl -X POST http://localhost:8000/api/v1/acp/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "session/prompt",
    "params": {
      "sessionId": "acp_xxx",
      "prompt": [
        {"type": "text", "text": "What are the main entry points?"}
      ]
    }
  }'

MCP Server Support¶

CodeGraph can connect to external MCP servers provided by the client:

{
  "method": "session/new",
  "params": {
    "cwd": "/project",
    "mcpServers": [
      {
        "id": "github",
        "name": "GitHub MCP",
        "transport": "stdio",
        "command": "github-mcp-server"
      }
    ]
  }
}

Agent Client Protocol (ACP) Integration