groq/orchestrate

groq/orchestrate

Description: Orchestrate

Language: Rust

License: MIT

Stars: 8

Forks: 0

Open issues: 2

Created: 2025-12-08T07:20:29Z

Pushed: 2026-04-14T03:38:30Z

Default branch: main

Fork: no

Archived: no

README:

---

📦 Installation

# from the repo root
cargo install --path .

Requirements: macOS with iTerm2, Rust toolchain, and your preferred AI coding agents installed.

---

⚡ Quick Start

1. Create `settings.yaml` in the Orchestrate data directory:

The settings file goes in the platform-specific data directory:

• macOS: ~/.orchestrate/settings.yaml
• Linux: ~/.local/share/orchestrate/settings.yaml
• Windows: %APPDATA%\Orchestrate\settings.yaml

default: default

presets:
# Simple: just an agent
default:
- agent: claude

# Complex: agent with dev server, tests, and shell
fullstack:
- agent: claude
commands:
- command: "./bin/go run ./cmd/server"
title: "Dev Server"
- command: "./bin/go test ./..."
title: "Tests"
- command: ""
title: "Shell"

# Multi-agent: compare different agents on the same task
compare:
- agent: droid
- agent: claude
- agent: codex

# Best of n: use n to run multiple instances of an agent
parallel:
- agent: claude
n: 3

2. Option A: Run via TUI

# Open TUI
orchestrate

3. Option B: Run via CLI:

# Use default preset
orchestrate --repo groq/openbench --name fix-bug --prompt "Create a new eval that implements a subset of SimpleQA"

# Or use the fullstack preset
orchestrate --repo groq/openbench --name fix-bug --prompt "Create a new eval that implements a subset of SimpleQA" --preset fullstack

This clones/updates the repo from the main branch, creates isolated git worktrees, and launches agents/commands in separate iTerm2 panes.

---

🔧 CLI Reference

| Flag | Description | |------|-------------| | --repo | Required. GitHub repo to clone (e.g., groq/openbench). Clones fresh or updates from main branch. | | --name | Required. Branch name prefix for worktrees. Each branch gets a unique hex suffix. | | --prompt | Required. The prompt to pass to each agent. | | --preset | Use a preset from settings.yaml. Defaults to the config's default preset. | | --n | Multiplier for agent worktrees. --n 2 runs each agent twice. |

---

📖 Use Cases

🏃 Single Agent with Dev Environment — Run your app alongside the agent + spare terminal

One agent, but with your dev server running and an extra shell for manual testing:

# settings.yaml
default: dev

presets:
dev:
- agent: codex
commands:
- command: "npm run dev"
title: "App"
color: "#00ff00"
- command: ""
title: "Terminal"

orchestrate --repo myorg/myapp --name feature-auth --prompt "Add OAuth2 login"

🔬 Evaluate Multiple Agents — Compare how droid/claude/codex solve the same problem

Give the same task to different agents and pick the best solution:

presets:
eval:
- agent: droid
- agent: claude
- agent: codex

orchestrate --repo myorg/myapp --name eval-refactor --preset eval --prompt "Refactor the database layer"
# Compare branches: eval-refactor-a3f2, eval-refactor-b7c1, eval-refactor-d9e4

🚀 Parallel Execution at Scale — Use --n multiplier for maximum throughput

Run multiple instances of each agent when you need sheer volume:

presets:
heavy:
- agent: claude
- agent: codex

orchestrate --repo myorg/myapp --name big-task --preset heavy --n 3 --prompt "Add comprehensive test coverage"
# Creates 6 worktrees: 3 claude, 3 codex

🛠️ Custom Dev Workflows — Full engineering sessions (backend, frontend, tests, shell)

Set up complete development environments with multiple services and tools:

presets:
fullstack:
- agent: claude
commands:
- command: "cd backend && cargo run"
title: "Backend API"
color: "#ff6600"
- command: "cd frontend && npm run dev"
title: "Frontend"
color: "#00ccff"
- command: ""
title: "Shell"
- agent: codex
commands:
- command: "npm run test:watch"
title: "Tests"
color: "#ffff00"

---

🤖 Supported Agents

| Agent | Description | Color | |-------|-------------|-------| | droid | Factory AI's coding agent | 🟠 Orange | | claude | Anthropic's Claude CLI | 🟤 Sand | | codex | OpenAI's Codex CLI | ⚫ Black |

Agents must be installed and available in your PATH.

🪵 Tracking shell commands in the activity log

Every agent shell defines a track helper when logging is enabled for that worktree. Use it to replace or rerun commands while keeping the activity panel up to date:

# inside the agent shell
track npm test
track ./bin/dev-server

track pipes stdout/stderr to the worktree's activity log (e.g. ~/.orchestrate/activity/.log) so the TUI activity stream stays clean even when you stop an agent and run custom commands.

---

⚙️ Configuration

Create settings.yaml in the Orchestrate data directory:

# settings.yaml
# Default preset when --preset is not specified
default: standard

presets:
# Simple: just agents
standard:
- agent: droid
- agent: codex
- agent: codex

# With commands: agents + terminals in their worktrees
dev:
- agent: codex
commands:
- command: "./bin/go run ./cmd/myapp"
title: "App"
- command: ""
title: "Terminal"

Command Options

| Option | Description | |--------|-------------| | command | Shell command to run (empty = just open terminal) | | title | Custom title for the terminal tab | | color | Hex color for the tab, e.g., #ff8800 |

> 💡 Commands run in their parent agent's worktree and show the branch name in the title.

TUI Navigation (Ratatui)

• 1/2/3/4 to jump to Worktrees / Launch / Settings / Presets
• Tab / Shift+Tab cycles views
• ? toggles the help overlay
• Worktrees: ↑/↓/g/G navigate, Enter focus existing window, o reopen, d details sidebar, x delete with confirm, Ctrl+R refresh, Ctrl+P toggle sidebar
• Launch: arrows or Tab to move, Ctrl+Enter or Launch button to start sessions, ←/→ cycle presets
• Settings: ↑/↓ select, ←/→ toggle values, Enter saves

---

🔄 How It Works

1. Clone & Update — Clones the specified GitHub repo (or updates if it already exists), always fetching the latest from main 2. Git Worktrees — Creates isolated worktrees, each with a unique branch based on main 3. iTerm2 Integration — Opens windows with up to 6 panes in a grid, color-coded by agent 4. Parallel Execution — Agents work simultaneously;…