floating-terminal git:20261025.5b7c094A

Immutable. This exact content never changes and is served at /api/v1/blob/7a0713345c89583f.

---
name: floating-terminal
description: The default terminal for an AI coding agent running under the Orca IDE (macOS and Linux) - run any command that needs a person or a real TTY (Touch ID, a password manager's desktop-app integration, a passkey, sudo, an interactive prompt, a long visible run) in Orca's own floating terminal through Orca's CLI, and get the command's REAL exit code and output back as JSON. Use instead of opening iTerm, Terminal.app, gnome-terminal or any osascript/open-launched window, and instead of asking the person to paste a command into their shell. TRIGGERS - run this in a terminal, needs Touch ID, needs a TTY, interactive command, op signin, sudo prompt, open a terminal, floating terminal, Orca terminal, run where I can see it, human in the loop command.
allowed-tools: Bash, Read
---

# Floating terminal (Orca IDE)

> **Self-Evolving Skill**: This skill improves through use. If Orca's CLI changed, a measured fact below no longer holds, or a workaround was needed: fix this file and the script immediately, don't defer. Only update for real, reproducible issues.

An agent's own Bash tool has no terminal a person can see or answer, and some tools refuse to run without one: biometric unlock, a password manager's app integration, `sudo`, passkeys, anything that prompts. Under the Orca IDE the answer is **Orca's floating terminal**, driven only through Orca's own CLI: one panel that exists on every Orca desktop, opened and read without any other app. [`scripts/orca-float`](./scripts/orca-float) does it in one call and hands back the result.

## When to use it — the default order

1. **The agent's own Bash tool** for anything non-interactive. It stays the first choice.
2. **`orca-float run`** for anything that needs a person, a TTY, or should stay visible. This is the default terminal for agents under Orca.
3. **Ask the person to run it themselves** only when Orca is absent (`orca-float doctor` exits 3) or its floating terminal is disabled.

Never open iTerm, Terminal.app, gnome-terminal, `osascript … do script`, or `open -a Terminal` for this: those windows are outside Orca, give no exit code back, and leave windows behind.

## Use

```bash
FLOAT="$(cc-plugin-root orca-tools)/skills/floating-terminal/scripts/orca-float"
"$FLOAT" doctor                                        # is the floating terminal usable here? (creates and closes a probe)
"$FLOAT" run --title "Unlock" -- some-cli signin       # runs, waits, returns JSON; the person answers any prompt in the panel
"$FLOAT" run --cwd ~/repo --timeout 600 -- ./script.sh --flag "two words"
"$FLOAT" open --title "Shell"                          # an interactive floating shell for the person; prints its handle
```

| Flag            | Meaning                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------ |
| `--title T`     | The tab's title (default `agent`). Say what the person is being asked to do.                     |
| `--cwd DIR`     | Directory to run in (default: the current one).                                                  |
| `--timeout SEC` | How long to wait for it to finish (default 1800). A person may take a while to touch a sensor.   |
| `--tail N`      | Lines of output to return (default 40; `0` for none).                                            |
| `--no-log`      | Do not record the output (for a command that prints a secret). The exit code still comes back.   |
| `--keep`        | Keep the tab open even on success. A failed run always keeps its tab, so the person can read it. |
| `--no-focus`    | Create the tab without bringing the panel forward.                                               |
| `--dry-run`     | Print the launcher it would run and create nothing.                                              |

One argument after `--` is run as a shell command line (`-- 'a | b'`); several are quoted word by word.

**Output:** stdout is one JSON object; progress goes to stderr.

```json
{
  "ok": true,
  "state": "finished",
  "exit_code": 0,
  "handle": "term_…",
  "tab_closed": true,
  "seconds": 4,
  "output": "…last lines…"
}
```

`state` is `finished`, `timeout` (still running; the tab stays) or `gone` (the person closed the tab). Exit status: 0 ok, 1 the command failed or did not finish, 2 usage, 3 no Orca CLI found.

**Tell the person before you call it** — "a floating terminal will open and ask for Touch ID" — because the run blocks until they answer or `--timeout` passes.

## Secrets

- A command that **prints** a secret: use `--no-log`, and do not ask for its output. Better, have it write the secret to its destination (a vault, a keychain) itself.
- Never put a secret in the command line: it is written to a temporary script (mode 700 directory, removed after the run) and shown in the panel.
- The output log is the same bytes the panel shows. It is deleted after the run; only `--tail` lines come back.

## How it works, and the measured facts behind it

Measured on Orca 1.4.2xx on macOS:

- `orca terminal create --worktree id:global-floating-terminal --command …` opens a tab in the floating terminal and runs the command in a login shell there. `orca terminal show` reports that tab's `worktreeId` as `global-floating-terminal`; `doctor` checks exactly that.
- **`orca terminal wait --for exit` cannot be trusted for the exit code**: it reported `exitCode 0` (`exitCause host_status_unavailable`) for a command that exited 7. And `orca terminal read` returns nothing once the shell has exited. So the script never relies on either: the command runs under `script` (a real TTY, so prompts and biometric unlock work, and every byte shown is also logged), writes its own exit status to a file, and the script polls that file — at most `--timeout` one-second ticks, checking every 15 s that the tab still exists.
- `script` differs between BSD (macOS) and util-linux; the launcher picks the right form at run time.
- Every `orca terminal` call names its handle. Omitted, Orca uses the active terminal, which may be another session's. Only the tab this run created is ever closed, never with `--all`.

Linux: the same Orca CLI and the same launcher (util-linux `script`). The CLI is found by the plugin's shared finder (`scripts/lib/orca-cli.sh`): `$ORCA_CLI`, `$ORCA_CLI_BIN_DIR/orca`, an `orca` on `PATH` that is really Orca's, `orca-ide` (the CLI's name on Linux: `/opt/Orca/resources/bin/orca-ide`, linked as `~/.local/bin/orca-ide`), then Orca's own install locations. On Linux desktops `/usr/bin/orca` is often the GNOME screen reader, so a bare `orca` is never trusted.

The Orca CLI talks to the Orca app of the **same user**: over SSH as another account, `doctor` reports Orca's own `runtime_unavailable` reason. The floating terminal is a local panel: this skill drives the Orca on the machine it runs on, not a paired runtime.

## Requirements

The Orca IDE CLI with the floating terminal enabled in Orca's settings, `bash ≥ 3.2`, `python3 ≥ 3.9`, and `script` (present on macOS and in util-linux).

## Post-Execution Reflection

1. **Did the JSON match what the person saw in the panel?** If the exit code or output differed, fix the launcher and add a test.
2. **Did a tab stay behind after a successful run, or close after a failed one?** Fix the close rule.
3. **Did a secret appear in `output`?** That run should have used `--no-log`; say so above if the case was not covered.