Quickstart

This walkthrough takes you from zero to a first dry-run wave in about ten minutes. You will register a project, pass the pre-dispatch gate, fire a single wave in dry-run mode, and read the board and slot status.

Prerequisites

• koryph binary on your PATH (koryph version should print a version)
• A git repository you want to manage (we call it ~/src/myproject below)
• bd (beads) initialised in that repo (bd stats should succeed)
• A Claude account profile name and the email address tied to it

Step 1 — Register the project

koryph project add ~/src/myproject \
  --account personal \
  --identity you@example.com

project add inspects the repo, writes a registry record, scaffolds the koryph adapter if one is missing, and installs the koryph scaffolding. Exactly what it installs depends on the project's configured runtime (koryph-v8u.9):

AGENTS.md is the runtime-neutral instruction file read natively by Codex, Cursor, Grok, Copilot, opencode, and amp — it documents the koryph operating contract so every runtime follows the same rules. Runtimes without hook support rely on worktree isolation and merge-time protected-path refusal for containment instead of in-editor lifecycle guards.

The rules are what make koryph's boundaries hold in-editor (Claude Code only): the agent-boundary-guard and worktree-guard hooks and the bd prime session-start hook, plus a baseline permission allow/deny list. Unlike the whole-file agents and commands, .claude/settings.json is merged additively — koryph's hooks and permissions are added and your own settings are never clobbered (re-run koryph rules install <root> any time; it is idempotent).

Both the agents and the commands are namespaced with the koryph- prefix (koryph-implementer, koryph-issue, …) so they never collide with a project's own — or another tool's — .claude entries. A project overrides any stage's persona by name via the stages/tiers maps in koryph.project.json.

Installing is idempotent and never clobbers your edits: a file that already exists with identical content is a silent no-op, and one whose content differs is left untouched with a warning. To refresh or repair the assets later, the canonical grouped verb installs all four at once:

koryph project install-assets <root> [agentsmd|agents|commands|rules|all]  # default: all

Pass a single kind to narrow it, --force to overwrite differing files, or --all-projects to refresh every registered project. The per-kind verbs (koryph agents install <root> --force, koryph commands install <root> --force, koryph rules install <root> --force) remain as working aliases. The point of shipping these commands is that koryph semantics are enforced whether you run koryph yourself or an in-editor prompt drives it for you.

The koryph-* slash commands (grouped under the koryph- prefix in the editor's command list):

Confirm the project was registered:

koryph project list

You should see one row with STATUS of registered.

Step 2 — Run the pre-dispatch gate

koryph validate myproject

validate checks that the repo has the required koryph hooks, a valid adapter, beads initialised, and a matching account identity. On the first green pass it promotes the record from registered → migrated and prints:

promoted migration_status: registered -> migrated
OK

Fix any reported issues and re-run until you see OK. A FAILED exit means at least one check did not pass — the output names the failing check.

Step 3 — Fire a first dry-run wave

koryph run --project myproject --once --dry-run

--once limits the engine to a single wave so you see exactly what would be dispatched without committing to a full run. --dry-run plans and prints the wave without launching any agent processes.

The output lists each bead the engine would dispatch, the model it would use, and the worktree branch it would create.

Other useful flags for early exploration:

Step 4 — Read the board

koryph board

board prints one row per registered project:

PROJECT     MIGRATION   ACCOUNT    RUN          RUN-STATUS  SLOTS  LIVE
myproject   migrated    personal   run-abc123   dry-run     -      0

Columns: project slug, migration status, account profile, latest run ID, run status, slot status counts (e.g. merged:2 running:1), and live PID count. Add --json for the machine-readable payload.

Step 5 — Read slot status

koryph status --project myproject

status shows per-slot detail for the latest run:

project myproject  run run-abc123  status dry-run  wave 1

PHASE        STATUS   MODEL     COST   ATTEMPTS  BRANCH  WORKTREE
beads-a1b    planned  sonnet    $0.00  0         -       -

Add --json to get the full ledger entry for scripting or post-processing.

What's next

• If your project's work lives in markdown (design docs, ROADMAP.md, TODO.md, inline TODO/FIXME clusters): run /koryph-import in the editor to convert that corpus into a filed bead graph before starting waves. This creates conflict-aware, footprint-labelled beads the loop can dispatch in parallel — without it, bd ready is empty and the loop has nothing to build.
• Remove --dry-run to fire a live wave: koryph run --project myproject --once
• After a successful wave, re-run koryph validate myproject — once a run has at least one merged slot and no failures, the record is promoted to validated.
• Read Running waves for multi-wave runs, --resume, --review, and auto-merge.
• Read Billing and quota before enabling --allow-api-spend.