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

# Assistants

> Connect a personal assistant that reads your account, builds agents through Builder, and suggests changes for you to approve.

A connected assistant (Grok, Muse, a scheduled Claude Code task) reads your account and suggests changes. It never approves, trades or moves funds: every suggestion waits for you in Terminal, and approval uses your passkey.

## Connect

```bash theme={null}
circuit auth login --assistant "Muse"
```

The CLI opens the same browser handoff as [`circuit auth login`](authentication). Approve with your passkey, name the connection, choose which wallets it may suggest changes for, and whether it may build new agents, suggest session actions, or suggest swaps and transfers. The permit lasts one year and is saved under the assistant's name, separate from your own login and from other assistants. Commands use your own login when one is saved, otherwise the only assistant login on the machine; when several logins share a machine, the assistant sets `CIRCUIT_ASSISTANT="Muse"` (or passes `--assistant "Muse"`) for every command. Change access or disconnect under Connected assistants in your profile menu, beside Settings and Passkeys; every request re-reads the connection's access, so changes apply to the existing permit at once and a disconnected permit is refused.

The permit carries only `account.read`. Routes that need `account.write`, such as uploading code, approving a suggestion, signing and account settings, refuse it. Free-text Terminal turns are refused too: an assistant submits reviews and builds.

## Workflow

1. **Read the account first.** `circuit terminal context` prints the snapshot Terminal reasons from: wallets (id, name, address, VM family), indexed holdings, sessions with their status, agents with their `startingAsset` (including `minimumAmountRaw`), pending operations, backtests, workspaces, and supported networks with their native asset. Use only ids and assets from this output.
2. **Build through Builder.** `circuit terminal --build "<strategy in plain words>" --wait` builds a new agent and waits for the build to finish; it needs a connection allowed to build. Assistants never edit existing agents; the user does. Never write agent files or run `circuit new` or `circuit upload`; an assistant cannot upload.
3. **Suggest changes.** Write a JSON file matching `circuit capabilities --resource terminal/review` and submit it with `circuit terminal --review <file> "<reason>"` (`-` reads stdin). The request text is recorded as the reason for the suggestion.

## Rules Circuit enforces

| Suggestion | Rule |
| - | - |
| Pause, resume, run now, stop, top up | `sessionId` must be one of the user's sessions; its state is checked when the user approves. Ended sessions need a start instead. |
| Start | `agentId`, a `walletId` the user owns, `settings` (may be `[]`), and an `allocation` in the agent's `startingAsset` (same `network` and `asset`); `allocation: null` lets the user choose. At approval the wallet needs at least `minimumAmountRaw` base units of that asset unallocated, so fund it first (for example with a swap suggestion). |
| Swap | `amount` is an exact token quantity, `{ "valueUsd" }`, `{ "balancePercent" }` or `"max"`; dollar and percent amounts convert at live prices when the suggestion is prepared. |
| Transfer | `to` must be `{ "walletId" }` of the user's own wallet; outside addresses are refused. |
| Raw `evmTx` / `solanaTx` | Refused for assistants. |
| Every suggestion | Each wallet involved must belong to the user and be allowed by the connection, and the suggestion kind (session actions, or swaps and transfers) must be allowed too. |

A refused suggestion returns the reason, for example `Assistants may only suggest transfers between your own wallets`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.