floating-terminal

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

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.

{
  "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.