Skip to main content

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 lets external tools interact with the CTOR agent over the Agent Client Protocol. You can use tools like acpx, OpenClaw, and Agmente 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.
Bash commands run without approval in ACP mode (headless). Use acpx --deny-all to override this if needed.

​
Prerequisites

  • CTOR is running with ACP enabled
  • BRICKS 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: 
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 is a headless CLI client for the Agent Client Protocol. It manages sessions, queues prompts, and streams agent output.

​
Install acpx

npm install -g acpx

​
Basic usage

# 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: 
{
  "agents": {
    "bricks": {
      "command": "bricks desktop-acp-bridge"
    }
  }
}
Then use the short form: 
acpx bricks sessions new
acpx bricks "refactor the auth module"
acpx bricks sessions list
acpx bricks sessions close

​
Use with OpenClaw

OpenClaw 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. 
# 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
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.
Connect from a browser-style client by including the token on the upgrade request: 
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 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 above to expose the ACP socket on the LAN: 
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. Once connected, Agmente uses the 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

ItemLocation
Socket file~/.bricks-project-desktop/acp.sock
Set the BRICKS_PROJECT_DESKTOP_DATA_DIR environment variable to change the socket location along with all other app data.