> ## 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.

# CLI Agents

> Back a chat with a local CLI coding agent — Claude Code, Codex, Pi, or Cursor Agent — over ACP

A chat session can be backed by a local CLI coding agent instead of CTOR's own built-in agent. CTOR spawns the CLI and speaks [ACP (Agent Client Protocol)](/ctor/reference/acp) to it, so it can drive the agent the same way it drives its own — sending prompts, showing tool calls, and rendering the response in your chat.

<Info>
  CLI Agents is a **Preview** feature.
</Info>

<Note>
  This is the reverse of [ACP](/ctor/reference/acp): that page covers *external* tools connecting into CTOR's built-in agent. CLI Agents makes CTOR itself the ACP client, driving Claude Code, Codex, Pi, or Cursor Agent as separate CLI tools. The two don't chain together — see [Using both ACP features together](#using-both-acp-features-together).
</Note>

## Choose an engine

A new, empty chat shows an **engine** pill next to the model selector. Click it to pick a backend:

* **Built-in agent** — CTOR's own agent, the default for every chat unless you choose otherwise
* One entry per CLI engine — **Claude Code**, **Codex**, **Pi**, **Cursor Agent** — under a **CLI agents (Preview)** heading, each showing its detected version

An engine that isn't available is shown but disabled, labeled **Not installed** or **Update required — this version has no ACP support**.

<Warning>
  The engine choice locks the moment the chat has a message. There's no way to switch a chat's engine afterward — start a new chat to use a different one.
</Warning>

A session's engine also appears as a small icon next to its title in the sidebar.

## The CLI engines

| Engine           | Install                                                                                                                | Minimum version                            | Authentication                                               |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------ |
| **Claude Code**  | Bundled with CTOR — no install needed. A system install, if found, is preferred.                                       | 2.1.0 (system installs only)               | Your existing Claude Code login                              |
| **Codex**        | Bundled with CTOR — no install needed. A system install, if found, is preferred.                                       | 0.144.0 (system installs only)             | Your existing Codex login (ChatGPT or API key)               |
| **Pi**           | CTOR bundles the connector; requires a separate install of [`pi`](https://github.com/earendil-works/pi) on your `PATH` | None enforced — any detected version works | Run `pi` in your terminal to sign in and configure providers |
| **Cursor Agent** | Requires a separate install of [`cursor-agent`](https://cursor.com/docs/cli) on your `PATH`                            | 2026.01                                    | Your existing Cursor Agent login                             |

Claude Code and Codex work out of the box — CTOR bundles both the connector and the CLI itself, so there's nothing to install. Pi and Cursor Agent don't: CTOR bundles Pi's connector, but the `pi` and `cursor-agent` binaries themselves are your own installs, so each only appears as an option once you've installed it yourself (and, for Cursor Agent, once it's a 2026+ build — older builds don't support ACP).

If a CLI agent isn't logged in, CTOR shows a notice — *"{Engine} is not logged in. Run the command below in your terminal, then send your message again."* — with a **Copy** button for the login command. Run it, then send your message again.

## Enable and configure

Open **Settings > Agent > CLI Agents (Preview)**:

* **CLI Agents** toggle — turns the feature on or off. Enabled by default.
* A path override for each engine (`claude`, `codex`, `pi`, `cursor-agent`) — point CTOR at a specific binary instead of the one it detects automatically. Leave empty to auto-detect. Setting your own install lets you keep it updated yourself (`claude update` / `codex update`), with your own plugins and skills, instead of relying on the version CTOR bundles.

Each row also shows the detected version and whether it's your system install or the one bundled with CTOR.

<Note>
  Turning the toggle off doesn't remove the engine picker from new chats — it only blocks sending a message on a CLI-backed chat once you try. Turn it off before starting a chat with a CLI engine, not after.
</Note>

## Models, modes, and effort

The model, mode, and (where supported) reasoning-effort selectors on a CLI-backed chat come directly from that CLI — CTOR doesn't curate or add to the list. What's available differs by engine:

* **Claude Code** — models and modes come from your own Claude Code configuration and subscription, so the exact list varies per user. A reasoning-effort selector appears for models that support it.
* **Codex** — models bake reasoning effort into the model itself, so there's no separate effort selector; modes range from read-only to full write access. Codex sessions get a **Normal / Fast** speed toggle instead, on supporting versions.
* **Pi** — models come from your own Pi configuration. Pi treats its session modes and reasoning effort as the same underlying setting, so CTOR shows only the effort selector — no separate mode selector — with more levels than Claude Code, up to **Max**.
* **Cursor Agent** — models and modes come from your Cursor Agent installation; no effort selector.

<Note>
  A CLI engine's own "Plan" mode, where offered, is a lighter mechanism than CTOR's own [Plan Mode](/ctor/reference/plan-mode) feature. CTOR's Plan Mode isn't available on CLI-backed chats — only the CLI's own mode options are.
</Note>

## Tool approval

When a CLI agent wants to run a command or use a tool it isn't already allowed to, CTOR shows an approval card with the action and the exact response options the CLI offers — these vary slightly by engine, but always include some form of allow-once, allow-always, and reject. "Allow always" choices are remembered by the CLI itself, using whatever trust settings you already have configured for it outside CTOR.

<Warning>
  Pi is the exception: it never sends CTOR an approval request, for its own tools or for MCP tools routed through CTOR's bridge. Every Pi tool call — including file edits and shell commands — runs immediately with your OS user permissions. There's no CTOR approval card to gate it.
</Warning>

<Warning>
  CLI agent sessions run entirely outside BRICKS' [sandbox](/ctor/reference/sandbox). The CLI has the same file and shell access it would have in your terminal, governed only by its own permission system — not by BRICKS' sandbox settings, network approval, or dangerous-command detection.
</Warning>

## What the agent can do in your project

A CLI agent backing a project chat gets the same two capabilities the built-in agent has for working with your app:

* **Drive the running [Simulator](/ctor/reference/simulator)** — open it, act on the running app, and take screenshots that appear inline in the chat.
* **Make structured edits through the [Editor](/ctor/reference/editor)** — instead of hand-editing configuration files directly.

For a [main chat](/ctor/guide/main-chat) session, it gets equivalent orchestration capabilities instead — creating, listing, and managing other sessions.

If the agent needs to ask you a clarifying question, it appears as a card near the input bar, the same as the built-in agent's clarifying questions.

Your [global and project skills](/ctor/reference/skills) still work — CTOR tells the CLI agent where to find each one, and it reads the instructions the same way it reads any other file when a task calls for it.

Your project's own [MCP servers](/ctor/reference/mcp) are made available differently per engine: Claude Code reads your project's `.mcp.json` itself; Cursor Agent receives your project's and inherited servers from CTOR, with its own approval prompt for each; Pi doesn't take MCP servers natively, so CTOR instead proxies them through the same bridge as its own desktop tools, exposed to Pi as regular tools with no separate approval step (see the warning above); Codex sessions currently don't have access to your project's configured MCP servers.

## Session behavior

Most of CTOR's session features work the same on a CLI-backed chat — forking, editing and resending a message, and `/undo` all work. Because a CLI's own conversation can't be edited directly, these actions start a fresh conversation with that CLI, seeded with a summary of the history so it has context; your visible chat history in CTOR is never affected. On a very long conversation, that summary can be less complete than the CLI's own native memory would have been.

Reopening a CLI-backed chat shows your full history instantly, with no reconnection needed. If CTOR can't resume the CLI's own session in the background (for example, after a long time away or a CLI update), you'll see a one-time notice — *"CLI agent session restarted — earlier context was summarized for the agent. Your full history above is preserved."* — and the conversation continues normally.

A few built-in-agent features aren't available on CLI-backed chats:

* [`/goal`](/ctor/reference/commands#goal) and [`/compact`](/ctor/reference/commands#compact) — the CLI manages its own context, so neither command is offered.
* Mid-turn steering — a message sent while the CLI is working is queued and delivered as a follow-up once the current turn finishes, instead of redirecting it immediately.
* Custom [hooks](/ctor/reference/hooks) don't fire for the CLI's own tool calls.

The context-window indicator appears for Claude Code and Codex sessions (Codex also shows a cost estimate), but not for Pi or Cursor Agent, neither of which reports usage.

## CLI agents from the main chat

When the [main chat](/ctor/guide/main-chat) spawns a new project session, it uses the same CLI engine the main chat itself is running on by default. Ask the agent to use the built-in agent instead if you want that session to run on it.

## Using both ACP features together

A chat backed by a CLI engine can't be driven by an external ACP client (see [ACP](/ctor/reference/acp)) — it still appears in that client's session list, but attempts to load, resume, reconfigure, or prompt it from outside CTOR fail cleanly. Use CTOR's own chat UI for CLI-backed sessions.

## Next steps

<CardGroup cols={2}>
  <Card title="ACP" icon="plug" href="/ctor/reference/acp">
    Connect external tools to CTOR's built-in agent.
  </Card>

  <Card title="Sandbox" icon="shield-halved" href="/ctor/reference/sandbox">
    Understand the sandbox that CLI agent sessions run outside of.
  </Card>
</CardGroup>