CARAVAN

GitHub-native merge movement

Keep the whole
convoy moving.

Caravan is a deterministic merge queue for people and agents. It turns pull-request topology into a safe, visible chain—without inventing another database.

Get on the road Read the specification
Source of truth
GitHub
Queue state
PR topology
Agent surface
CLI · JSON · MCP

HEAD IS CLEAR → ROLL

One chain. Exact evidence.
No mystery state.

01 / The topology is the queue

Nothing hiding
behind GitHub.

A caravan is simply a linear chain of open pull requests. Every member carries the caravan label; each PR targets the branch ahead of it. The head alone targets the default branch and holds squash auto-merge.

02 / The operating loop

Mechanical work rolls.
Judgment stops.

Every tick rediscovers GitHub state. Caravan advances what it can prove, then returns a typed, resumable decision whenever semantics need a person or agent.

  1. 01

    Discover

    Read branches, labels, checks, bases, and exact revisions fresh from GitHub.

  2. 02

    Prove

    Validate graph shape, mechanical compatibility, CI, and cross-convoy safety.

  3. 03

    Move

    Keep auto-merge on the head, advance merged chains, and preserve ordering.

  4. 04

    Hand off judgment

    Conflict or failed CI? Return exact evidence and safe next commands—never guess.

$cara loop --once --json

03 / Evidence over optimism

Safe by construction.
Legible by default.

⌁

Mechanical compatibility

Non-mutating merge proofs use exact head and base revisions. No history rewrite just to test a theory.

{ }

Typed decisions

Human output stays concise while JSON and MCP receive stable errors, evidence, and resumable commands.

↻

Idempotent recovery

Interrupted operations resume from rediscovered GitHub state—not a fragile local cursor.

◎

Canonical events

A bounded, secret-free journal records transitions and hook receipts in shared Git metadata.

⇄

Three equal surfaces

The human CLI, stable JSON envelopes, and MCP tools all route through one typed library path.

◇

Force is still proof

Known CI failures may be accepted, but conflicts, stale revisions, and permissions are never bypassed.

04 / Command map

From first PR
to open road.

STARTcara check

Prove the current PR can travel.

JOINcara new

Lead a convoy—or cara join a tail.

ROLLcara sync

Advance safe work and expose decisions.

OBSERVEcara status

See the entire fleet and its evidence.

Built for agent traffic

Caravan ×
Cacophony

Caravan owns bounded GitHub queue mechanics. Cacophony listens to typed hooks, sends the right specialist to a decision point, and schedules another sync. Authority stays crisp: Caravan never pretends to be the agent runtime.

Explore Cacophony 
hooks:
  sync_failed:
    command: ./scripts/dispatch-agent
    timeout_secs: 30
    blocking: false

# exact evidence enters on stdin
# the next tick starts fresh

05 / Join the convoy

Ready to roll?

Build from source today. Release archives include checksums and support bounded self-update on Linux and Apple silicon.

git clone https://github.com/harryaskham/caravan.git
cd caravan && nix develop
cargo build --release