About
Getting Started
LLM Providers
Channels
Tools
Agent Memory
Advanced
Security

ACP Sessions

ACP lets GoClaw attach to an external agent session and route your chat turns through that session instead of the normal local LLM tool loop.

Mental model:

  • GoClaw is the control plane
  • ACP is the execution plane
  • you stay inside the normal GoClaw chat experience

So ACP in GoClaw is not mainly “a tool that talks to Cursor or Grok”. It is a session-aware external agent attachment. Once attached, your normal GoClaw session is temporarily routed through that ACP session.

GoClaw supports local-stdio ACP sessions with two drivers today: the Cursor driver (cursor-agent acp) and the Grok driver (grok agent stdio). Use whichever external agent you want to steer for a particular task.

Note: The Cursor driver invokes the unambiguous cursor-agent binary rather than the bare agent command, because installing Grok on the same host overwrites the agent symlink. If you only have Cursor installed both binary names work; if you have both, only cursor-agent reliably reaches Cursor.

Current Scope

GoClaw currently supports:

  • the cursor and grok ACP drivers
  • a local stdio transport
  • session-scoped attachment through /acp commands
  • agent-facing ACP control and inspection tools
  • interactive Cursor extension flows surfaced in HTTP, Telegram, and TUI

By default, /acp attach uses the Grok driver and applies the configured friendly model alias for that driver (grok-build). Cursor remains available with /acp attach cursor, using claude-4.6-opus-high-thinking unless you change it. You can override the default driver with acp.defaultDriver, and either preferred model with acp.drivers.cursor.model / acp.drivers.grok.model in goclaw.json or through the dedicated Configuration -> ACP editor sections.

Note on Grok: grok-build-latest is what the Grok CLI itself advertises as available, but xAI’s chat proxy currently 404s on -latest for many teams. GoClaw defaults to grok-build because it works for every Grok-enabled account; promote yourself to -latest if your team has access.

ACP attachment is tied to the GoClaw session key, not to one specific UI tab or one specific chat transport. For owner sessions, that usually means the attached ACP session follows the shared primary session.

Configuration

ACP preferences live under the top-level acp config tree:

{
  "acp": {
    "defaultDriver": "grok",
    "drivers": {
      "cursor": {
        "model": "claude-4.6-opus-high-thinking"
      },
      "grok": {
        "model": "grok-build"
      }
    }
  }
}

Both setup editors expose this through a dedicated ACP section with one subsection per driver. Each driver offers a curated model dropdown plus a custom entry path while still saving only the final drivers.<driver>.model string.

The Refresh Cursor Models and Refresh Grok Models actions re-query the corresponding ACP agent and rebuild the in-memory model catalog for the current running process, then reload the ACP form so the dropdowns reflect the refreshed lists. The catalogs themselves are not written back into goclaw.json.

Authentication

  • Cursor authenticates through the ACP authenticate call using the cursor_login method; this happens automatically during attach.
  • Grok authenticates itself from ~/.grok/auth.json (set up via grok login once before first use), so no GoClaw-side login step is needed.

Common Workflow

1. Attach a session

Attach a new ACP session using the configured defaultDriver:

/acp attach

When attach succeeds, GoClaw also tries to apply the configured acp.drivers.<driver>.model alias to that ACP session. If the attached session does not expose that alias, attach fails with a clear error instead of silently picking something else.

Pick the driver explicitly, with an optional working directory or startup mode:

/acp attach cursor --cwd /path/to/project --mode agent
/acp attach grok --cwd /path/to/project

Re-attach to an existing ACP session ID:

/acp attach cursor --session SESSION_ID

2. Inspect or change mode

Check the current ACP attachment:

/acp status

The status output includes the current ACP mode and, when available, the currently selected friendly model alias.

Change the ACP mode when the driver supports it:

/acp mode plan

Typical modes used by Cursor are agent, plan, and ask. The Grok driver does not expose session modes today; /acp mode on a Grok session returns a clear “ACP driver does not support session modes” error.

List the live model aliases that the attached ACP session currently accepts:

/acp model list

Switch the attached ACP session to one of those friendly aliases:

/acp model claude-4.6-opus-high-thinking   # Cursor
/acp model grok-build                      # Grok

Use /acp model list first when you want to confirm the exact aliases exposed by the currently attached session.

3. Steer the attached session

Send a prompt into the attached ACP session:

/acp steer Review the current refactor and suggest the next safe step.

By default, steer detaches after the prompt completes so you can return to normal GoClaw chat naturally.

If you want to keep the ACP session attached for more back-and-forth turns, use:

/acp steer --stay-attached Ask the attached Cursor session to create a short plan.

Ask a quick side question without derailing the agent’s current task with /btw (or /acp btw). It interrupts the in-flight turn, answers with full context, then the agent resumes what it was doing:

/btw which files have you changed so far?

4. Finish cleanly

Use these depending on what you want:

  • /acp detach to stop routing this GoClaw session through ACP, while leaving the external ACP session available to re-attach later
  • /acp close to close the ACP session entirely
  • /acp cancel to cancel the currently running ACP prompt without closing the session

Grok Status Notices

Grok ACP sessions emit a few _x.ai/* extension methods that GoClaw handles transparently:

  • Model catalog updates — if Grok rolls out a new model mid-session, GoClaw mirrors the change into the live session so /acp model list stays accurate without re-attaching.
  • Rich error messages — when an attached Grok prompt fails (e.g. your team does not have access to the requested model), GoClaw substitutes the agent-side human-readable explanation for the generic JSON-RPC -32603 Internal error you’d otherwise see.
  • Retry notices — when Grok internally retries a failing API call, a small italic “Grok retrying after api error: …” status line appears while the turn is in progress and clears when the turn completes. HTTP shows the notice inline next to the chat input; the TUI shows it next to “Thinking…”; Telegram sends a single status message that edits in place (with a 5-second debounce so retry storms don’t trip the Telegram edit rate limit).

These do not require any configuration. To opt out of the Grok driver entirely, attach to Cursor instead (/acp attach cursor).

Slash Commands While Attached

When you attach an ACP session (with /acp attach), slash commands the agent advertises (e.g. /compact, /session-info, /help) go to the agent instead of GoClaw. This matches what you would expect if you were driving cursor-agent or grok directly: typing /compact compacts the attached session’s context, not GoClaw’s local session.

This forwarding only applies to interactive attachments — the ones you started yourself. When GoClaw’s own agent attaches a session to delegate work (via the acp_control tool), you are still talking to GoClaw, so your slash commands stay GoClaw-owned and are not forwarded to that delegated session.

A small set of session-control commands always stays GoClaw-owned regardless of what the agent advertises, so you can never lose the ability to detach or panic-stop a misbehaving session:

  • /acp — attach, detach, status, mode, model, steer, cancel, close
  • /a2a — A2A control
  • /shutdown — owner-only shutdown phrase

To run any other GoClaw builtin while attached (for example GoClaw’s own /clear or /help), detach first with /acp detach. GoClaw learns the agent’s command list from the ACP available_commands_update notification, so the routing only kicks in once the agent has announced its catalog.

HTTP Context Badge for ACP Sessions

While an ACP session is attached, the HTTP chat header’s “Context” badge reflects the attached session’s live token usage (reported by the agent) rather than the local LLM’s token counter. The badge label appends · ACP · driver/model so the source and active model are always visible, for example Context 70k / 512k (14%) · ACP · grok/grok-build.

  • Window known — Grok publishes the context budget per model via _meta.totalContextTokens; Cursor encodes it in the modelId (e.g. claude-opus-4-6[thinking=true,context=200k,effort=high]). In both cases the badge shows Context N / M (X%) · ACP · driver/model and changes color at 75% / 90% just like the local badge.
  • Window unknown — for entries that do not advertise a window (e.g. Cursor’s default[] “Auto” or composer-2[fast=true]), the badge shows Context N · ACP · driver/model with no percentage.
  • No usage reported yet — early in a session, before the agent has reported usage, the badge reads Context — / M · ACP · driver/model when the window is known or Context — · ACP · driver/model otherwise.
  • Prompt running — the badge appends the non-idle ACP state, for example Context 70k / 512k (14%) · ACP · grok/grok-build · running.

Hovering the badge shows the ACP session ID, driver, model, state, transport, CWD, token details, and last activity. The badge refreshes on send, stream/tool lifecycle events, and turn completion; while a turn is active, the browser also polls briefly so transient states like running can surface. Grok currently reports usage on the final session/prompt response, so the count does not tick during a long-running prompt. The GoClaw /context builtin still reports local-session tokens, not ACP tokens.

Interactive Behavior

Cursor ACP sessions emit interactive extension requests such as questions, plan approval flows, todo updates, delegated-task notices, and generated-asset notices. Grok ACP sessions do not currently emit interactive extension methods (see “Grok Status Notices” above for the non-interactive _x.ai/* methods Grok does emit).

GoClaw surfaces Cursor’s interactive events differently by channel:

  • HTTP/Web UI shows interactive cards for questions and plan approval, plus rendered status cards for todo, task, and generated-image events
  • Telegram uses inline buttons for single-choice and approval flows, and native polls for single-question multi-select prompts
  • TUI shows notice-only summaries so you can see what happened, but interactive responses must be handled elsewhere

If an interactive ACP prompt is waiting and you continue chatting instead of clicking the UI, GoClaw cancels the pending interactive request and treats your new message as the next turn. This avoids getting stuck behind a blocked prompt.

Limitations

Current ACP support is intentionally narrow:

  • only the Cursor and Grok drivers are supported today
  • only local stdio transport is supported today
  • the Grok driver does not advertise session modes, so /acp mode is only meaningful on Cursor sessions
  • ACP-attached sessions do not yet support normal media or other content-block turns
  • TUI currently mirrors interactive ACP events as notices rather than a full response UI

If you want to send images, audio, or other content-block input to GoClaw, detach from ACP first.

Background Delegation

GoClaw’s own agent can hand a task to an attached ACP coding agent and keep working while it runs, rather than blocking until the coding agent finishes. While the delegated agent works:

  • it stays free to keep talking to you, and you can ask “what’s it doing?” — GoClaw reports whether the agent is still working, how long since its last activity, its todo checklist, and its latest output
  • the coding agent’s live progress streams into your chat attributed to it: its spoken commentary always shows, and its raw thinking shows only when you have thinking display turned on
  • when the coding agent’s turn finishes, GoClaw is woken automatically with a completion summary so it can review the work and decide the next step

This is driven by the agent-facing acp_control tool (a background steer), not a slash command. See ACP Tools .

User Commands vs Agent Tools

There are two ACP control surfaces:

  • /acp slash commands are for you as the operator
  • acp_control and acp_inspect are agent-facing tools used internally by the GoClaw agent

That means you can also ask GoClaw to interact with an attached ACP session on your behalf, for example to inspect ACP state, switch mode, or steer the attached ACP instance through its ACP tools.

Use the slash commands for normal manual control. The agent tools are documented separately in ACP Tools .

See Also