OPEN-SOURCE AGENT ORCHESTRATION

Run a fleet of agents.
Ship one result.

Kahn turns a task graph into parallel Claude Code sessions, runs them in dependency order, and verifies each step with shell exit codes — not vibes. When two agents touch the same file, the scheduler resolves it automatically. 

$ curl kahn.run | sh
GitHub Architecture
Prompt-DAG topology with topological execution wave A directed acyclic graph of 7 nodes arranged in a trellis, animating with a wave that respects topological order. One node highlights in amber as the active execution point; at one moment, two sibling nodes contend for execution and one defers to the next scheduler tick. 
[agent-a] ✓ added tests for auth.rs
[agent-b] ✓ refactored auth.rs
[agent-a] ✓ tests passing
[agent-b] ✓ tests passing
$ git status
  both modified:   src/auth.rs
[merge] conflict — resolution required
[agent-a] self-report: DONE
[agent-b] self-report: DONE
[reality] : neither done. neither aware.

/01 Agent fleets fail because
they cannot see each other.

Two agents editing the same file is not a merge problem. It's an observability problem. You cannot parallelise work you cannot see. Ask an agent whether it is done and it will tell you yes. Every time. KAHN's wedge is the refusal to trust that answer.

/02 The mechanism.
Three invariants.

STEP 1 — SCAN

Walk a directory recursively. Trace every prompt block and agent invocation. Build a dependency graph from depends_on annotations. Reject cycles. Produce a dag.json to .kahn/state/.

→ invariant I-1: Scope never writes to state

SCAN: Directory to DAG transformation src/ auth.rs main.rs api.rs scan A B C D

STEP 2 — SCHEDULE

Walk the DAG in topological order. Each node has a touches set (files it reads/writes). If two nodes in the same tick have overlapping touches, defer one to the next tick. Topological order enforced; cycles rejected.

→ invariant I-2: Schedule respects order

SCHEDULE: Topological ordering with conflict detection tick-0 tick-1 A auth.rs B util.rs C auth.rs conflict — auth.rs

STEP 3 — VERIFY

Execute each node. Evaluate its done_when condition (shell expression, usually exit 0). If it passes, mark done. If it fails, Ralph (the retry loop) retries with exponential backoff. If done_when never satisfies, fail.

→ invariant I-3: Verify by exit code

VERIFY: Execution with retry loop (Ralph) execute done? ✓ done ✗ Ralph — exponential backoff

/03 Scope — the read-only projection.

Everything you see is derived from .kahn/state/. Scope cannot write to state. It cannot lie about state. It is a window, not an operator.

git clone https://github.com/kahn-hq/kahn.git
cd kahn
docker compose up
open http://localhost:7070

/04 Self-host in
90 seconds.

The orchestrator, Scope, and a demo DAG. Apache-2.0. No telemetry. No phone-home. Your agents. Your filesystem. Your rules.

MIT-compatible no-telemetry airgap-ok

/05 Build log.

Wk 00 problem statement
Wk 01 dag scanner v0
Wk 02 touches-conflict scheduler
Wk 03 Ralph retry-loop
Wk 04 Scope v0
Wk 05 v0.1 public release ← YOU ARE HERE
Wk 06 dashboard polish
Wk 07 taxonomy
Wk 08 real-deploy + economics

subscribe to the log →
github.com/kahn-hq/kahn
@kahn_hq on x
kahn.tools on bluesky