Quickstart — Orkestra Docs

This guide gets Orkestra running in a real project. By the end, you’ll have created a Trak, watched an agent implement code in an isolated worktree, and approved the result.

Prerequisites: Rust (latest stable) with Cargo, and at least one AI coding agent CLI — either Claude Code or OpenCode — installed and authenticated. Git is required.

Install Orkestra

Clone the repository and build the binary

git clone https://github.com/tiniest-fox/orkestra.git
cd orkestra
cargo build --release

The binary is produced at target/release/ork.

Make ork available globally

Copy the binary to a directory in your PATH:
```
cp target/release/ork /usr/local/bin/ork
```
Verify the install
```
ork --version
```

Set up a project

Any Git repository can be an Orkestra project. Orkestra bootstraps itself the first time you run an ork command in a repo.

Go to your project
```
cd /path/to/your-project
```
Bootstrap the .orkestra/ directory
```
ork trak list
```
On first run, Orkestra creates .orkestra/ with a default workflow, prompt templates, and gate scripts. If no Traks exist yet, you’ll see an empty list — that’s expected.
Commit the configuration
```
git add .orkestra/
git commit -m "Add Orkestra config"
```
Orkestra appends entries to .gitignore that exclude runtime state (the database, logs, and worktrees). Only the config files go into version control.

Customize your gate script

The gate script runs automatically after each agent work stage to verify quality. The default is a placeholder — replace it with your project’s actual checks.

Open .orkestra/scripts/checks.sh and edit it:

#!/bin/bash
set -e
cd "$ORKESTRA_WORKTREE_PATH"

# Replace with your project's checks:
pnpm install --frozen-lockfile
pnpm run lint
pnpm run typecheck
pnpm test

The gate’s exit code determines what happens next. Exit zero: the work passes and moves to approval. Non-zero: Orkestra sends the agent back with the script’s output as feedback, and it retries.

Create your first Trak

Create a Trak
```
ork trak create \
  -t "Add input validation to the login form" \
  -d "The login form accepts any input without validation. Add client-side and server-side validation for email format and password length (minimum 8 characters)." \
  --flow subtask
```
Orkestra creates an isolated git branch and worktree, then starts the first stage.

Tip

The --flow subtask flag uses the work → review flow (two stages). The default flow includes planning and breakdown stages before work begins — better for larger tasks, but more steps for your first run.
Check the status

The Trak ID appears in the output when you create the Trak — it looks like only-decisive-chiffchaff. Use it to check what’s happening:
```
ork trak show <your-trak-id> --pretty
```
An AI agent is reading your description, implementing changes in its isolated worktree, and running your gate script. If the gate fails, the agent retries automatically.

Review and approve

When a stage finishes, you review the output and decide whether to advance or send the agent back.

Check ork trak show <your-trak-id> --pretty periodically. Once the stage is awaiting your input, run approve or reject.

Approve the current stage:

ork trak approve <your-trak-id>

Reject with feedback:

ork trak reject <your-trak-id> --feedback "Validation runs on blur, but it should also run on form submit. Fix the submit handler."

Rejection sends your feedback to the agent. It revises and you review again. When the final stage is approved, the Trak is complete and the branch is ready to merge.

What’s next

Core Concepts — the full model: flows, stages, gates, capabilities, and prompt templates.
Workflow Configuration — configure custom flows for different task types.
Gates — environment variables available to gate scripts and how to write effective checks.
Prompt Templates — customize how agents behave at each stage.

View on GitHub