ACP¶

Pegg implements the Agent Client Protocol (ACP): a JSON-RPC 2.0 protocol for driving a coding agent from an editor or other client. The server exposes the same orchestrator used by the CLI and TUI.

Starting the server¶

pegg serve --acp --stdio

pegg serve --acp
# acp server listening on http://127.0.0.1:8080/acp

Host and port come from --host / --port or the server config block. The ACP handler does not apply the HTTP API's auth or CORS middleware.

Protocol basics¶

• Every message is a JSON-RPC 2.0 envelope. "jsonrpc" must be exactly "2.0".
• Batch requests are not supported.
• A message with method and no id is a notification: handlers run, no response is written.
• A message with id and no method is a response to a server-initiated request.

Error codes¶

Methods¶

Unknown methods return -32601.

initialize¶

protocolVersion is required and must be at least 1. The result advertises what the agent supports:

{
  "protocolVersion": 1,
  "agentCapabilities": {
    "loadSession": true,
    "promptCapabilities": { "image": true, "audio": false, "embeddedContext": true },
    "mcpCapabilities": { "http": true, "sse": false },
    "sessionCapabilities": {
      "delete": {},
      "resume": {},
      "close": {},
      "additionalDirectories": {}
    }
  },
  "agentInfo": { "name": "pegg", "title": "Pegg AI Agent", "version": "0.1.0" },
  "authMethods": []
}

session/new¶

Creates a new ACP session. cwd is required. Pegg also creates a persisted session (titled ACP Session) in its session store and links the two.

{ "jsonrpc": "2.0", "id": 1, "method": "session/new", "params": { "cwd": "/home/user/project" } }

{ "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "9d1f..." } }

mcpServers and additionalDirectories are accepted but currently ignored.

session/prompt¶

Only the first text content block is used as the agent input. While the agent runs, the server pushes session/update notifications (see below). The result's stopReason is one of:

{ "jsonrpc": "2.0", "id": 2, "method": "session/prompt",
  "params": { "sessionId": "9d1f...", "prompt": [{ "type": "text", "text": "Fix the failing test" }] } }

{ "jsonrpc": "2.0", "id": 2, "result": { "stopReason": "end_turn" } }

session/list¶

Lists persisted sessions (page 1, size 50, newest first). nextCursor is currently always empty.

{
  "sessions": [
    { "id": "3f2b...", "title": "Fix parser bug",
      "createdAt": "2026-09-10T09:15:00Z", "updatedAt": "2026-09-10T09:42:11Z" }
  ],
  "nextCursor": ""
}

Server notifications¶

The server pushes session/update notifications:

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "9d1f...",
    "update": { "sessionUpdate": "agent_message_chunk", "messageId": "…",
                "content": { "type": "text", "text": "Working on it" } }
  }
}

When the context is compacted mid-run, an agent_message_chunk notification is emitted with the text [Context compacted (<strategy>) — <messages> messages, <tokens> tokens].

The usage_update payload uses a fixed size of 200000 and a USD cost object.

Transports¶

echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1}}' \
  | pegg serve --acp --stdio

# 1. initialize
curl -i http://127.0.0.1:8080/acp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientInfo":{"name":"demo","version":"1.0"}}}'

# 2. open the event stream (long-lived)
curl -N http://127.0.0.1:8080/acp \
  -H 'Accept: text/event-stream' \
  -H 'Acp-Connection-Id: <uuid>'

Complete example (stdio)¶

→ {"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1}}
← {"jsonrpc":"2.0","id":0,"result":{"protocolVersion":1,"agentCapabilities":{...},"agentInfo":{...}}}
→ {"jsonrpc":"2.0","id":1,"method":"session/new","params":{"cwd":"/home/user/project"}}
← {"jsonrpc":"2.0","id":1,"result":{"sessionId":"9d1f..."}}
→ {"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{"sessionId":"9d1f...","prompt":[{"type":"text","text":"List the Go files"}]}}
← {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"9d1f...","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Here are"}}}}
← {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"9d1f...","update":{"sessionUpdate":"tool_call","toolCallId":"…","title":"glob","kind":"other","status":"pending"}}}
← {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"9d1f...","update":{"sessionUpdate":"tool_call_update","toolCallId":"…","status":"completed"}}}
← {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"9d1f...","update":{"sessionUpdate":"usage_update","used":1540,"size":200000,"cost":{"amount":0.004,"currency":"USD"}}}}
← {"jsonrpc":"2.0","id":2,"result":{"stopReason":"end_turn"}}

Cancellation¶

Send session/cancel with the session id to abort a running prompt. The running agent's context is cancelled and the in-flight session/prompt resolves with stopReason: "cancelled". No response is written for the cancel message itself. $/cancelRequest is accepted but does nothing.

Outbound requests¶

The server can also call methods on the client (fs/read_text_file, fs/write_text_file, session/request_permission). The plumbing is implemented, but current tools do not invoke it, so clients do not need to handle these methods yet.