AgentAPI

English | 繁體中文

Control Claude Code, AmazonQ, Opencode, Goose, Aider, Gemini, GitHub Copilot, Sourcegraph Amp, Codex, Kimi Code, Pi, Auggie, and Cursor CLI with an HTTP API.

You can use AgentAPI:

• to build a unified chat interface for coding agents
• as a backend in an MCP server that lets one agent control another coding agent
• to create a tool that submits pull request reviews to an agent
• and much more!

Changes in this fork

This fork started from the upstream v0.12.2 codebase. It keeps the original terminal-emulation and HTTP API model, while extending AgentAPI into a more complete workspace for operating long-running coding agents.

Session workspace and chat UI

The embedded chat UI is organized around tasks instead of a single flat transcript. Each user request becomes a navigable task with its associated response, thinking blocks, tool calls, and background activity.

Tasks read as a transcript: a time rail, your prompt in a tinted block labelled "You", the agent's turn opening with its mark and name (e.g. Pi), the agent's reply as Markdown, tool calls as one-line rows ($ command, exit code, duration, output preview), and thinking as margin notes on wide screens. A status strip above the composer shows what the agent is doing right now, and the header, tab title and queue say "Needs you" while the agent waits for an answer. Long tasks show their latest 40 steps first.

The Session Explorer provides:

• links and file paths discovered in the current conversation;
• an index for jumping directly to earlier tasks;
• Markdown preview and export for individual tasks;
• access to the live terminal when the parsed conversation is not sufficient;
• MCP server and Temporal/Discord configuration without leaving the chat UI;
• a Session tab with a two-step Restart (open the Explorer with ⌘K / Ctrl+K).

Each message has its own markdown/raw toggle so you can switch render modes without affecting the rest of the conversation.

Images can be pasted straight into the composer (a pasted screenshot is uploaded like an attachment; pasted text still pastes as text). Image attachments and the images in sent messages show as thumbnails that open full size; the agent gets the file path.

The UI also includes improved mobile layouts, attachment handling, searchable tool activity, connection-state indicators, and more compact tool-call cards. The header shows the agent's mark (Claude's orange square, Pi's logo) and the AgentAPI version.

TTY mode is an escape hatch for when the chat view looks wrong: the terminal button in the header swaps the conversation for the agent's terminal screen (xterm.js) and sends every key straight to the agent, including arrows, Ctrl/Alt keys, pastes and IME input. A key bar provides Esc, Tab, arrows, Enter and Ctrl keys on phones. The font grows with the window (11–20px); the mirror uses the agent's real terminal width, so start AgentAPI with --term-width 120 if you want longer lines.

Background alerts: while the tab is in the background, its icon shows an amber dot when the agent needs you, a blue dot while it works, and a green dot when a task finished. Browser notifications can be turned on from the status menu.

Message queue and connection recovery

Messages submitted while an agent is busy are placed in a FIFO queue instead of being rejected. Queued messages can be inspected, edited, or deleted before delivery through both the API and chat UI.

Long-running browser sessions are protected by SSE heartbeats, automatic reconnection, stale-connection detection, and local recovery of messages that failed before reaching the server. The document title and session header expose the current task, agent status, and connection state.

Reopening a long conversation is fast: the chat caches the transcript in the browser (IndexedDB), shows it immediately, and then asks the server only for what changed since.

Relevant APIs include:

• GET /queue and PUT/DELETE /queue/{id} for queue management;
• GET /events for live messages, status, errors, rich activity, and heartbeat events. With ?sync=1 the stream starts with a session_sync event and every update carries a seq; reconnecting with &since=<seq>&epoch=<epoch> replays only what changed;
• GET /title for the current human-readable session title.

Structured Claude, Codex and Pi activity

In addition to parsing terminal snapshots, this fork can watch Claude, Codex and Pi session logs. This provides structured thinking blocks, tool invocations, tool results, usage information, and stable message identifiers that cannot always be reconstructed reliably from terminal output alone.

• GET /rich-messages returns the structured conversation.
• GET /timeline returns normalized session events suitable for export, auditing, or building another UI.
• Background and delegated tasks remain visible with their running, completed, or failed state and output details.
• Claude thinking blocks are rendered inline as collapsible sections in the task timeline.
• Codex is started with -c model_reasoning_summary="auto" (unless you set it yourself) so its log holds readable reasoning summaries instead of only encrypted reasoning.

Terminal parsing remains the fallback for other agents and for environments where a session log is unavailable.

MCP management

Claude, Codex and Pi MCP servers can be managed while AgentAPI is running. The implementation preserves unrelated settings in .mcp.json (Claude), $CODEX_HOME/config.toml (Codex) or ~/.pi/agent/mcp.json (Pi).

The API and Session Explorer support:

• reading or replacing the complete MCP server map;
• creating, updating, and deleting individual servers;
• checking remote HTTP connectivity and resolving local stdio executables;
• saving, importing, exporting, and applying reusable MCP profiles;
• optionally restarting the PTY agent to apply changes immediately.

When an agent is restarted, AgentAPI itself and its HTTP/SSE clients remain online. The child agent receives a new process and session-log watcher, although its previous in-memory conversation context is not retained. Before restarting, AgentAPI updates Codex (codex update) and Pi (pi update --self), so the restarted agent is the latest release; Claude Code updates itself.

Run-status webhooks

AgentAPI can send an HTTP POST whenever a run changes between running and stable. Webhooks can be initialized with CLI flags or AGENTAPI_WEBHOOK_* environment variables, then inspected or changed through GET/PUT /webhook or the Session Explorer.

Delivery runs asynchronously with a configurable timeout and retry count. An optional Go text/template payload template lets you reshape the POST body for any receiver — available fields are .ID, .Type, .CreatedAt, .RunID, .Status, .PreviousStatus, .AgentType, and .Transport. When no template is set, the default JSON payload is sent unchanged.

agentapi server \
  --webhook-url https://example.com/agentapi/events \
  -- claude

Discord replies through Temporal

The optional agentapi discord service lets you continue the same agent session from Discord after closing the web UI. It starts a Temporal workflow for a pending response, sends a bot notification, and waits for a human_response signal when an allowed Discord user replies to that notification. A worker Activity then submits the reply to AgentAPI. The web UI remains usable throughout.

This supports ordinary conversational follow-ups and recognized numbered PTY confirmation dialogs. Notifications are independent of browser presence. AgentAPI and the bridge must remain running; Temporal preserves workflow state, not the agent's terminal process. See setup, configuration and limitations.

Self-update

AgentAPI can update itself from the command line:

agentapi update          # download and install the latest release
agentapi update --check  # check without downloading
agentapi update --force  # skip version comparison

Release binaries are verified against the release's checksums.txt SHA-256 manifest before the running executable is replaced. An update is rejected if the manifest is missing, malformed, or does not match the download.

API token authentication

All API endpoints can be protected with a Bearer token. Authentication is disabled by default for backward compatibility.

# Auto-generate a random token (printed to stderr on startup)
agentapi server --api-token -- claude

# Use a specific token
agentapi server --api-token=my-secret -- claude

# Via environment variable
AGENTAPI_API_TOKEN=my-secret agentapi server -- claude

When enabled, every API request must include Authorization: Bearer <token>. Static file routes (/, /chat/*) are exempt so browsers can open the chat UI without a token.

Interactive prompt support

The chat UI detects interactive TUI prompts — such as Claude Code's plan approval dialog or permission confirmation, Codex's approvals, and Pi's project trust prompt — and docks them above the composer as a decision card. Number keys pick an option. Multi-select questions (Claude Code's AskUserQuestion with multiSelect) show checkboxes and a Continue button that moves on to the next question or the review step. A numbered list in the agent's answer is not mistaken for options. GET /status reports the prompt as terminal_prompt.

Kimi Code CLI

This fork adds the kimi agent type, automatic detection for the kimi executable, chat UI labeling, terminal message formatting, readiness detection, and tests for its startup state.

Kimi can use the regular interactive PTY transport:

agentapi server -- kimi

It can also use Kimi's native ACP server after completing /login once:

agentapi server --type=kimi --experimental-acp -- kimi acp

Pi coding agent

The pi agent type runs the Pi coding agent (npm install -g @earendil-works/pi-coding-agent) in its interactive terminal UI. It is auto-detected when the executable name is pi:

agentapi server -- pi

Log in once with /login in Pi (TTY mode in the chat UI works), or set a provider key such as ANTHROPIC_API_KEY. AgentAPI follows Pi's session log (~/.pi/agent/sessions/, or $PI_CODING_AGENT_DIR / $PI_CODING_AGENT_SESSION_DIR) for structured messages, so the chat shows Pi's tool calls, thinking and token usage like it does for Claude Code and Codex.

Pi's dialogs (such as the project trust prompt) can be answered from the chat, and the header and tab icon show Pi's logo. The Explorer's MCP tab manages Pi's user-level servers in ~/.pi/agent/mcp.json, and restarting the agent runs pi update --self first.

AgentAPI starts Pi with its own --session-id (a new one on every start or restart) so it follows the right session log even when several Pi processes share a directory. If you pass --session, --continue, --resume or --session-id yourself, AgentAPI leaves the session to you; with --continue/--resume the chat falls back to the terminal output.

Runtime reliability

The fork also includes fixes for wide-character terminal cursor tracking, PTY lifecycle leaks, concurrent event delivery, message tracking races, ACP shutdown, TUI re-render artifacts, JSONL watcher flushing, rich message content-block merging during Claude delta streaming, and runtime session-file switching when Claude Code parks a session to a new JSONL. These changes are intended to keep AgentAPI stable across long sessions, process replacement, and temporary browser or network interruptions.

See the full comparison with upstream for the complete commit history.

Quickstart

1. Install agentapi:

   OS=$(uname -s | tr "[:upper:]" "[:lower:]");
   ARCH=$(uname -m | sed "s/x86_64/amd64/;s/aarch64/arm64/");
   curl -fsSL "https://github.com/k1dav-c/agentapi/releases/latest/download/agentapi-${OS}-${ARCH}" -o agentapi && chmod +x agentapi

   Alternatively, you can download this fork's latest binary from the releases page. Upstream coder/agentapi release binaries do not include the features documented in the Changes in this fork section.

2. Verify the installation:

   agentapi --help

   On macOS, if you're prompted that the system was unable to verify the binary, go to System Settings -> Privacy & Security, click "Open Anyway", and run the command again.

3. Run a Claude Code server (assumes claude is installed on your system and in the PATH):

   agentapi server -- claude

   If you're getting an error that claude is not in the PATH but you can run it from your shell, try which claude to get the full path and use that instead.

4. Send a message to the agent:

   curl -X POST localhost:3284/message \
     -H "Content-Type: application/json" \
     -d '{"content": "Hello, agent!", "type": "user"}'

5. Get the conversation history:

   curl localhost:3284/messages

6. Try the chat web interface at http://localhost:3284/chat.

CLI Commands

agentapi server

Run an HTTP server that lets you control an agent. If you'd like to start an agent with additional arguments, pass the full agent command after the -- flag.

agentapi server -- claude --allowedTools "Bash(git*) Edit Replace"

You may also use agentapi to run the Aider and Goose agents:

agentapi server -- aider --model sonnet --api-key anthropic=sk-ant-apio3-XXX
agentapi server -- goose

Pi runs through its interactive terminal UI (see Pi coding agent):

agentapi server -- pi

Kimi Code can run through its interactive terminal UI:

agentapi server -- kimi

Kimi Code also provides a native ACP server. After logging in once with kimi and /login, you can use AgentAPI's ACP transport:

agentapi server --type=kimi --experimental-acp -- kimi acp

Note

When using Claude, Codex, Opencode, Copilot, Gemini, Amp or CursorCLI, always specify the agent type explicitly (eg: agentapi server --type=codex -- codex), or message formatting may break. Kimi and Pi are auto-detected when the executable name is kimi or pi; use --type=kimi / --type=pi for wrappers or ACP mode.

An OpenAPI schema is available in openapi.json.

By default, the server runs on port 3284. Additionally, the server exposes the same OpenAPI schema at http://localhost:3284/openapi.json and the available endpoints in a documentation UI at http://localhost:3284/docs.

Endpoints:

• GET /messages - returns a list of all messages in the conversation with the agent
• POST /message - sends a message to the agent. When a 200 response is returned, AgentAPI has detected that the agent started processing the message
• GET /status - returns the backward-compatible stable/running status, detailed lifecycle (starting, ready, running, restarting, exited, or failed), a session ID, a monotonically increasing run ID, the AgentAPI version, the agent's open dialog (terminal_prompt) and the terminal width (terminal_columns)
• GET /events - an SSE stream of events from the agent: message and status updates (?sync=1 for incremental replay on reconnect)
• DELETE /messages - clears all conversation state (messages, rich messages, timeline, errors) and restarts the agent process
• POST /upload - stores a file (up to 10 MB) in the server's temporary upload directory and returns its path, which a message references as @"<path>"
• GET /uploads/{checksum}/{name} - returns an uploaded image (PNG, JPEG, GIF, WebP or BMP, judged by content) for the chat to show; other files are refused
• GET/PUT /webhook - reads or updates run-status webhook delivery without restarting the agent
• GET /mcp - returns configured MCP servers and the managed config path for Claude, Codex or Pi
• PUT /mcp - replaces the complete MCP server set; pass ?restart=true to restart the PTY agent and apply immediately
• POST /mcp/check - checks remote HTTP connectivity and resolves stdio executables
• POST /mcp/servers, PATCH/DELETE /mcp/servers/{name} - creates, updates, or removes one MCP server
• GET /mcp/profiles - exports project-scoped MCP configuration profiles
• PUT/DELETE /mcp/profiles/{name} - imports, replaces, or removes a profile
• POST /mcp/profiles/{name}/apply - replaces the active MCP configuration with a saved profile

API token authentication

Set --api-token to require a Bearer token on all API requests (static chat UI routes are exempt):

agentapi server --api-token -- claude             # auto-generate and print to stderr
agentapi server --api-token=my-secret -- claude    # use a specific token

The equivalent environment variable is AGENTAPI_API_TOKEN. When set, clients must include Authorization: Bearer <token> on every API call. Without --api-token, authentication is disabled (backward compatible).

Allowed hosts

By default, the server only allows requests with the host header set to localhost. If you'd like to host AgentAPI elsewhere, you can change this by using the AGENTAPI_ALLOWED_HOSTS environment variable or the --allowed-hosts flag. Hosts must be hostnames only (no ports); the server ignores the port portion of incoming requests when authorizing.

To allow requests from any host, use * as the allowed host.

agentapi server --allowed-hosts '*' -- claude

To allow a specific host, use:

agentapi server --allowed-hosts 'example.com' -- claude

To specify multiple hosts, use a comma-separated list when using the --allowed-hosts flag, or a space-separated list when using the AGENTAPI_ALLOWED_HOSTS environment variable.

agentapi server --allowed-hosts 'example.com,example.org' -- claude
# or
AGENTAPI_ALLOWED_HOSTS='example.com example.org' agentapi server -- claude

Allowed origins

By default, the server allows CORS requests from http://localhost:3284, http://localhost:3000, and http://localhost:3001. If you'd like to change which origins can make cross-origin requests to AgentAPI, you can change this by using the AGENTAPI_ALLOWED_ORIGINS environment variable or the --allowed-origins flag.

To allow requests from any origin, use * as the allowed origin:

agentapi server --allowed-origins '*' -- claude

To allow a specific origin, use:

agentapi server --allowed-origins 'https://example.com' -- claude

To specify multiple origins, use a comma-separated list when using the --allowed-origins flag, or a space-separated list when using the AGENTAPI_ALLOWED_ORIGINS environment variable. Origins must include the protocol (http:// or https://) and support wildcards (e.g., https://*.example.com):

agentapi server --allowed-origins 'https://example.com,http://localhost:3000' -- claude
# or
AGENTAPI_ALLOWED_ORIGINS='https://example.com http://localhost:3000' agentapi server -- claude

Run status webhooks

Set --webhook-url to send an HTTP POST whenever the run status changes between running and stable:

agentapi server \
  --webhook-url 'https://example.com/agentapi/events' \
  -- claude

The equivalent environment variables are AGENTAPI_WEBHOOK_URL, AGENTAPI_WEBHOOK_PAYLOAD_TEMPLATE, AGENTAPI_WEBHOOK_TIMEOUT, and AGENTAPI_WEBHOOK_MAX_ATTEMPTS. The timeout defaults to 10s, and delivery is attempted up to 3 times.

The initial webhook values can still be changed while AgentAPI is running with GET/PUT /webhook. Session Explorer now uses its Temporal tab for Temporal and Discord bridge settings. The legacy webhook API remains available for compatibility, but is no longer the Session Explorer integration.

The request body has this format:

{
  "id": "unique-delivery-id",
  "type": "run.status_changed",
  "created_at": "2026-07-26T12:00:00Z",
  "data": {
    "run_id": "agentapi-process-run-id",
    "status": "stable",
    "previous_status": "running",
    "agent_type": "claude",
    "transport": "pty"
  }
}

Each request includes X-AgentAPI-Delivery, X-AgentAPI-Event, and X-AgentAPI-Timestamp headers.

agentapi update

Update the agentapi binary to the latest release from GitHub.

agentapi update          # download and install the latest version
agentapi update --check  # only check if an update is available
agentapi update --force  # update even if already at the latest version

agentapi attach

Attach to a running agent's terminal session.

agentapi attach --url localhost:3284

Press ctrl+c to detach from the session.

How it works

AgentAPI runs an in-memory terminal emulator. It translates API calls into appropriate terminal keystrokes and parses the agent's outputs into individual messages.

Splitting terminal output into messages

There are 2 types of messages:

• User messages: sent by the user to the agent
• Agent messages: sent by the agent to the user

To parse individual messages from the terminal output, we take the following steps:

1. The initial terminal output, before any user messages are sent, is treated as the agent's first message.
2. When the user sends a message through the API, a snapshot of the terminal is taken before any keystrokes are sent.
3. The user message is then submitted to the agent. From this point on, any time the terminal output changes, a new snapshot is taken. It's diffed against the initial snapshot, and any new text that appears below the initial content is treated as the agent's next message.
4. If the terminal output changes again before a new user message is sent, the agent message is updated.

This lets us split the terminal output into a sequence of messages.

Removing TUI elements from agent messages

Each agent message contains some extra bits that aren't useful to the end user:

• The user's input at the beginning of the message. Coding agents often echo the input back to the user to make it visible in the terminal.
• An input box at the end of the message. This is where the user usually types their input.

AgentAPI automatically removes these.

• For user input, we strip the lines that contain the text from the user's last message.
• For the input box, we look for lines at the end of the message that contain common TUI elements, like > or ------.

What will happen when Claude Code, Goose, Aider, or Codex update their TUI?

Splitting the terminal output into a sequence of messages should still work, since it doesn't depend on the TUI structure. The logic for removing extra bits may need to be updated to account for new elements. AgentAPI will still be usable, but some extra TUI elements may become visible in the agent messages.

Roadmap

Pending feedback, we're considering the following features:

• Support the MCP protocol
• Support the Agent2Agent Protocol

Long-term vision

In the short term, AgentAPI solves the problem of how to programmatically control coding agents. As time passes, we hope to see the major agents release proper SDKs. One might wonder whether AgentAPI will still be needed then. We think that depends on whether agent vendors decide to standardize on a common API, or each sticks with a proprietary format.

In the former case, we'll deprecate AgentAPI in favor of the official SDKs. In the latter case, our goal will be to make AgentAPI a universal adapter to control any coding agent, so a developer using AgentAPI can switch between agents without changing their code.