Skip to main content
Prepare Orca ADE to manage Worktrees and declare the local coding agent CLIs Yellowhammer can dispatch. These tools run under the macOS account that runs your Nights.

​
Check Orca readiness

Install Orca ADE and make its orca executable available on the PATH used by setup and scheduled jobs. Settings → General → Orca ADE explains this relationship; Yellowhammer has no separate Orca setting. Setup warns when it cannot resolve orca on the PATH it writes into a Project’s jobs. Orca creates, places, and cleans up Worktrees. A Worktree is a working checkout, not a security sandbox. Your agent CLI performs the code work there using its local authentication.

​
Declare an agent CLI

  1. Install and authenticate a supported CLI under the intended macOS account. The current registered adapter names are claude, codex, and agy.
  2. Open Settings → Agent CLIs.
  3. In Declare, choose the adapter name. Enter its absolute executable path in Executable (optional) when needed for unattended discovery, then choose Declare. Scheduled jobs use a minimal PATH, which can differ from your terminal’s.
  4. Open Base Routing Table and configure a route naming that declared CLI. The Add Project prerequisites require a declared CLI and a base route.
  5. Return to Agent CLIs and choose Probe Now. After a previous run, the button is Probe Again.
Declaring the first CLI can create the machine configuration before any Project exists. Declaring does not probe it.

​
Read the Probe result

The card shows the probed CLI version, adapter version, executable, and whether Routes are Offered or Not offered, including a reason when excluded. The Probe checks unattended dispatch, result-file output, and process containment. It also records session resumption and state containment findings; those two findings do not decide the overall verdict. The findings appear when the Probe finishes. Read the Probe log for output and failures. Repeat the Probe after changing the executable, authentication, or CLI version. Only one Probe runs at a time.
Planned sequence diagram
Local execution path

Show Yellowhammer coordinating Orca worktrees while an installed agent CLI performs code work on the Mac.

Planned sequence: Yellowhammer dispatches through Orca; the local agent CLI works in a Project repository; results return for review.

​
Confirm it worked

Setup can resolve Orca, the intended agent CLI is declared, a base route names it, and its Probe result offers it for dispatch. Choose agents and routes explains route-specific model and effort choices.

​
Common problems

  • Works in Terminal but is not found unattended: set an absolute CLI executable path and check the scheduled PATH used to find Orca.
  • Probe stops at authentication or a prompt: complete that CLI’s local sign-in or permission setup, then probe again before leaving it unattended.
  • No base route names a declared CLI: choose Open Base Routing Table, configure a route, then return to the Add Project sheet so it reads the updated prerequisites.

​
Next steps

Add a Project and repositories · Local execution and credentials