> ## Documentation Index
> Fetch the complete documentation index at: https://yellowhammer.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Orca and agent CLIs

> Prepare local worktree execution and the coding agents you already use.

Prepare Orca ADE to manage [Worktrees](https://yellowhammer.dev/docs/reference/statuses-and-glossary.md#worktree) 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](https://yellowhammer.dev/docs/run/choose-agents-and-routes.md) 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](https://yellowhammer.dev/docs/setup/add-project-and-repositories.md) · [Local execution and credentials](https://yellowhammer.dev/docs/concepts/local-execution-and-credentials.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.