terrylica/cc-skills

floating-terminal

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

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/terrylica/cc-skills --skill floating-terminal

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

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

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
FlagMeaning
--title TThe tab's title (default agent). Say what the person is being asked to do.
--cwd DIRDirectory to run in (default: the current one).
--timeout SECHow long to wait for it to finish (default 1800). A person may take a while to touch a sensor.
--tail NLines of output to return (default 40; 0 for none).
--no-logDo not record the output (for a command that prints a secret). The exit code still comes back.
--keepKeep the tab open even on success. A failed run always keeps its tab, so the person can read it.
--no-focusCreate the tab without bringing the panel forward.
--dry-runPrint 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.
from this repository

More skills

All skills
terrylica
Community

academic-pdf-to-gfm

Convert academic PDF papers to GitHub-renderable GFM markdown with math equations. TRIGGERS - PDF, GitHub markdown, math

1h installs
1
GitHub stars
2
Updated
Nov 5
terrylica
Community

adr-code-traceability

Add ADR references to code for traceability. TRIGGERS - ADR traceability, code reference, document decision in code.

1h installs
1
GitHub stars
2
Updated
Nov 5
terrylica
Community

arxiv-source-first-paper-ingest

Read an arXiv paper faithfully by fetching the authors' own LaTeX source instead of OCR-ing the PDF. Extracts every display equation with its label, environment and enclosing proposition, renders each to MathML, and proves usability by compiling each formula with a real TeX engine. Use when you need a paper's formulas exactly — to replicate a method, implement a loss function or custom objective, verify a quoted number, or check a claim against what the authors actually wrote. TRIGGERS - read th

1h installs
1
GitHub stars
2
Updated
Nov 5
terrylica
Community

azure-provision

Bootstrap Azure automation when interactive az login is blocked by a Conditional Access policy (error 530035, "Device state: Unregistered"). Mints a service principal through the Azure Portal session ONCE — using Microsoft Graph over a captured token, not DOM clicking — then provisions resource groups, Cognitive Services / AI Language / Speech resources and their keys entirely via az/REST, writing key AND endpoint together into the SCS vault. Use when az login fails but the portal works, when mo

1h installs
1
GitHub stars
2
Updated
Nov 5