solidcraft-upstream/docs/agent-chat.md

# Agent chat

Agent chat is a side panel where you talk to a coding agent you already use (Claude Code,
Codex, Gemini CLI, OpenCode and others), or to a model behind an OpenAI-compatible endpoint you
choose (Ollama or LM Studio on your computer, OpenAI, any other URL), and have it work on the
design that's open. A coding agent runs on your computer under **your own account** with that
agent: SolidCraft doesn't sell or proxy a model and needs no key for it. An endpoint's key, if
it needs one, goes into your system keychain, never into SolidCraft's settings.

Desktop app only.

## Turning it on and off

Everything about it is on one page: **Preferences → AI**.

- **Show AI features** (on by default) is the master switch. Turned off, SolidCraft shows nothing
  of it: no AI button, no shortcut, no menu entry, no panel, and nothing is looked for or
  started. The page stays, so you can turn it back on.
- **Show button in toolbar** (on by default): the **AI** button at the right end of the toolbar
  row, which stays there however wide the window is. Turn it off to keep only the shortcut and
  the menu entry.

With AI features on, the panel opens from:

- the **AI** button at the right end of the toolbar;
- **Ctrl+Shift+A** (Cmd+Shift+A on a Mac), which also works from the chat's own text box;
- **View settings** (the last button of the navigation bar under the view) → **Agent chat**.

Nothing runs until you need it: SolidCraft looks for installed agents (a quick `--version`
each, in the background) when the panel or the AI page first opens, and starts an agent only
when you send a message or press **Connect**.

## The panel

- **Docking:** drag the panel's header (the dotted grip and the title) to the other half of the
  window and let go. The side it would land on lights up while you drag. You can also pick
  **Left** or **Right** under Preferences → AI → Panel. SolidCraft remembers the side.
- **Width:** drag the panel's inner edge. SolidCraft remembers it.
- **Minimise** (the line in the header) folds the panel into a thin strip that keeps the chat
  icon, the agent's state, and a count of anything waiting for your answer. Click the icon to
  unfold it. **Close** (×) hides the panel. Neither stops the agent; **Stop** does.
- **The agent switcher** under the title picks the agent for this conversation; switching stops
  the one running. Next to it, when the agent has modes of its own (Claude Code has *Default*,
  *Accept Edits*, *Plan*…), a second drop-down sets the agent's mode.

## Agents

Preferences → AI → **Agents** lists every agent the chat can use, each with its kind (a program or
an endpoint), version or model, whether it looks signed in, **Test**, **Default** (the one a new
conversation starts with), its own permission setting, and **Remove** for the ones you added.

### Found by themselves

SolidCraft looks for agents that speak the [Agent Client Protocol](https://agentclientprotocol.com)
on your `PATH` and in the usual install folders a desktop app's `PATH` often misses (npm's
global folder, nvm, Volta, bun, `~/.local/bin`, Homebrew, `%APPDATA%\npm`). For each one it
shows its **version** (from `--version`, given three seconds) and whether it looks **signed in**.
SolidCraft only checks whether the agent's own login file (`~/.claude/.credentials.json`,
`~/.codex/auth.json`, `~/.gemini/oauth_creds.json`, …) or one of its key variables exists. It never
reads the file and never starts the agent to find out. On macOS Claude Code keeps its login in
the keychain, so SolidCraft doesn't guess there.

| Agent | What to install |
|---|---|
| Claude Code | `npm install -g @agentclientprotocol/claude-agent-acp` (the ACP adapter for Claude Code) |
| Codex | `npm install -g @agentclientprotocol/codex-acp` |
| Gemini CLI | `npm install -g @google/gemini-cli` (it speaks ACP itself: `gemini --acp`) |
| OpenCode | `npm install -g opencode-ai` (`opencode acp`) |
| GitHub Copilot CLI, Qwen Code, goose | listed with their install command when missing |

The panel lists agents that aren't installed with their install command and a **Copy** button.
**Refresh** looks again after you install one. **Test** starts an agent briefly, asks it for a
session and ends it again.

### Add agent…

- **Installed agent:** your own entry for an installed agent, for example with other arguments.
- **Custom command:** any other program that speaks ACP on stdin and stdout, such as
  `my-agent --acp`. SolidCraft starts it directly, not through a shell.
- **OpenAI-compatible API:** a preset (Ollama `http://localhost:11434/v1`, LM Studio
  `http://localhost:1234/v1`, OpenAI) or a custom URL, the model name, and an optional key.
  The key goes into the system keychain (Keychain on macOS, Credential Manager on Windows, the
  Secret Service on Linux) and is only ever sent over HTTPS or to this computer. **Test** asks the
  endpoint for its models. For these agents SolidCraft runs the conversation itself, with the
  same tools, limits and questions as for a coding agent, and at most 24 model requests per
  message.

## Signing in

If a coding agent isn't signed in, it says so and the panel shows **Sign in to the agent** with
the agent's own ways to sign in:

- **A command for a terminal**, e.g. `claude-agent-acp --cli auth login --claudeai`, with a **Copy**
  button. Run it in a terminal, sign in there, then press **I've signed in: connect again**.
- **A button** for agents that sign in by themselves (Codex's ChatGPT login opens your browser).
- **A variable to set** for agents that take a key from the environment. The panel has no field
  for a coding agent's key, on purpose.

Whatever you typed before signing in is sent once the agent is ready.

## What the agent can do

The agent reaches the open design only through SolidCraft's own tools (the
[MCP server](mcp.md)), which SolidCraft hands it when the chat starts:

- **Read the design:** list commands, inspect features, sketches and parameters, measure,
  take pictures of the view.
- **Change the design:** run any modelling command, alone or in a batch. Changes show in the
  window as they happen.
- **One undo per message:** everything the agent changes while answering one message becomes
  a single undo step, named after your message. The conversation shows *N changes, one undo
  step* with **Undo these changes** while nothing else has happened since.
- **Tool cards:** each tool call shows as a card with its state; click it to see what it returned.
- **Attach view:** tick it to send a picture of the current view with your message, for agents
  that take pictures.

## Permissions

Preferences → AI → **Permissions** decides what the agent may do without asking, for every agent;
each agent can have its own setting in its row.

- **Ask every time:** every change to the design and every file action waits for **Allow**,
  **Always allow** or **Deny** in the panel.
- **Auto-allow model edits** (the default): modelling commands run at once; saving, opening, exporting,
  importing, starting a new design, any command given a file name, and undoing past the start of
  your message still ask.
- **Allow everything:** nothing asks. The page warns you: the agent can then save, overwrite and
  replace your design.

**Always allow** remembers that command for that agent. The page lists what you allowed this way,
per agent, with **Reset**.

These settings cover SolidCraft's tools. A coding agent's own tools (its shell, its file edits)
follow the agent's own mode, which you pick in the panel's header. When an agent asks before
using one of SolidCraft's tools, SolidCraft answers for you, since its own gate checks the call,
and notes it in the chat as *Auto-allowed*. With **Allow everything**, or after **Always allow**,
the agent's other questions are answered the same way and noted too.

## What it can't do

- **Files wait for you** unless you chose **Allow everything**. **Cancel** or **Stop** declines
  everything that's waiting, and a question nobody answers is declined after four minutes. The
  [MCP server's folder limits](mcp.md) still apply after you allow: the design's folder, the
  recovery folder and the server's own scratch folder.
- **A limit per message.** The agent may make 24 changes per message by default; you can set
  the number on the AI page. Reading the design doesn't count. When it reaches the limit, it's
  told to stop and report what's left; send another message to let it carry on.
- **No crash reports,** whatever the permissions. Crash reports can hold other designs and file
  paths.
- **Not the rest of the app.** It can't click the interface, change settings, quit, or drive the
  chat itself.
- **Its own tools stay off where we can turn them off.** SolidCraft declares no file system and
  no terminal to the agent, runs it in an empty working folder of its own, and asks the Claude
  Code adapter to turn off its shell, file and web tools for the session.

When the panel's agent is stopped, another agent is picked, or SolidCraft quits, the agent and
every program it started (the CLI it wraps, its MCP server) are stopped.

## Privacy

Nothing goes anywhere except to the agent you run, or the endpoint you added. SolidCraft starts
a coding agent as a program on your computer and talks to it over its standard input and
output. What the agent sends to its own service, under your account and that service's terms,
is between you and that service, exactly as when you use the agent in a terminal. SolidCraft
never sees, stores or passes on a coding agent's password, token or key. An endpoint's key is
kept in the system keychain and sent only to that endpoint. SolidCraft's own connection to the
agent's tools uses a random per-launch token in a file only you can read, which never passes
through the agent.

## Trying it without an account

A scripted test agent is in the source tree. It makes a block, rounds it and measures it, with
no model behind it:

```sh
cargo build --release -p solidcraft-ui-egui --example acp_test_agent
```

Then add it under Preferences → AI → **Add agent… → Custom command** with the path of
`target/release/examples/acp_test_agent`. Put "save" in your message to see an Allow / Deny card,
or "ask" to see the agent ask its own permission.