Documentation

1. Download Orkest

Download the latest version of Orkest from the official site:

2. Install the app

Open the downloaded .dmg file and drag Orkest into your Applications folder. On first launch, macOS may ask you to confirm opening an app from an identified developer.

3. Install Claude Code CLI

If you plan to use Claude Code as your agent, install the CLI globally:

npm install -g @anthropic-ai/claude-code

Then authenticate by running claude in your terminal and following the OAuth flow, or set your Anthropic API key.

4. Install Codex CLI (optional)

To use OpenAI Codex as an agent:

npm install -g @openai/codex

Authenticate with your OpenAI API key by running codex and completing the setup.

Claude Code

Anthropic's autonomous coding agent. Claude Code can read and write files, run terminal commands, search codebases, and handle multi-step engineering tasks.

Authentication

Orkest supports two authentication methods for Claude Code:

• Claude OAuth / CLI — Run claude in your terminal and complete the browser-based OAuth flow. Orkest detects the session automatically.
• Anthropic API Key — Set your API key via the ANTHROPIC_API_KEY environment variable or in Orkest's settings.

Codex

OpenAI's coding agent. Codex can analyze codebases, write code, and execute multi-file changes.

Authentication

Connect your OpenAI account by setting the OPENAI_API_KEY environment variable or configuring it in Orkest's settings panel.

How worktrees work

Git worktrees (git worktree) let you check out multiple branches of the same repository simultaneously, each in its own directory. Orkest automates this:

1. 1When you create a new worktree, Orkest runs git worktree add with a new branch
2. 2The agent is launched inside the worktree directory with full access to the isolated copy
3. 3Changes in one worktree never affect another, or your main branch
4. 4When done, you review, merge, and clean up the worktree

Creating a worktree

Click New Worktree in the sidebar. Configure:

• Branch name — The Git branch for this worktree (e.g. feature/auth, fix/api-bug)
• Base branch — The branch to fork from (defaults to main)
• Agent — Which AI agent to use (Claude Code or Codex)

Managing worktrees

The sidebar shows all active worktrees with status indicators: green for active agents, yellow for paused, and gray for idle. Click a worktree to switch to its view. Right-click to access options like deleting the worktree or changing the agent.

Visual staging and diffs

After an agent makes changes, open the Git panel to see a list of modified files. Click any file to view a line-by-line diff. Stage individual files or all changes at once.

Commits and pushes

Write a commit message and commit staged changes directly from the app. Push to your remote in one click. Orkest also supports checkpoints — automatic intermediate commits that let you roll back if an agent goes off track.

Pull request creation

Create pull requests directly from Orkest. The app pushes the branch and opens a PR on your Git remote (GitHub, GitLab, or any standard Git host). No browser switching required.

Supported remotes

Orkest works with any Git remote that supports standard Git protocols:

• GitHub (github.com and GitHub Enterprise)
• GitLab (gitlab.com and self-hosted)
• Bitbucket
• Any remote supporting SSH or HTTPS Git protocols

Auto-detected files

The Context Engine reads the following files from your project root:

Writing a CLAUDE.md

The CLAUDE.md file is the most important context file. It tells agents how to work with your specific project. A good CLAUDE.md includes:

• Project overview and architecture
• Build, test, and lint commands
• Coding conventions and patterns to follow
• Key files and their purposes
• Things agents should avoid or be careful about

# CLAUDE.md

## Project
E-commerce API built with Express + TypeScript + Prisma.

## Commands
```bash
npm run dev     # Start dev server
npm test        # Run Jest test suite
npm run lint    # ESLint check
```

## Architecture
- src/routes/    — Express route handlers
- src/services/  — Business logic
- src/models/    — Prisma schema and types
- src/middleware/ — Auth, validation, error handling

## Conventions
- All routes return { data, error } shape
- Use Prisma transactions for multi-table writes
- Tests go in __tests__/ next to the source file

Per-worktree context

Context is injected per worktree. If your worktree is on a branch that has a modifiedCLAUDE.md, the agent will use that version. This is useful for feature branches that need specific instructions.

Features

• Per-worktree isolation — Each terminal session is scoped to its worktree directory
• Multi-session support — Open multiple terminal tabs in the same worktree
• Full xterm.js — Colors, cursor movement, scrollback buffer, copy/paste
• Shell integration — Uses your default shell (bash, zsh, fish)

What's tracked