09. Automation and Editor Integration

ACP / stdio

Embed Matcha CLI in an editor or SDK as a long-lived local assistant. The transport this product supports for that job is **stdio** over the Agent Client Protocol (ACP).

How ACP talks to Matcha

ACP is JSON-RPC: the client owns stdin/stdout, and Matcha CLI runs as the ACP agent process. A typical session is four calls you can implement by hand or with an SDK:

initialize — protocol version and client capabilities
session/new — working directory (and optional _meta)
session/prompt — the user turn
session/update notifications — streamed text, thoughts, and tool calls

Standard ACP method names (initialize, session/new, session/prompt, session/update) are not rewritten. Private extensions use the Matcha namespace io.github.iampaco.matcha/*. Receivers still accept legacy x.ai/* names.

This is not headless -p (one prompt, then exit).

Start the process

Start the assistant explicitly in stdio mode:

matcha agent --always-approve stdio

Flags that apply to every matcha agent transport go **after** agent and **before** the mode name. Mode-specific flags go after the mode.

Flag	Role
`-m, --model`	Model ID
`--always-approve`	Alias `--yolo`. Skip interactive tool-permission prompts.
`--reauth`	Authenticate before the assistant starts (visible alias `--reauthenticate`).
`--agent-profile <PATH>`	Load a profile file.
`--plugin-dir <DIR>`	Extra plugin directory for this process (repeatable; trusted).
`--leader` / `--no-leader`	Attach to a shared leader, or force a local assistant.

session/new can set always-approve for that session only:

{
  "cwd": "/path/to/project",
  "mcpServers": [],
  "_meta": { "yoloMode": true }
}

Other _meta fields: rules, systemPromptOverride, agentProfile, autoMode. yoloMode wins over autoMode.

While a prompt is running, the assistant sends session/update notifications. Switch on sessionUpdate:

Value	Meaning
`agent_message_chunk`	Response text
`agent_thought_chunk`	Reasoning
`tool_call`	A tool started
`tool_call_update`	Progress or result
`plan`	Current plan

Discover extra methods from the initialize result. Do not treat the legacy x.ai/* tables in older how-tos as a complete list. Feedback and product-telemetry extensions stay disabled.

When to use stdio

Use stdio when a client must keep a session open: an editor that already speaks ACP, an eval harness, or a small program that streams tool calls into its own UI. Headless -p is simpler when you only need the final text.

Editors that already speak ACP (Zed, some Neovim and Emacs packages, marimo) can spawn matcha agent stdio themselves. Official ACP client libraries exist for TypeScript, Rust, Python, Go, and Kotlin; see https://agentclientprotocol.com.

Send a prompt

Minimal local server for an SDK or editor:

matcha agent --always-approve --model <your-model-id> stdio

JSON-RPC is one object per line on stdin/stdout. After initialize and session/new, a prompt looks like:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/prompt",
  "params": {
    "sessionId": "<id from session/new>",
    "prompt": [{ "type": "text", "text": "List the files in this project" }]
  }
}

The client then reads session/update notifications until the prompt result arrives.

Always-approve on the command line is the usual CI/SDK default. Deny rules and hooks still apply. Interactive TUI users normally leave ask mode.

What is unavailable

**Product relay** and **relay session sync**. Do not run matcha agent headless, pass --grok-ws-url, or open a grok.com / official-cloud WebSocket. Bare matcha agent (no stdio / serve / leader mode) follows that relay path — always pass stdio for BYOK editor embeds.
**Account login inside ACP** (x.ai/auth/* device/OAuth helpers). Configure a Provider key on the machine first.
**Feedback and telemetry** extension methods.