Skip to content
This repository was archived by the owner on Sep 13, 2026. It is now read-only.

README.md

Latest commit

 

History

History
256 lines (166 loc) · 11 KB

README.md

File metadata and controls

256 lines (166 loc) · 11 KB
Raw

AgentAPI

Install (SHA-256)

Pin GitHub Release v0.6.0 and verify SHA256SUMS. Website install.sh / install.ps1 abort on mismatch.

https://github.com/LinespottingOrg/GrokBuildRemote-Agents/releases/tag/v0.6.0 https://github.com/LinespottingOrg/GrokBuildRemote-Agents/blob/main/docs/PINNED-INSTALL.md

96cef605d3e030ccef99d27ea6240e0d3b668dd045e6b5b9e585c9fd03c6ef23  gbr-agent-darwin-amd64
de7e065ef2cf6877b3b2cd04679a67b627f876337f529247e236204543e4062c  gbr-agent-darwin-arm64
a50a5c41993e6531a3b477eb409ccc845212bf541384dc803061c80657f86719  gbr-agent-linux-amd64
5bfd22c7110234942c4c02ff8154b836d0af45a9422c178a4f52010187d40061  gbr-agent-linux-arm64
f773b89fd31310172b756e0593e0f3b2382b0a3440af2a7d0a8b3073b0c23e27  gbr-agent-windows-amd64.exe
8fb9efcbc7e2ac91c11964944bf0f45e31bb23f4356d9dcb4b305d7cb9b0fe8c  gbr-agent-windows-arm64.exe

VER=v0.6.0
BASE=https://github.com/LinespottingOrg/GrokBuildRemote-Agents/releases/download/$VER
# swap darwin-arm64 for your OS/arch
curl -fsSL -o gbr-agent-darwin-arm64 "$BASE/gbr-agent-darwin-arm64"
curl -fsSL -o SHA256SUMS "$BASE/SHA256SUMS"
shasum -a 256 -c SHA256SUMS --ignore-missing
gbr-agent pair && gbr-agent run

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

agentapi-chat

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!

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/coder/agentapi/releases/latest/download/agentapi-${OS}-${ARCH}" -o agentapi && chmod +x agentapi

    Alternatively, you can download the latest release binary from the releases page.

  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

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.

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.

There are 4 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 current status of the agent, either "stable" or "running"
  • GET /events - an SSE stream of events from the agent: message and status updates

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

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.

Pair a phone with Build Remote Agent

You can spectate an AgentAPI-wrapped Aider session from a phone running Build Remote Agent. Pairing uses the free MIT gbr-agent. Protocol gbr/1. The phone is spectator + veto; AgentAPI stays on :3284 and Aider stays the coding agent.

Independent product. Not affiliated with xAI or SpaceX.

Phone: open Build Remote Agent → scan the QR (or type the 8-char code). Unpair in Settings before changing PCs.

Attach only:

  • HTTP Bot API: http://127.0.0.1:8788 after gbr-agent run
  • MCP stdio: node GrokBuildRemote-Agents/mcp/gbr-mcp/bin/gbr-mcp.js
curl -sS http://127.0.0.1:8788/health
curl -sS http://127.0.0.1:8788/v1/sessions

Do not send the phone at AgentAPI :3284. Do not commit mailbox keys. Phone Settings → Bot API is the only place the relay key is copied.

Agent: https://github.com/LinespottingOrg/GrokBuildRemote-Agents (MIT)

Roadmap

Pending feedback, we're considering the following features:

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.

What the phone sees

Terminal windows on this PC (machine-wide mailbox). Not headless OpenCode / CodeNomad sidecar / Electron. :8788 in a sidecar is Bot API JSON, not a transcript.

https://github.com/LinespottingOrg/GrokBuildRemote-Agents/blob/main/docs/WHAT-THE-PHONE-SEES.md https://grokbuildremote.com/integrations.html