Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,6 @@
/code/
/code2/
/dist/

# planning artifacts
implementation_plan.md
136 changes: 136 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
# AGENTS.md

## What this repo is

Go CLI (`cmd/orchestra`) that orchestrates multiple AI coding agents (Claude Code, OpenCode, Mimo, etc.) through a single supervised interface. Agents run headless; human approves via diff review.

## Build & verify (run these in order before pushing)

```sh
go build ./... # compile
go vet ./... # static analysis
go test ./... # all tests
gofmt -w . # format (CI enforces this)
```

No shortcuts. CI runs exactly these four steps against Go 1.22.

## Single-focus commands

```sh
go test ./internal/scheduler/... # test one package
go vet ./internal/engine/... # vet one package
gofmt -l . # list unformatted files
```

## Build the binary

```sh
go build -o bin/orchestra ./cmd/orchestra
./bin/orchestra --help
```

Binary is at `bin/orchestra` (gitignored).

## Project structure

- `cmd/orchestra/` — Cobra CLI (main.go + one file per subcommand: run, do, plan, dashboard, agents, etc.)
- `internal/engine/` — the core supervised loop (dispatch → validate → retry → review). Every front door (`run`, shell, `do`) drives this.
- `internal/agent/` — Agent interface + registry. This is the extension point for adding new agents.
- `internal/router/` — AI routing: classifies intent → picks agent. Uses a CLI agent now; API planned.
- `internal/planner/` — decomposes requests into ordered steps with `depends_on` for parallelism.
- `internal/scheduler/` — bounded-concurrency DAG runner for parallel worktrees.
- `internal/worktree/` — git worktree isolation (branch per task, merge + conflict detection).
- `internal/validate/` — build → lint → test pipeline, auto-detects toolchain, stops on first failure.
- `internal/config/` — YAML config + built-in agent defaults + toolchain auto-detection.
- `internal/memory/` — SQLite history at `~/.orchestra/orchestra.db` (never in the repo tree).
- `internal/tui/` — Bubble Tea dashboard (agents, history, benchmarks, chat tabs).
- `internal/ui/` — terminal styling (gradients, spinners, diffs). TTY-aware.
- `internal/shell/` — interactive chat REPL.
- `internal/review/` — diff display + accept/reject prompt.
- `internal/runner/` — generic process exec (stream/capture/timeout). The engine's engine.
- `internal/gitutil/` — git helpers (is-repo, is-clean, diff, restore, commit).
- `internal/fsdiff/` — git-free supervision for plain folders: directory snapshots, a Myers line-diff emitting git-style unified output, and snapshot restore. Used by the engine whenever `--dir` is not a git repository.
- `internal/llm/` — HTTP LLM providers (`Provider` interface; openai-compatible + anthropic). No new deps: stdlib net/http.
- `internal/patch/` — extracts unified diffs / whole-file blocks from model output and applies them (git apply --check dry-run first; traversal-guarded writes).

## Key conventions

- **CGO_ENABLED=0** — pure-Go builds (uses `modernc.org/sqlite`, not CGo). Do not introduce C dependencies.
- **Tests use fake agents** — small shell scripts, not real CLIs. Tests are headless, offline, deterministic. Follow this pattern.
- **Test files are colocated** (`*_test.go` next to source). Pure logic (scheduler, config detection, TUI update/view) is tested without a TTY.
- **CI checks**: build, vet, test, gofmt. All four must pass. Run them locally before pushing.
- **Releases**: push a `v*` tag → GoReleaser cross-compiles → GitHub Release. Version stamped via `-ldflags -X main.version=<tag>`.
- **Config file**: `orchestra.yaml` (optional, generated by `orchestra init`). Built-in defaults work without one.
- **`dir_flag` in agent config**: some CLIs (e.g. opencode) don't honor process cwd. Set `dir_flag: "--dir"` so parallel worktrees stay isolated.

## Supervised loop (the core abstraction)

Every front door (`run`, `do`, shell) drives the same pipeline in `internal/engine/`:

```
dispatch → validate → retry (self-correct) → review (accept/reject)
```

Git is optional. Inside a repository, diffs and rejects use git and the tree must start clean
(reject does `git restore`). Outside one — like opencode or claude — the engine snapshots the
directory first (`internal/fsdiff`), diffs against that snapshot, and restores from it on reject;
accept just keeps the files. `--parallel` and `benchmark` still require a repository (worktrees).

If you change validation or retry logic, you change all three entry points. The engine is the product — not the CLI or the TUI.

## Agent interface contract

`internal/agent/agent.go` defines the extension point. Implement the `Agent` interface:

```go
type Agent interface {
Name() string
Run(ctx context.Context, task Task) (Result, error)
Health() error
Capabilities() []Capability
}
```

Optional interfaces that agents may also implement: `Querier` (text output for planning), `Prober` (live health check), `QuietRunner` / `QuietQuerier` (no-stream variants for the TUI). Callers type-assert and fall back gracefully.

Register new agents in `internal/agent/registry.go` — the `Registry.Add()` method preserves insertion order for stable listings.

There are two concrete implementations: `CLIAgent` (spawns a CLI in headless auto-approve mode) and `APIAgent` (`internal/agent/apiagent.go`, calls an HTTP LLM via `internal/llm`, applies its patch via `internal/patch`). API agents are configured with `type: api` in orchestra.yaml — see docs/EXTENDING.md. A future agent kind can implement the interface without touching the scheduler, router, or shell.

## Testing with fake agents

Tests never call real agent CLIs. Instead, use small shell scripts or builtins as stubs:

```go
// "true" is a valid fake agent — exits 0, does nothing.
reg.Add(agent.New("alpha", "true", nil, "", []agent.Capability{agent.CapImplement}))
```

For scheduler tests, pure logic (DAG validation, concurrency caps) is tested without any agent at all. See `internal/scheduler/scheduler_test.go` for examples.

For config detection tests, temp dirs with marker files (`go.mod`, `package.json`) are used — no real toolchain needed beyond what's on PATH (tests skip gracefully via `t.Skip`).

## TUI stack

The dashboard (`internal/tui/`) uses Charm's ecosystem:
- **Bubble Tea** — Elm-architecture TUI framework
- **Lipgloss** — terminal styling
- **Glamour** — markdown rendering
- **Chroma** — syntax-highlighted diffs

These are not interchangeable with other TUI frameworks. Tests are headless (`tui_test.go` renders views without a TTY by injecting `WindowSizeMsg`).

## Router is CLI-based

The AI router (`internal/router/`) classifies intent by dispatching to an agent in query mode (e.g. `claude -p`), not by calling an LLM API itself. It inherits agent CLI quirks: needs `--dangerously-skip-permissions`, uses the same `runner` package, and the classification latency is whatever the agent takes. Since `APIAgent` also implements `Querier`, an api-type agent can serve as the router's classifier today; a dedicated direct-API classifier inside `internal/router` remains planned but unimplemented.

## Gitignored directories

`code/` and `code2/` are local dogfooding test projects. They are gitignored — do not create or modify files there as part of your changes.

## Before pushing

Always run: `go build ./... && go vet ./... && go test ./... && gofmt -w .`

Branch off `main`. Keep changes focused; add/adjust tests. Describe the change and how you verified it in the PR.
18 changes: 18 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

The canonical agent instructions live in AGENTS.md (shared with other coding agents). It covers the
build/verify commands, package layout, the supervised loop, the Agent interface, and testing conventions:

@AGENTS.md

## Additions for Claude Code

- Module path is `github.com/crossben/orchestra-code`; CI pins Go 1.22. If `go` tries to download a
newer toolchain and fails offline, run `go env -w GOTOOLCHAIN=local` once.
- Run a single test: `go test ./internal/engine/ -run TestName -v`.
- CI also runs `goreleaser check` against `.goreleaser.yaml`, so keep that file valid if you touch it.
See docs/RELEASING.md for the release flow and docs/EXTENDING.md for adding agents (CLI or `type: api`).
- Orchestra is supervised-first: nothing an agent produces is kept without an explicit accept at diff review.
If a change alters agent behavior or the supervised loop, call that out explicitly in the PR.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ gofmt -w . # format (CI enforces this)

```
cmd/orchestra CLI (cobra): run / do / plan / benchmark / dashboard / agents / init / shell
internal/agent Agent interface + CLIAgent + registry ← the extension point
internal/agent Agent interface + CLIAgent/APIAgent + registry ← the extension point
internal/engine supervised pipeline: dispatch → validate → retry → review
internal/router AI routing (classify → decide)
internal/planner request → ordered steps (+ dependencies)
Expand Down
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -260,8 +260,11 @@ A config file overrides defaults and adds agents; matching names replace the bui

```
cmd/orchestra Cobra CLI: run / plan / do / history / agents / init / shell (default)
internal/agent Agent interface + CLIAgent + registry + Querier
internal/agent Agent interface + CLIAgent/APIAgent + registry + Querier
internal/config YAML config + built-in agent defaults + validator auto-detection
internal/fsdiff git-free supervision: dir snapshots + unified diff + restore
internal/llm HTTP LLM providers (openai-compatible, anthropic) behind one interface
internal/patch extract changes from model replies and apply them safely
internal/ui terminal styling: gradient banner, spinners, colored diffs (TTY-aware)
internal/tui Bubble Tea dashboard: agents / history / benchmarks (read-only monitor)
internal/router AI routing: Classifier (CLI now, API later) → Decision, 3-tier fallback
Expand Down
11 changes: 10 additions & 1 deletion cmd/orchestra/agents.go
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ func newAgentsCmd() *cobra.Command {
if a.Name() == cfg.DefaultAgent {
def = " (default)"
}
fmt.Printf("%-12s %-16s %s%s\n", a.Name(), status, capList(a), def)
fmt.Printf("%-12s %-16s %s%s%s\n", a.Name(), status, capList(a), apiTag(a), def)
}
fmt.Println(ui.Dim("\ntip: `orchestra agents --probe` checks agents can actually run, not just that they're installed"))
return nil
Expand Down Expand Up @@ -105,3 +105,12 @@ func capList(a agent.Agent) string {
}
return strings.Join(caps, ",")
}

// apiTag labels HTTP-backed agents so `orchestra agents` shows what they are
// at a glance (e.g. " (api: openai/gpt-4o)"). Empty for CLI agents.
func apiTag(a agent.Agent) string {
if api, ok := a.(*agent.APIAgent); ok {
return ui.Dim(fmt.Sprintf(" (api: %s/%s)", api.ProviderName(), api.Model()))
}
return ""
}
2 changes: 1 addition & 1 deletion cmd/orchestra/benchmark.go
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ func newBenchmarkCmd() *cobra.Command {
return err
}
if !gitutil.IsRepo(flagDir) {
return errNotRepo(flagDir)
return fmt.Errorf("benchmark needs a git repository — every agent runs in an isolated worktree so their changes never collide")
}
if clean, err := gitutil.IsClean(flagDir); err != nil {
return err
Expand Down
18 changes: 11 additions & 7 deletions cmd/orchestra/do.go
Original file line number Diff line number Diff line change
Expand Up @@ -56,14 +56,18 @@ func newDoCmd() *cobra.Command {
agentName = cfg.DefaultAgent
}

// Git pre-flight — the workflow commits/merges; start clean.
if !gitutil.IsRepo(flagDir) {
return errNotRepo(flagDir)
// Git pre-flight: sequential mode works anywhere (snapshot-tracked),
// but --parallel isolates steps in git worktrees, so it needs a repo.
inRepo := gitutil.IsRepo(flagDir)
if parallel && !inRepo {
return fmt.Errorf("--parallel needs a git repository (each step runs in an isolated worktree); run inside a repo, or drop --parallel for step-by-step supervision")
}
if clean, err := gitutil.IsClean(flagDir); err != nil {
return err
} else if !clean {
return errDirty()
if inRepo {
if clean, err := gitutil.IsClean(flagDir); err != nil {
return err
} else if !clean {
return errDirty()
}
}

reg := cfg.BuildRegistry()
Expand Down
4 changes: 0 additions & 4 deletions cmd/orchestra/errors.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,6 @@ package main

import "fmt"

func errNotRepo(dir string) error {
return fmt.Errorf("%s is not a git repository (run `git init` first)", dir)
}

func errDirty() error {
return fmt.Errorf("working tree has uncommitted changes; the supervised loop " +
"reverts on reject and would discard them — commit/stash first, or pass --force")
Expand Down
10 changes: 10 additions & 0 deletions cmd/orchestra/init.go
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,16 @@ agents:
bin: mimo
args: ["run", "--dangerously-skip-permissions"]
capabilities: [implement, review]

# API-backed agent (no CLI needed): Orchestra sends the model a snapshot of
# the repo and applies the returned patch itself. Uncomment and set the key:
#
# - name: gpt
# type: api
# provider: openai # openai | anthropic (OpenRouter/Groq/Ollama work via openai + api_base)
# model: gpt-4o
# api_key_env: OPENAI_API_KEY
# capabilities: [plan, implement, review]
`

func newInitCmd() *cobra.Command {
Expand Down
27 changes: 17 additions & 10 deletions cmd/orchestra/root.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,14 @@ import (
"github.com/crossben/orchestra-code/internal/gitutil"
"github.com/crossben/orchestra-code/internal/router"
"github.com/crossben/orchestra-code/internal/shell"
"github.com/crossben/orchestra-code/internal/ui"
"github.com/spf13/cobra"
)

// version is the build version. It defaults to the last released tag for
// `go install`, and is overridden at release time via
// -ldflags "-X main.version=<tag>" (see .goreleaser.yaml).
var version = "0.7.3"
var version = "0.8.0"

// persistent flags shared across subcommands.
var (
Expand Down Expand Up @@ -53,15 +54,21 @@ func runShell(cmd *cobra.Command) error {
if err != nil {
return err
}
if !gitutil.IsRepo(flagDir) {
return errNotRepo(flagDir)
}
clean, err := gitutil.IsClean(flagDir)
if err != nil {
return err
}
if !clean {
return errDirty()

// Git is optional: inside a repository the supervised loop uses git for
// diffs/rejects (and wants a clean start); anywhere else it snapshots the
// directory instead, so plain folders work like opencode or claude.
inRepo := gitutil.IsRepo(flagDir)
if inRepo {
clean, err := gitutil.IsClean(flagDir)
if err != nil {
return err
}
if !clean {
return errDirty()
}
} else {
fmt.Printf("%s\n", ui.Dim(fmt.Sprintf("▸ %s is not a git repository — Orchestra will track changes by snapshot (accept keeps files, reject restores)", flagDir)))
}

mem, err := openMemory()
Expand Down
21 changes: 11 additions & 10 deletions cmd/orchestra/run.go
Original file line number Diff line number Diff line change
Expand Up @@ -60,16 +60,17 @@ func newRunCmd() *cobra.Command {
cfg.Principles = principles
}

// Git pre-flight: the supervised loop reverts on reject.
if !gitutil.IsRepo(flagDir) {
return errNotRepo(flagDir)
}
clean, err := gitutil.IsClean(flagDir)
if err != nil {
return err
}
if !clean && !force {
return errDirty()
// Git pre-flight: inside a repository the supervised loop reverts
// on reject, so it wants a clean start (unless --force). Plain
// directories are fine — changes are snapshot-tracked instead.
if gitutil.IsRepo(flagDir) {
clean, err := gitutil.IsClean(flagDir)
if err != nil {
return err
}
if !clean && !force {
return errDirty()
}
}

reg := cfg.BuildRegistry()
Expand Down
38 changes: 36 additions & 2 deletions docs/EXTENDING.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Extending Orchestra — adding agents

Orchestra treats every agent as an interchangeable component behind one interface. There are two
Orchestra treats every agent as an interchangeable component behind one interface. There are three
ways to add one, from easiest to deepest.

---
Expand Down Expand Up @@ -60,7 +60,41 @@ You'll see the full supervised loop against your custom agent.

---

## 2. Implement the `Agent` interface (for a built-in / non-CLI agent)
## 2. Add an API-backed agent via config (no code)

If you'd rather call a hosted LLM directly than spawn a CLI, register an agent with
`type: api`. Orchestra sends the model a bounded snapshot of your repository plus the task,
the model replies with changes (a unified diff or whole-file blocks), Orchestra applies them
to the working tree, and everything flows through the same supervised loop:
validate → retry → diff review.

```yaml
agents:
- name: gpt
type: api
provider: openai # openai | anthropic
model: gpt-4o # required
# api_base: https://api.openai.com/v1 # optional override (OpenRouter, Groq,
# # Ollama, vLLM… all speak the openai format)
api_key_env: OPENAI_API_KEY # env var holding the key (provider default)
context_budget: 98304 # repo snapshot byte cap (default 96 KiB)
capabilities: [plan, implement, review]
```

Notes:
- The API key is read from the environment at run time — never put keys in the YAML.
- `orchestra agents` shows these as `(api: <provider>/<model>)`, and `--probe` runs a real
tiny completion so auth/billing problems surface with actionable detail.
- Because the model cannot explore the repo itself, the snapshot it receives matters: keep
the tree lean, and raise `context_budget` if tasks touch many files.
- Self-correction works like any agent: on validation failure the failure text is fed back
and the model re-edits its own prior changes in place.
- Works everywhere CLI agents do: `run`, shell, dashboard chat, planning, routing, and even
`do --parallel` worktrees (patches apply inside each isolated worktree).

---

## 3. Implement the `Agent` interface (for a built-in / non-CLI agent)

For agents that aren't a subprocess (e.g. a direct API/gRPC client), implement the interface in
[`internal/agent/agent.go`](../internal/agent/agent.go):
Expand Down
Loading
Loading