Wire Mode - Geoff API

Wire mode is how external programs talk to Geoff Code instead of a human at a terminal. It powers custom UIs, automated testing, CI pipelines, and editor integrations. Geoff Code offers two surfaces:

Streaming JSON — geoff -p ... --output-format stream-json emits one JSON object per line for a single non-interactive turn. Ideal for scripts and pipelines.
ACP server — geoff acp exposes a full duplex session over stdio for ACP-compatible editors and IDEs.

Streaming JSON output

Run a prompt non-interactively and stream structured results to stdout:

geoff -p "List every exported function in src/ and its file." \
  --output-format stream-json

Each line of stdout is a complete JSON object. There are three message shapes.

Assistant messages

Assistant text and tool calls, in OpenAI-compatible form. tool_calls carries an id, a function.name, and JSON-encoded function.arguments:

{
  "role": "assistant",
  "content": "I'll search the source for exported functions.",
  "tool_calls": [
    {
      "type": "function",
      "id": "call_01",
      "function": { "name": "Grep", "arguments": "{\"pattern\":\"export function\",\"path\":\"src\"}" }
    }
  ]
}

Tool result messages

The output of a tool call, keyed back to its tool_call_id:

{
  "role": "tool",
  "tool_call_id": "call_01",
  "content": "src/parser.ts:12: export function parse(...)"
}

Resume hint

The final line is a meta message telling you how to resume the session you just ran:

{
  "role": "meta",
  "type": "session.resume_hint",
  "session_id": "abc123",
  "command": "geoff -r abc123",
  "content": "To resume this session: geoff -r abc123"
}

In prompt mode Geoff Code runs with permissions set to auto and approves tool calls automatically, so the turn completes without blocking for input. Combine with -y only if you also want write/shell actions auto-approved everywhere.

Consuming the stream

Read stdout line by line and JSON.parse each line:

geoff -p "Summarize the README." --output-format stream-json \
  | while IFS= read -r line; do
      echo "$line" | jq -r 'select(.role=="assistant") | .content // empty'
    done

The default --output-format text instead prints a human-readable transcript: assistant text on stdout, thinking and progress on stderr.

ACP server

For editor and IDE integrations, run Geoff Code as an Agent Client Protocol server over stdio:

geoff acp

ACP-compatible clients (such as Zed and JetBrains plugins) spawn this command and drive a full Geoff Code session — sending prompts, receiving streaming content, handling approval requests, and surfacing slash commands and skills. The server advertises built-in slash commands plus any skills available in the working directory. Clients that need to authenticate the agent re-invoke it through the terminal-auth path, which runs the device-code login flow:

geoff acp --login

This is equivalent to geoff login and exists so ACP clients can complete sign-in without leaving the editor.

Command Reference

All flags for prompt mode and the acp subcommand.

Getting Started

Non-interactive mode basics.

​Streaming JSON output

​Assistant messages

​Tool result messages

​Resume hint

​Consuming the stream

​ACP server

​Related

Command Reference

Getting Started

Streaming JSON output

Assistant messages

Tool result messages

Resume hint

Consuming the stream

ACP server

Related