🐋 orca
commandsconfig
github ↗

orca

Coordinated agent run harness. Breaks down a task into a graph of tasks, then executes it end-to-end via a persistent Codex session with full context across tasks.

Install
shell
npm install -g orcastrator
Commands

orca <task>

usageorca [task] [flags]

Start a new run from a plain-language task. Orca first runs a low-effort planning-necessity decision, then either generates a full plan for multi-step work or executes directly when one focused task is enough.

shell
# Run a taskorca "add auth to the app"# Run with a spec or plan fileorca --spec ./specs/feature.mdorca --plan ./specs/feature.md

Flags

[task]Plain-language task (positional)
--task, -p, --prompt <text>Task as a named flag (alias for positional)
--spec <path>Path to a spec/markdown breakdown file
--plan <path>Path to a plan file (same as --spec)
--config <path>Path to an orca config file
--on-milestone <cmd>Shell command to run on each milestone
--on-error <cmd>Shell command to run on error
--codex-onlyForce Codex executor for this run
--codex-effort <low|medium|high|xhigh>Override Codex effort for this run
--on-task-complete <cmd>Shell command to run when a task completes
--on-task-fail <cmd>Shell command to run when a task fails
--on-invalid-plan <cmd>Shell command to run when planner/review output is invalid
--on-findings <cmd>Shell command to run when post-execution review reports findings
--on-complete <cmd>Shell command to run when the full run completes
-h, --helpShow help
-V, --versionShow version

orca plan

usageorca plan [flags]

Plan tasks without executing them. Useful for reviewing the task breakdown before committing to a run.

shell
orca plan --spec ./specs/feature.md

Flags

--spec <path>Path to a spec/markdown breakdown file
--config <path>Path to an orca config file
--on-milestone <cmd>Shell command to run on each milestone
--on-error <cmd>Shell command to run on error

orca status

usageorca status [flags]

Without --run or --last, lists all runs as a summary table. With --run or --last, shows detailed status for a specific run — tasks completed, in-progress, pending, or failed.

shell
orca status            # list all runs (summary table)orca status --last     # status of the most recent runorca status --run <id> # status of a specific run

Flags

--run <run-id>Show status for a specific run ID
--lastShow status for the most recent run
--config <path>Path to an orca config file

orca list

usageorca list [flags]

List all runs stored in the runs directory.

shell
orca list

Flags

--config <path>Path to an orca config file

orca resume

usageorca resume [flags]

Resume a paused or interrupted run from where it left off.

shell
orca resume --lastorca resume --run feature-auth-1766228123456-1a2b

Flags

--run <run-id>Resume a specific run by ID
--lastResume the most recent run
--config <path>Path to an orca config file
--codex-onlyForce Codex executor for this resume
--codex-effort <low|medium|high|xhigh>Override Codex effort for this resume

orca cancel

usageorca cancel [flags]

Cancel a running or paused run.

shell
orca cancel --lastorca cancel --run feature-auth-1766228123456-1a2b

Flags

--run <run-id>Cancel a specific run by ID
--lastCancel the most recent run
--config <path>Path to an orca config file

orca answer

usageorca answer <run-id> <answer>

Provide an answer to a run that is blocked waiting for input.

shell
orca answer feature-auth-1766228123456-1a2b "yes, use migration A"

Flags

[run-id]Run ID (positional)
[answer]Answer text (positional)
--run <id>Run ID as a named flag (alias for positional)

orca pr

usageorca pr <subcommand> [flags]

Manage pull requests for a run. Subcommands: draft, create, publish, status.

shell
orca pr                          # default pr actionorca pr draft   --run <run-id>   # open a draft PRorca pr create  --run <run-id>   # create a PRorca pr publish --run <run-id>   # publish (un-draft) the PRorca pr status  --run <run-id>   # check PR status

Flags

--run <run-id>Target a specific run by ID
--lastTarget the most recent run
--config <path>Accepted for compatibility; currently unused by PR command run resolution

orca pr publish

usageorca pr publish [flags]

Publish a draft PR for a run (ready for review). In TTY mode, run selection is interactive when --run/--last is omitted; non-TTY requires --run or --last.

shell
orca pr publish --run <run-id>orca pr publish --lastorca pr publish --config ./orca.config.js   # accepted, currently unused by PR command resolution# Non-TTY requires explicit selectionorca pr publish --last

Flags

--run <run-id>Target a specific run by ID
--lastTarget the most recent run
--config <path>Accepted for compatibility; currently unused by PR command run resolution

orca setup

usageorca setup [flags]

Configure API keys and environment. Supports scoped config (global or project-level).

shell
orca setup                      # auto-detect (default)orca setup --openai-key sk-...orca setup --openai-key sk-...orca setup --executor codexorca setup --ts --global         # write to ~/.orca/config.tsorca setup --ts --project        # write to ./orca.config.ts

Flags

--openai-key <key>Set OpenAI API key
--executor <codex>Explicitly set executor in written config
--tsWrite TypeScript config output (.ts) instead of .js
--globalWrite global config (~/.orca/config.js by default, or .ts with --ts)
--projectWrite project config (./orca.config.js by default, or .ts with --ts)
--project-config-templateWrite a typed project hook template to ./orca.config.ts
--skip-project-configDo not prompt to generate a project config template

orca skills

usageorca skills [flags]

List loaded skills and their sources.

shell
orca skillsorca skills --config ./orca.config.js

Flags

--config <path>Path to an orca config file

orca help

usageorca help [command]

Show help for any command.

shell
orca helporca help planorca help prorca --help
Config

Config Discovery

Orca auto-discovers config in this order — later entries override earlier ones:

  1. ~/.orca/config.ts (takes precedence when both exist) or ~/.orca/config.js — global user config
  2. ./orca.config.ts (takes precedence when both exist) or ./orca.config.js — project config
  3. --config <path> — explicit override

Run state is stored at <runsDir>/<run-id>/status.json. Defaults to ~/.orca/runs unless overridden by ORCA_RUNS_DIR.

Validator caveat: ORCA_SKIP_VALIDATORS=1 forces review.execution.validator.auto off at runtime.

Project Instruction Files

During planning, Orca automatically injects project instruction files when present:

  1. AGENTS.md

Orca resolves the project root from the nearest .git and injects AGENTS.md when present.

Config Options

Full example — all options are optional:

ts
// orca.config.tsimport { defineOrcaConfig } from "orcastrator";export default defineOrcaConfig({  executor: "codex",  openaiApiKey: process.env.OPENAI_API_KEY,  runsDir: "./.orca/runs",  sessionLogs: "./session-logs",  skills: ["./.orca/skills"],  maxRetries: 1,  codex: {    enabled: true,    model: "gpt-5.3-codex",    thinkingLevel: {      decision: "low",      planning: "high",      execution: "medium",    },    command: "codex",    timeoutMs: 300000,    multiAgent: false,  },  pr: { enabled: true, requireConfirmation: true },  review: {    // Deprecated aliases: review.enabled / review.onInvalid    plan: { enabled: true, onInvalid: "fail" },    execution: {      enabled: true,      maxCycles: 2,      onFindings: "auto_fix",      validator: { auto: true },    },  },});

Field reference

Top-levelexecutor, openaiApiKey, runsDir, sessionLogs, skills, maxRetries, hooks, hookCommands, pr, review, codex
maxRetriesAccepted OrcaConfig field; current planner-generated task retry limits remain fixed by task graph contracts
codex.*enabled, model, effort, thinkingLevel.decision|planning|execution, command, timeoutMs, multiAgent, perCwdExtraUserRoots
pr.*enabled, requireConfirmation
review.plan.*enabled, onInvalid
review.execution.*enabled, maxCycles, onFindings, validator.auto, validator.commands, prompt
Deprecated aliasesreview.enabled, review.onInvalid

Thinking-level controls are explicit: use codex.thinkingLevel.decision|planning|execution with canonical values low|medium|high|xhigh .

On Codex session startup, Orca calls app-server skills/list with cwds: [cwd], forceReload: true and optional perCwdExtraUserRoots .

Hooks

Function hooks are primary (hooks) and are strongly typed with `defineOrcaConfig`. Command hooks (hookCommands) are supported via config or CLI --on-... flags.

onMilestoneFired at each milestone checkpoint
onTaskCompleteFired when a single task completes successfully
onTaskFailFired when a task fails
onInvalidPlanFired when planner/review output is invalid
onFindingsFired when post-exec review reports findings
onCompleteFired when the entire run completes successfully
onErrorFired on run failure and on hook-dispatch/command-hook failures

Hook handler context is deterministic: { cwd, pid, invokedAt }.

Command hooks receive structured event payload JSON on stdin.

Interactive hook flow

If a run needs operator input, Orca moves the run into waiting_for_answer and pauses execution until an answer is submitted.

shell
# 1) Inspect the blocked runorca status --run <run-id># 2) Submit the answerorca answer <run-id> "yes, use migration A"# 3) Continue executionorca resume --run <run-id>

See Types ↓ for full hook event and context contracts.

ts
# Via config (function hooks + command hooks)import { defineOrcaConfig } from "orcastrator";import type { HookEventMap, HookHandlerContext } from "orcastrator/types";export default defineOrcaConfig({  hooks: {    onTaskComplete: async (event, context) => {      const _typedEvent: HookEventMap["onTaskComplete"] = event;      const _typedContext: HookHandlerContext = context;      console.log(`task done: ${event.taskName}`, context.cwd);    },  },  hookCommands: {    onTaskComplete: "node ./scripts/on-task-complete.mjs",  },});# ./scripts/on-task-complete.mjs# let s = ""; process.stdin.on("data", d => s += d);# process.stdin.on("end", () => {#   const payload = JSON.parse(s);#   console.log(`done: ${payload.taskName}`);# });

Multi-agent Mode

Codex supports experimental multi-agent workflows where it can spawn parallel sub-agents for complex tasks. Off by default because enabling it modifies your global ~/.codex/config.toml.

⚠️ Enabling multi-agent mode writes multi_agent = true to your global Codex config. If you already have it enabled there, orca picks it up automatically.
js
// orca.config.jsexport default {  codex: { multiAgent: true }};

Run ID format

Run IDs are generated as <slug>-<unix-ms>-<hex4>:

feature-auth-1766228123456-1a2b

Agent Skill

Drop this SKILL.md into your agent's skills directory to give it native Orca support.

Agent SkillSKILL.md
---
name: orca
description: "Orchestrate multi-step AI coding tasks via the Orca CLI. Use when: running multi-file code changes, spawning background agents, planning and executing complex tasks end-to-end. NOT for: simple single-file edits, reading code."
---

# Orca

Orca (orcastrator) is a CLI that breaks a task into a graph of tasks and executes it end-to-end via Codex.

## Install
npm install -g orcastrator

## Run a Task
orca "your task here"

## Key Commands
orca <task>              Start a new run
orca status [--last]     Check run status
orca answer <text>       Answer a question the agent raised
orca resume [--last]     Resume a paused run
orca cancel [--last]     Cancel a run
orca pr create [--last]  Open a PR for the run's branch

## Config (~/.orca/config.js or ./orca.config.js)
export default {
  executor: "codex",           // "codex" (default)
  sessionLogs: "./session-logs",
  hooks: {
    onComplete: async (event, context) => {
      console.log(event.message, context.cwd);
    },
  },
  hookCommands: {
    onComplete: "node ./scripts/on-complete.mjs",
  },
  codex: { multiAgent: false },
}

## Notes
- Codex executor requires ~/.codex/auth.json
- Must be run inside a git repo
- Run ID format: <slug>-<unix-ms>-<hex4>
- Use orca answer to unblock a waiting run

Types

Full TypeScript contracts for hook events and context. Import directly from orcastrator/types ↗.

HookHandlerContext

Passed as the second argument to every function hook.

ts
type HookHandlerContext = {  cwd: string;       // working directory of the orca run  pid: number;       // process id  invokedAt: string; // ISO timestamp of invocation};

BaseHookEvent

Base shape shared by all hook events. Hook-specific events extend this.

ts
type BaseHookEvent = {  runId: RunId;  message: string;  timestamp: string;  taskId?: string;  taskName?: string;  error?: string;  metadata?: Record<string, string | number | boolean | null>;};

HookEventMap

Maps each hook name to its full event type.

ts
type HookEventMap = {  onMilestone:    BaseHookEvent & { hook: "onMilestone" };  onTaskComplete: BaseHookEvent & { hook: "onTaskComplete"; taskId: string; taskName: string };  onTaskFail:     BaseHookEvent & { hook: "onTaskFail"; taskId: string; taskName: string; error: string };  onInvalidPlan:  BaseHookEvent & { hook: "onInvalidPlan"; error: string };  onFindings:     BaseHookEvent & { hook: "onFindings" };  onComplete:     BaseHookEvent & { hook: "onComplete" };  onError:        BaseHookEvent & { hook: "onError"; error: string };};

Example payload (JSON)

Shape of the JSON written to stdin for command hooks.

json
{  "hook": "onTaskComplete",  "runId": "feature-auth-1766228123456-1a2b",  "message": "Task completed",  "timestamp": "2026-02-22T12:00:00.000Z",  "taskId": "task-2",  "taskName": "Apply migration"}