> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# ACP (Agent Client Protocol)

> Connect external tools to CTOR's AI agent

ACP lets external tools interact with the CTOR agent over the [Agent Client Protocol](https://agentclientprotocol.org). You can use tools like [acpx](https://github.com/openclaw/acpx), [OpenClaw](https://openclaw.ai), and [Agmente](https://apps.apple.com/us/app/agmente/id6756249477) to send prompts, manage sessions, and orchestrate agents — all powered by the same agent, settings, and MCP tools as the desktop GUI.

## How it works

The desktop app runs a Unix socket server inside the Electron main process. The bridge CLI (`bricks desktop-acp-bridge`) pipes ACP JSON-RPC messages between stdin/stdout and the socket, so any ACP client can connect.

```
ACP client (acpx, OpenClaw, etc.)
  └─ spawns ─▶ bricks desktop-acp-bridge
                  └─ connects ─▶ Unix socket (~/.bricks-project-desktop/acp.sock)
                                    └─ CTOR (shared agent)
```

Because the socket server runs inside the app, ACP sessions share everything with the GUI:

* **Sessions** — conversations created via ACP appear in the sidebar and vice versa
* **Settings** — API keys, default model, and provider config come from the app
* **MCP tools** — `.mcp.json` tools configured in the project are available
* **Skills** — global and project skills are loaded

### Session APIs

In addition to `session/new` and `session/prompt`, the bridge supports:

* `session/list` — enumerate sessions on disk, filterable by project cwd
* `session/load` and `session/resume` — reopen an existing session and stream the full tool-call and message timeline so the client can rebuild state after a refresh or restart
* `session/set_mode` — switch the thinking level (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`)
* `session/set_model` and `session/set_config_option` — change the model mid-session using the same `provider::name` identifiers the desktop GUI exposes

While a session is active, every connected client receives the same event stream — prompts started from the GUI are mirrored to ACP clients in real time, and ACP prompts appear in the GUI as they stream.

## Enable ACP

ACP is disabled by default. To enable it:

1. Open **Settings** (gear icon in the sidebar)
2. Go to **Agent**
3. Toggle **Enable ACP**

The socket server starts immediately — no app restart needed. A green **ACP** indicator appears in the sidebar footer when ACP is active. Click it to open Settings.

<Warning>
  Bash commands run without approval in ACP mode (headless). Use `acpx --deny-all` to override this if needed.
</Warning>

## Prerequisites

* [CTOR](/ctor) is running with ACP enabled
* [BRICKS CLI](/cli) is installed (`bun add -g @anthropic-company/bricks-cli`)
* The working directory is a BRICKS project (contains `application.json`)

## Verify the connection

Test that the bridge can reach the desktop app:

```bash theme={null}
echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{},"clientInfo":{"name":"test"}}}' \
  | bricks desktop-acp-bridge
```

If you see `Cannot connect to CTOR`, make sure the app is running and ACP is enabled in Settings.

## Use with acpx

[acpx](https://github.com/openclaw/acpx) is a headless CLI client for the Agent Client Protocol. It manages sessions, queues prompts, and streams agent output.

### Install acpx

```bash theme={null}
npm install -g acpx
```

### Basic usage

```bash theme={null}
# Create a session in the current project
acpx --agent 'bricks desktop-acp-bridge' sessions new

# Send a prompt
acpx --agent 'bricks desktop-acp-bridge' "list all files and summarize the project"

# Auto-approve all tool calls
acpx --agent 'bricks desktop-acp-bridge' --approve-all "fix the linting errors"

# Quiet mode (final output only)
acpx --agent 'bricks desktop-acp-bridge' --format quiet "what does this project do?"

# JSON output for automation
acpx --agent 'bricks desktop-acp-bridge' --format json "run the tests"
```

### Persistent config

Add the agent to `~/.acpx/config.json` to avoid repeating `--agent`:

```json theme={null}
{
  "agents": {
    "bricks": {
      "command": "bricks desktop-acp-bridge"
    }
  }
}
```

Then use the short form:

```bash theme={null}
acpx bricks sessions new
acpx bricks "refactor the auth module"
acpx bricks sessions list
acpx bricks sessions close
```

## Use with OpenClaw

[OpenClaw](https://openclaw.ai) supports ACP via acpx. With the `bricks` agent configured in `~/.acpx/config.json` (see above), OpenClaw can connect to the desktop app's agent for multi-agent orchestration.

## WebSocket bridge

For ACP clients that speak WebSocket instead of stdio — including browser-based clients and the Agmente iOS app — run the bridge in `--ws` mode. Each WebSocket client opens its own dedicated connection to the ACP Unix socket; one WebSocket text frame equals one JSON-RPC message.

```bash theme={null}
# Expose on the LAN (default) with a required token — recommended
bricks desktop-acp-bridge --ws --port 8765 --auth-token "$ACP_TOKEN"

# Token can also come from the environment
BRICKS_DESKTOP_ACP_BRIDGE_TOKEN="$ACP_TOKEN" bricks desktop-acp-bridge --ws

# Restrict to localhost only
bricks desktop-acp-bridge --ws --host 127.0.0.1 --port 8765
```

<Warning>
  The default bind host is `0.0.0.0` — `--ws` is intended for LAN exposure. Always set `--auth-token` and only run on trusted networks. Without a token, any client reachable on the bound interface can connect, and the bridge prints a warning at startup.
</Warning>

Connect from a browser-style client by including the token on the upgrade request:

```js theme={null}
const ws = new WebSocket('ws://127.0.0.1:8765', [], {
  headers: { Authorization: `Bearer ${token}` },
})
ws.onmessage = (e) => console.log('from acp:', e.data)
ws.send(JSON.stringify({ jsonrpc: '2.0', id: 0, method: 'initialize', params: { /* ... */ } }))
```

## Use with Agmente

[Agmente](https://apps.apple.com/us/app/agmente/id6756249477) is an iOS ACP client that lets you talk to the CTOR agent from your iPhone or iPad. It connects over WebSocket, so use the [WebSocket bridge](#websocket-bridge) above to expose the ACP socket on the LAN:

```bash theme={null}
bricks desktop-acp-bridge --ws --port 8765 --auth-token "$ACP_TOKEN"
```

In Agmente, point the agent connection at `ws://<your-mac-ip>:8765` and supply the token. The phone and the Mac running CTOR must be on the same network — or reachable via VPN or a tunnel such as [Tailscale](https://tailscale.com).

Once connected, Agmente uses the [session APIs](#session-apis) above to list past sessions, resume them, and switch model or thinking level on the fly. Prompts you send from Agmente also stream into the desktop GUI, and vice versa.

## Copy project path

Use **Actions** (top-right dropdown) > **Copy Project Path** to quickly copy the current project's path for use with external tools.

## Data

| Item        | Location                             |
| ----------- | ------------------------------------ |
| Socket file | `~/.bricks-project-desktop/acp.sock` |

<Tip>
  Set the `BRICKS_PROJECT_DESKTOP_DATA_DIR` environment variable to change the socket location along with all other app data.
</Tip>