# Orca or direct

A machine runs each card in one of two places. With Orca installed, a run gets an Orca worktree and terminal. Without
it, the machine runs in **direct mode**: a git worktree, and the coding agent in the agent's own tmux. Orca is
optional.

## What a machine needs

| Tool | Why | Install |
|---|---|---|
| git | a worktree for each card | `xcode-select --install` on a Mac, or your distro's `git` |
| tmux | the session each run lives in | `brew install tmux`, `apt-get install tmux`, `dnf install tmux`, `pacman -S tmux` |
| Claude Code | cards on Claude Code | offered by setup on a Mac with the Claude app, or `--install-claude`; then `claude auth login` |
| Codex CLI | cards on Codex | `npm install -g @openai/codex` (or `brew install codex`), then `codex login` |
| Gemini CLI | cards on Gemini CLI | `npm install -g @google/gemini-cli`, then [sign in through Andon](https://andon-docs.pages.dev/machines/accounts-and-providers.md#sign-in-to-gemini-cli) |
| gh (optional) | pull requests from card branches | `brew install gh` or your distro's package, then `gh auth login` |

A machine needs at least one of Claude Code, Codex and Gemini CLI. The installer checks for these and enrolls the
machine: [Mac](https://andon-docs.pages.dev/machines/macos.md), [Linux](https://andon-docs.pages.dev/machines/linux.md), [Windows](https://andon-docs.pages.dev/machines/windows.md).

The agent looks for each CLI at every sync. **Settings → Machines** lists a machine's agents under **Advanced**
(*Agents: Claude Code, Codex*). A Codex card goes only to a machine that reports Codex. After you install a CLI, press
**Sync** (the circular arrows) on the machine's card, or wait for the next heartbeat.

On a Mac with the Claude app but no `claude`, setup offers to install Claude Code with Anthropic's installer and sign it
in with the account you use in the app. `--install-claude` installs it unattended (the sign-in then waits for you),
`--no-install-claude` skips the question, and `--yes` alone never installs it. To add it later:
`andon setup --install-claude`.

## How a machine picks: Orca or a terminal

Where a card runs is not a board setting. The agent decides per run:

1. A machine with the `orca` command runs cards in Orca. One without it runs them in a terminal (direct mode).
2. A repository's `.andon/settings.json` can ask for one with `runtime` under `automation`: `auto` (the default), `orca` or `terminal`.
   A run that asks for Orca on a machine without it runs in a terminal.
3. The machine's policy can turn either off: `andon policy runtimes orca,terminal` lists the ones it allows. A run
   that asks for one the policy turns off fails with the reason, and the card offers **Run on another machine**.

To keep a machine in direct mode even though Orca is installed, set `"launcher": "direct"` in
`~/.config/andon/config.json` and restart the agent.

The board labels a direct machine **Direct** and hides **Focus in Orca** and **Adopt Orca worktrees** for it. The run
panel's heading ends with where the run went, for example *Codex · gpt-5-codex · Terminal*.

## Direct mode

In direct mode, and for any run in a terminal:

- Each run gets a git worktree at `<projectsRoot>/worktrees/<repo>/<branch>` on its own `andon-…` branch.
  `projectsRoot` defaults to `~/Projects`.
- The coding agent runs in the tmux session `andon-<run id>` on the agent's own socket. List them with
  `tmux -L andon ls`.
- Every run's session lives in that one tmux server, so if the server goes away, every run on the machine ends with
  it. The agent notices within 15 seconds and writes one line to its log (the socket, when the server last answered,
  the sessions and runs it took, and what the agent could tell about why: the process exited, or it still runs but its
  socket file was removed). Settings → Machines shows *tmux server stopped at 15:31; 5 runs interrupted* (or
  *restarted*, when a new server had already taken its place by the time the agent noticed) for a week, and
  `andon doctor` shows the last one. Each run that was still working and hadn't opened its pull request ends
  **Interrupted**, and Needs you offers **Resume** (or **Resume all**, for several at once): see
  [An interrupted run](https://andon-docs.pages.dev/guide/needs-you.md#an-interrupted-run).
- A run's command doesn't see `$TMUX` or `$TMUX_PANE`, so a bare `tmux kill-server` (or any bare `tmux` command) in
  a run, or in a tool the coding agent runs, reaches the default tmux server, not the agent's. Naming the socket,
  `tmux -L andon …`, still reaches it: don't put that in a recipe or a card.
- The agent finds repositories by scanning its scan roots. `andon repos` lists and edits them.

## Show in Terminal

A run in a terminal has two terminal items in its ⋯ menu:

- **Open terminal** opens the board's own terminal, in the browser on any device, attached to the run's tmux session.
  What you type goes to the session; **Read-only** turns that off.
- **Show in Terminal** opens a window on the machine itself, attached to the same session. It takes the place of
  **Focus in Orca**. The board shows it only when the machine can open a window: always on a Mac; on Linux only with a
  display and `x-terminal-emulator`; never on a server.

On a Mac the window opens in Terminal unless `andon policy terminal-app <app>` names another (iTerm, Ghostty, …).
`andon policy auto-open-terminal on` opens it by itself as each interactive run starts. Closing the window detaches;
the run keeps going.

When the coding agent shows its own prompt in the terminal, one the board can't answer, the card says *Claude is
waiting in its terminal* (or Codex, or Gemini), with **Open terminal**, **Show in Terminal** (or **Focus in Orca**)
and **Interrupt**.

## Choose the agent and model

The workspace's default is under **Settings → Automation**: **Agent** (Claude Code, Codex or Gemini CLI) and **Model**.
A team can change both under **Settings → Teams →** the team **→ Overrides**. A card can change them in its
properties: **Agent** and **Model**, where **Default for this team** follows the team.

For Codex and Gemini CLI, a model is the name the CLI takes (for example `gpt-5-codex`, or a `gemini-…` name); empty
means the CLI's own default. Changing the agent resets the model. Accounts are on
[Several CLI accounts](https://andon-docs.pages.dev/machines/accounts-and-providers.md).

## Codex

- **One Codex home per machine.** Andon runs Codex with `CODEX_HOME` set to `~/.local/state/andon/codex-home`. It holds
  the sessions (so **Continue** resumes them), Andon's hooks and the trusted worktrees. Your login is linked in from
  `~/.codex/auth.json` (or `$CODEX_HOME/auth.json` if you set `CODEX_HOME`). Andon never writes to `~/.codex`.
- **The first run on a machine** asks you to trust Andon's hooks. The card shows *Codex is waiting in its terminal*.
  Press **Open terminal** and choose *Trust all and continue*. Andon never answers this screen for you, and offers no
  Interrupt there (Escape would skip the hooks). You answer it once per machine, and again only when Andon's hooks
  change.
- **Permissions** come to the board like Claude's: *Codex needs a decision*, the command, Codex's reason, **Allow** or
  **Deny**. Each Andon permission mode maps to a Codex sandbox and approval policy, never a bypass or full-auto mode.
- **Interrupt** (or Escape in Codex) ends the turn, and the card goes to *Waiting for you*.
- **A live session can't switch model** (Codex's `/model` is a picker). Stop the session and **Continue** on the other
  model.
- **Headless runs** (`codex exec`) can't write `.git` from Codex's sandbox, so Andon commits what Codex changed on the
  card's branch when the run ends.

## Gemini CLI

Gemini CLI runs a card in the run's tmux session or headless, and can review a team's own pull requests. Pick it as the
**Agent** (above) or as the team's **Reviewer** (search Settings for **Reviewer**).

- **A Gemini home per account.** Andon sets `GEMINI_CLI_HOME` to the run's account. The machine's own login is
  `~/.local/state/andon/gemini-home`; an account added with `andon accounts add gemini <name>` is its own home. Andon
  never reads or writes `~/.gemini`. Sign in once per home: [Gemini CLI sign-in](https://andon-docs.pages.dev/machines/accounts-and-providers.md#sign-in-to-gemini-cli).
- **Google's models only.** A Gemini run on a provider's model (`openrouter/…`) fails with *Gemini CLI runs on Google's
  models only*.
- **Trust.** Andon trusts each card worktree for Gemini before it starts, so Gemini doesn't ask. It never trusts
  someone else's checkout, because trusting a folder loads that folder's own `.gemini/` settings, hooks and MCP servers.
  A Gemini review of someone else's pull request is refused. If Gemini asks *Do you trust the files in this folder?*,
  the card says so: answer it in the terminal.
- **Permissions.** Andon's `plan` mode runs Gemini in its plan mode; `dontAsk` and `manual` run its default mode;
  `acceptEdits` and `auto` run it in `auto_edit`. Andon never passes `yolo`. In `dontAsk` and `acceptEdits`, the
  recipe's allowed shell commands and edit tools run without asking. Anything else asks in Gemini's own prompt, and the
  card shows that prompt with its options as buttons (*Allow once*, *Allow for this session*, *No, suggest changes*).
  *No, suggest changes*, like **Interrupt**, cancels the whole turn, and the card goes to *Waiting for you*: reply to
  say what to do instead.
- **Switching the model** of a live session types `/model set <model>` (for this session only), then your text.
- **Headless runs** (a headless card, a pipeline step, a review round) leave out every tool that would ask. They run
  only the shell commands the recipe allows, and edit only in `dontAsk` and `acceptEdits`; a `plan` run edits nothing.
  Andon commits what the run changed on the card's branch when it ends.
- **Review rounds** run on the team's own pull requests only. Andon commits and pushes Gemini's fixes before it records
  the round.

## The machine's policy

The machine's local policy has the final say over what runs on it. It lives in the config file under `policy`.

- `andon policy` prints it as rows: what each key allows or blocks, and the command that changes it.
- `andon policy show` prints the raw JSON.
- The board shows the same rows: **Settings → Machines**, open **Advanced** on the machine's card, then
  **Local policy**, with the preset it matches. They are read-only, except in the desktop app on the computer it runs
  Andon on, where a row that holds something back has a button that runs its fix
  ([Fix this machine's policy in the app](https://andon-docs.pages.dev/guide/desktop-app.md#fix-this-machines-policy-in-the-app)).

### Presets

Setup ends by asking for a preset (`--preset locked|standard|open` answers it unattended). `andon policy preset <name>`
switches later. A preset sets four things; every other key keeps its value.

| Preset | Recipes | Auto merge | New repositories (clone, Start from a folder) | Terminal input from the board |
|---|---|---|---|---|
| **Locked** | each needs `andon policy approve <recipe>` on the machine | off | off | off |
| **Standard** | the org's current ones approved; new or edited ones need approving on the machine | allowed | allowed | on |
| **Open** | any recipe from the org | allowed | allowed | on |

Unattended, and when you press Enter at the question, setup picks Open, so editing a recipe on the board never stops
this machine's runs. Pick Standard or Locked when each recipe change should be approved on the machine first.
`--trust-org`, `--approve-current`, `--allow-auto-merge` and `--no-auto-merge` adjust the preset after it is applied.

### Agents and runtimes

| Key | Default | Command | What it does |
|---|---|---|---|
| `allowedExecutors` | Claude Code, Codex and Gemini CLI | `andon policy executors claude,codex` | The agent CLIs this machine runs cards with. A card on another fails before anything is made: *<machine>'s policy doesn't allow Codex*. |
| `allowedRuntimes` | Orca and terminal | `andon policy runtimes orca,terminal` | Where runs may live (see [How a machine picks](#how-a-machine-picks-orca-or-a-terminal)). |
| `terminalApp` | Terminal | `andon policy terminal-app iTerm` | The Mac app **Show in Terminal** opens. |
| `autoOpenTerminal` | off | `andon policy auto-open-terminal on` | Opens that window by itself as each interactive run starts. |
| `extraArgs` | accept | `andon policy extra-args refuse` | Whether runs here take the extra arguments set on the board (below). |

A refused run changes nothing on the machine, and the card offers **Run on another machine**. Settings → Machines shows
an agent the policy turns off: *Agents: Claude Code · Codex off in its policy*.

The config file's `bins.claude`, `bins.codex`, `bins.gemini`, `bins.tmux` and `bins.git` point at a CLI that isn't on
the agent's `PATH`.

Every `andon policy` key is listed in `andon --help`.

### Extra arguments

A machine can add its own flags to every coding-agent session it starts, `--chrome` for example.

1. Open **Settings → Machines** and find the machine.
2. Open **Advanced**.
3. Under **Extra arguments**, type the flags for Claude Code, Codex or Gemini CLI. Only the machine's owner can change
   them.

The next session picks them up, interactive and headless, but not Codex review rounds. They go on the command line
after Andon's own flags. The machine can refuse them all with `andon policy extra-args refuse`.

Extra arguments may only add behaviour, so only flags known to do that are taken. The board checks them as you type
and the machine checks again at launch. These are the flags a machine can add:

| CLI | Flags |
|---|---|
| Claude Code | `--chrome`, `--no-chrome`, `--ide`, `--verbose`, `--ax-screen-reader`, `--brief`, `--debug [filter]` (`-d`), `--debug-file <path>`, `--effort <level>`, `--autocompact <size>`, `--name <name>` (`-n`) |
| Codex | `--search`, `--no-alt-screen`, `--strict-config`, `--image <file>` (`-i`) |
| Gemini CLI | `--debug` (`-d`), `--screen-reader` |

Any other flag is refused, including ones the CLI doesn't list in its help: Andon sets permissions, settings, MCP,
the session, the prompt and the model itself. A word after a flag is that flag's value only when the flag takes one;
otherwise it would be the prompt or one of the CLI's commands (`exec`, `mcp`, `plugin`), and is refused. For Claude
Code's `--debug`, put the filter after `=` (`--debug=mcp`). The text is split into words the way a shell would, but nothing is expanded
and it never goes through a shell. A run whose arguments break a rule fails with the reason.

## Check it

1. In **Settings → Machines**, the machine is online and lists the agents you installed.
2. Run a card on a direct machine. The run heading ends in *Terminal*, and `tmux -L andon ls` on the machine lists
   `andon-<run id>`.
3. **Show in Terminal** opens a window attached to the session. Reply from the board, and the reply shows up in it.
