# Quickstart

> First successful session: open Orca, add a repo, create a worktree, launch a CLI agent terminal, and verify with `orca status` and `orca worktree current`.

- Repository: stablyai/orca
- GitHub: https://github.com/stablyai/orca
- Human docs: https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c
- Complete Markdown: https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/llms-full.txt

## Source Files

- `README.md`
- `src/cli/specs/core.ts`
- `src/cli/handlers/core.ts`
- `src/shared/tui-agent-startup.ts`
- `src/shared/tui-agent-selection.ts`
- `skills/orca-cli/SKILL.md`

---

---
title: "Quickstart"
description: "First successful session: open Orca, add a repo, create a worktree, launch a CLI agent terminal, and verify with `orca status` and `orca worktree current`."
---

Orca’s first-session path wires the Electron desktop app to a local **runtime RPC** (`status.get`, `repo.add`, `worktree.create`, terminal PTY spawn) and exposes the same control plane through the **`orca` CLI** (`package.json` registers `orca` → `out/cli/index.js`). A successful quickstart ends with `runtime.reachable: true` from `orca status` and a resolvable enclosing worktree from `orca worktree current` inside the new workspace directory.

## Prerequisites

| Requirement | Notes |
| --- | --- |
| Orca desktop app | Install from [onOrca.dev](https://onOrca.dev), GitHub Releases, Homebrew (`brew install --cask stablyai/orca/orca`), or AUR packages listed in the README. |
| `orca` on `PATH` | Shipped with the app; verify with `command -v orca`. |
| A git repository | Orca registers repos by filesystem path (`orca repo add --path`). Non-git folders are supported as `folder` repos but follow a different first-terminal path. |
| At least one CLI agent | Orca is BYOC: no Orca login. Install any supported agent binary (Claude Code, Codex, Grok, OpenCode, etc.) on `PATH`. |

<Note>
Orca does not require a specific model provider. Detection walks installed agent binaries and falls back through `TUI_AGENT_AUTO_PICK_ORDER` when no default is set.
</Note>

## Session architecture

```mermaid
sequenceDiagram
  participant User
  participant CLI as orca CLI
  participant App as Orca desktop
  participant Runtime as Orca runtime RPC
  participant PTY as PTY / agent shell

  User->>App: Launch Orca (or orca open)
  CLI->>Runtime: status.get
  Runtime-->>CLI: graphStatus ready
  User->>App: Add repo / create worktree
  App->>Runtime: repo.add / worktree.create
  Runtime->>PTY: spawn (ORCA_WORKTREE_ID, ORCA_TERMINAL_HANDLE, …)
  User->>CLI: orca status / orca worktree current
  CLI->>Runtime: status.get / worktree.show
```

## Step-by-step first session

<Steps>
<Step title="Open Orca and confirm the runtime">

Launch the Orca desktop app from your install, or start it from a shell:

```bash
orca open
```

`orca open` checks runtime reachability first; if the runtime is already up it returns immediately. Otherwise it launches the app (macOS uses `open` on the `.app` bundle when packaged) and polls every 250ms for up to **15 seconds** until `runtime.reachable` is true.

Verify readiness:

```bash
orca status
```

<RequestExample>
```bash
orca status --json
```
</RequestExample>

<ResponseExample>
```json
{
  "ok": true,
  "result": {
    "app": { "running": true, "pid": 12345 },
    "runtime": {
      "state": "ready",
      "reachable": true,
      "runtimeId": "runtime-…"
    },
    "graph": { "state": "ready" }
  }
}
```
</ResponseExample>

Human-readable `orca status` prints the same fields as lines (`appRunning`, `runtimeState`, `runtimeReachable`, `runtimeId`, `graphState`). In non-JSON mode, `orca status` sets **exit code 1** when `runtime.reachable` is false.

</Step>

<Step title="Register a repository">

In the desktop UI, add a project through the sidebar **Add repo** flow (`AddRepoDialog`), pointing at your git checkout’s root directory.

Equivalent CLI registration (paths resolve against the invoking shell’s cwd unless you pass an absolute path):

```bash
orca repo add --path /absolute/path/to/your-repo --json
orca repo list --json
```

Copy the returned `repo.id` for the next step (`id:<repoId>` selector).

</Step>

<Step title="Create an Orca-managed worktree">

In the UI, create a new workspace/worktree for the registered repo (for example via the worktree palette or add-worktree dialog). Orca creates a dedicated git worktree path and, by default, seeds a **first terminal** without switching the active workspace unless you opt in.

CLI equivalent:

```bash
orca worktree create \
  --repo id:<repoId> \
  --name my-first-task \
  --comment "quickstart seed" \
  --json
```

| Flag | Effect |
| --- | --- |
| `--activate` | Reveal the new workspace in the desktop UI (also implied by `--run-hooks`). |
| `--run-hooks` | Force `orca.yaml` setup hooks and reveal the worktree so hooks can run in the first terminal. |
| `--parent-worktree active` | Record lineage from the caller’s current Orca worktree. |
| `--no-parent` | Create an independent workspace with no parent link. |

<Info>
`orca worktree create` from the CLI spawns the initial PTY in the background (`activate: false`) and pre-allocates a terminal handle. The desktop UI path can additionally set `createdWithAgent` and launch your default or auto-detected agent via `activateAndRevealWorktree`.
</Info>

</Step>

<Step title="Launch a CLI agent terminal">

Pick any agent you have installed. The desktop uses `settings.defaultTuiAgent` when set; otherwise `pickTuiAgent` walks `TUI_AGENT_AUTO_PICK_ORDER` (`claude`, `codex`, `grok`, `copex`, …) against `detectInstalledAgents()`.

From the CLI, create a focused agent tab in the new worktree (replace the command with your agent’s launch binary from `TUI_AGENT_CONFIG`, e.g. `claude`, `codex`, `grok`):

```bash
cd /path/to/orca/worktree/checkout

orca terminal create \
  --worktree active \
  --title "Agent" \
  --command "claude" \
  --focus \
  --json
```

| Behavior | Detail |
| --- | --- |
| Default targeting | Omit `--worktree` to use the active worktree for the current directory. |
| Focus | Without `--focus`, the tab is created without stealing UI focus when possible. |
| Agent commands | Bare agent binaries (`claude`, `codex`, …) route through Orca’s renderer-backed terminal path for correct geometry. |
| Env injection | Spawned shells receive `ORCA_WORKTREE_ID`, `ORCA_TAB_ID`, `ORCA_PANE_KEY`, and `ORCA_TERMINAL_HANDLE` (pre-allocated `term_*` handle for CLI control). |

List live terminals:

```bash
orca terminal list --worktree active --json
```

</Step>

<Step title="Verify from the worktree directory">

`cd` into the Orca-managed worktree path (printed by `orca worktree list` or `worktree create` JSON). Then confirm Orca recognizes the directory and the runtime is still healthy:

```bash
orca status --json
orca worktree current --json
```

`worktree current` resolves the shell’s cwd to the **longest enclosing** Orca-managed worktree path, then returns the full worktree record via `worktree.show` (same shape as `worktree show --worktree id:<id>`).

<Warning>
On a **remote paired runtime**, `active` / `current` cwd shortcuts are rejected. Pass an explicit server-side selector (`id:`, `path:`, `branch:`, `issue:`) instead.
</Warning>

Optional human-readable check inside the worktree:

```bash
orca worktree current
# prints key: value lines for id, path, branch, comment, parentWorktreeId, …
```

</Step>
</Steps>

## `orca status` field reference

| Field | Ready signal | Other common values |
| --- | --- | --- |
| `app.running` | `true` | `false` when Orca has never started |
| `runtime.reachable` | `true` | `false` during bootstrap or after crash |
| `runtime.state` | `ready` | `not_running`, `starting`, `graph_not_ready`, `stale_bootstrap` |
| `graph.state` | `ready` | `not_running`, `starting`, `unavailable` |

<Tip>
If metadata exists but the socket is dead, `runtime.state` is `stale_bootstrap`—restart the Orca app, then rerun `orca open` and `orca status`.
</Tip>

## Worktree selectors used in verification

| Selector | Resolves to |
| --- | --- |
| `active` / `current` | Enclosing Orca worktree for shell `cwd` (local CLI only) |
| `id:<worktreeId>` | Stable runtime id (preferred after `worktree current`) |
| `path:<absolute-path>` | Worktree checkout path |
| `branch:<name>` | Branch name (ambiguous if duplicated) |
| `issue:<number>` | Linked issue number |

## CLI-only quickstart (scripted)

For automation or headless agents, the same session collapses to:

```bash
command -v orca
orca open --json
orca status --json
orca repo add --path /abs/repo --json
# capture repo.id from JSON
orca worktree create --repo id:<repoId> --name task-1 --json
cd "$(jq -r '.result.worktree.path' <<<"$WT_JSON")"
orca terminal create --command "codex" --focus --json
orca status --json
orca worktree current --json
```

Use `--json` on every call when parsing output programmatically.

## Troubleshooting

| Symptom | Likely cause | Mitigation |
| --- | --- | --- |
| `runtime_open_timeout` | App did not become reachable within 15s | Start Orca manually; retry `orca status` |
| Exit code 1 from `orca status` | `runtime.reachable` is false | `orca open`; wait for `graph.state: ready` |
| `graph_not_ready` / `unavailable` | Renderer graph not synced | Focus Orca window; wait and recheck |
| `No Orca-managed worktree contains the current directory` | Shell cwd is outside any worktree | `cd` into the worktree path or pass `--worktree id:…` |
| Empty agent terminal | No agent on `PATH` and `defaultTuiAgent` is `blank` | Install an agent binary or set a default in Orca settings |
| `selector_ambiguous` on `path:` | Duplicate repo registrations share a path | Prefer `id:` from `worktree list` |

## What you have after quickstart

- A **registered repo** known to Orca’s runtime store.
- An **Orca-managed worktree** with its own checkout path and metadata (`comment`, optional `parentWorktreeId`, linked issue fields).
- At least one **live PTY** running your CLI agent, addressable as `term_*` via `orca terminal read/send/wait`.
- Confirmed **runtime RPC** (`orca status`) and **cwd resolution** (`orca worktree current`) for later scripting.

Update the worktree comment at meaningful checkpoints:

```bash
orca worktree set --worktree active --comment "reproduced issue; implementing fix" --json
```

## Related pages

<CardGroup>
<Card title="Overview" href="/overview">
Desktop app, runtime RPC, bundled CLI, BYOC agents, and install-to-worktree flow.
</Card>
<Card title="Installation" href="/installation">
Platform packages, prerequisites, and CLI registration.
</Card>
<Card title="Worktrees and repos" href="/worktrees-and-repos">
Repo registration, worktree create/list/remove, lineage, and selectors.
</Card>
<Card title="Terminals and agents" href="/terminals-and-agents">
PTY lifecycle, agent catalog, `ORCA_*` env vars, and terminal CLI vs orchestration.
</Card>
<Card title="CLI scripting workflow" href="/cli-scripting-workflow">
End-to-end automation with `orca open`, terminals, and worktree comments.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
Runtime reachability, selector ambiguity, and terminal timeouts.
</Card>
</CardGroup>