NAME

kahn — prompt-DAG scheduler for ClaudeCode agent fleets

SYNOPSIS

kahn scan [<dir>]
kahn run [--from <node>] [--max-parallel <n>] [--dry-run]
kahn status [--run <id>] [--watch]
kahn scope [--port <n>]
kahn archive [--run <id>] [--gzip]

INSTALL

$ curl kahn.run | sh
⊳ piping curl to sh makes me nervous

Verify first:

curl https://kahn.run/install.sh > /tmp/kahn-install.sh
less /tmp/kahn-install.sh
sh /tmp/kahn-install.sh

Or download a pinned release:

gh release download v0.1.0 --repo kahn-hq/kahn

QUICKSTART

From zero to first DAG run in under 60 seconds.

  1. curl kahn.run | sh
  2. cd your-repo
  3. kahn scan . → writes .kahn/state/dag.json
  4. kahn run → begins topological execution
  5. kahn scope → opens http://localhost:7070
  6. (optional)
  7. kahn archive --run last --gzip → .kahn/archive/runs/<id>.tar.gz

COMMANDS

kahn scan

Walk a directory, produce a prompt-DAG, write it to .kahn/state/dag.json. Rejects cycles. Rejects multiply-rooted graphs unless --multi-root is given.

OPTIONS

--multi-root
allow multiple root nodes
--exclude <glob>
skip paths matching glob
--out <path>
write DAG to custom path

EXIT

0
DAG produced
2
cycle detected
3
unreadable input
4
empty DAG

kahn run

Execute a DAG in topological order. Each node's done_when is evaluated. If it fails, Ralph (the retry loop) retries with exponential backoff. If done_when never satisfies within the node budget, fail and continue to dependents.

OPTIONS

--from <node>
start execution from this node (skip earlier layers)
--max-parallel <n>
limit concurrent worker threads (default: 4)
--dry-run
print execution plan, do not execute

EXIT

0
DAG converged
1
generic failure
5
touches-conflict unresolvable within max iterations
6
worker crashed non-recoverably
7
done_when never satisfied within node budget

kahn status

Query the status of a completed or running DAG execution. With --watch, poll for updates every 100ms until convergence.

OPTIONS

--run <id>
query specific run (default: last)
--watch
poll for updates until convergence

EXIT

0
run found, exit code reflects run status
1
run not found or corrupted

kahn scope

Start the read-only observability dashboard. Serves on localhost:7070 by default. Scope reads .kahn/state/ and streams live updates to connected clients. Cannot write to state.

OPTIONS

--port <n>
listen on port (default: 7070)

EXIT

0
dashboard exited cleanly
1
port in use or permission denied

kahn archive

Export a completed run to `.kahn/archive/runs/<id>/`. Archives are append-only: Scope writes logs, DAG, and metadata here as runs complete.

OPTIONS

--run <id>
archive specific run (default: last)
--gzip
compress archive to .tar.gz

EXIT

0
archive created
1
run not found or write failed

CONFIGURATION

.kahn/state/

Owned by orchestrator — do not hand-edit. Invariant I-1 enforced: Scope never writes outside .kahn/archive/.

.kahn/state/
    dag.json              # current DAG
    runstate.json         # live node statuses
    locks/                # per-node atomic lock files

.kahn/archive/

Owned by Scope — read-only at runtime. Append-only writes of completed runs.

.kahn/archive/
    runs/<id>/            # one dir per completed run
        log.jsonl         # transition events
        dag.json          # DAG snapshot at run time
        summary.json      # final state summary

ENVIRONMENT

KAHN_HOME
default: ./.kahn
KAHN_SCOPE_PORT
default: 7070
KAHN_LOG_LEVEL
default: info (debug|info|warn|error)

EXIT CODES

0 success, DAG converged
1 generic failure
2 scan error: cycle in graph
3 scan error: unreadable input
4 scan error: empty DAG
5 run error: touches-conflict unresolvable within max iterations
6 run error: worker crashed non-recoverably
7 run error: done_when never satisfied within node budget
126 permission denied
127 command not found
130 interrupted (SIGINT)

FILES

~/.config/kahn/config.toml
user configuration (model, api key, defaults)
./.kahn/
per-project state and archive

VERSIONS

version date notes
0.0.1-dev TBD internal, pre-public
0.1.0 [pending] first public release

SEE ALSO

kahn.tools
product site, architecture writeups, blog
kahn-hq/kahn
source, issues, licence (Apache-2.0)
ralph(1)
the retry loop, documented separately
claude-code(1)
the agent this schedules

COLOPHON

Written and maintained by Devarno out of London. Typeset in fraunces + source serif 4. kahn(1) is part of the KAHN project; see https://kahn.tools for architecture and build log. Null routes go here. exit 0.