# koryph

> Multi-project orchestrator for autonomous Claude Code agents: beads-native, account-safe, subscription-first. `koryph` runs autonomous implementation waves across many git projects — reading each project's beads ready-graph, batching conflict-free work by declared footprint, dispatching headless Claude Code agents into isolated git worktrees under the correct Claude account, checkpointing to disk, governing subscription burn, and merging finished work through a green gate.

This file is a machine-readable index for AI agents and tools ingesting the project. Links point to the canonical Markdown sources on GitHub (fetchable as raw text). The same book is published at https://koryph.build/.

## Install

Prerequisites: `git`; the Claude CLI (`claude`, from https://claude.ai/download, authenticated via `claude auth login`); the `bd` (beads) CLI (https://github.com/gastownhall/beads, confirm with `bd doctor`). `gh` (GitHub CLI) is optional but simplifies the steps below.

koryph is a single static binary — no Go toolchain or runtime required to run it. Detect your platform, fetch the latest release, verify it, install it:

```sh
os="$(uname -s | tr '[:upper:]' '[:lower:]')"     # darwin | linux
arch="$(uname -m)"; case "$arch" in x86_64) arch=amd64 ;; aarch64|arm64) arch=arm64 ;; esac

# with gh (simplest — resolves the latest release automatically)
gh release download --repo koryph/koryph -p "koryph_*_${os}_${arch}.tar.gz" -p checksums.txt

# without gh (curl + GitHub API only)
tag="$(curl -fsSL https://api.github.com/repos/koryph/koryph/releases/latest | grep -m1 '"tag_name"' | cut -d '"' -f4)"
curl -fsSLO "https://github.com/koryph/koryph/releases/download/${tag}/koryph_${tag#v}_${os}_${arch}.tar.gz"
curl -fsSLO "https://github.com/koryph/koryph/releases/download/${tag}/checksums.txt"

shasum -a 256 -c --ignore-missing checksums.txt   # macOS; use `sha256sum -c --ignore-missing checksums.txt` on Linux
tar -xzf koryph_*_"$os"_"$arch".tar.gz koryph
install -m 0755 koryph ~/.local/bin/              # any directory on PATH
koryph version                                    # expect: koryph <version>
```

Building from source instead requires Go 1.21+: `go install github.com/koryph/koryph/cmd/koryph@latest`.

On macOS and Linuxbrew the tap is the simplest path: `brew install koryph/tap/koryph` (no Go required). Full prerequisites, PATH troubleshooting, and shell completions: [Installation](https://github.com/koryph/koryph/blob/main/docs/user-guide/installation.md). To verify a download's checksum, cosign signature, and SLSA provenance before trusting it: [Supply-chain verification](https://github.com/koryph/koryph/blob/main/docs/user-guide/supply-chain.md).

## Enable koryph in a project (agent runbook)

This section is a complete, executable sequence for an AI agent asked to
"enable koryph in this project". Execute it top to bottom; every step is
idempotent and safe to re-run. Ask the human only for the two values in
step 2 (account profile name, account email).

1. **Preconditions.** `koryph version` works (else run the Install section
   above); the target is a git repository; the agent runtime CLI is
   authenticated (e.g. `claude --version`); `bd` (beads) is installed. If the
   repo has no beads database yet, initialise it first: `bd init` in the repo
   root (confirm with `bd stats`).

2. **Register the project** (creates the machine-local registry record,
   scaffolds `koryph.project.json` if missing, and installs the agent
   scaffolding — `AGENTS.md`, `koryph-*` personas/commands, hooks/rules for
   runtimes that support them; never clobbers existing files):

   ```sh
   koryph project add <repo-root> --account <profile> --identity <email>
   ```

3. **Complete `koryph.project.json`.** Two fields matter most and cannot be
   guessed by koryph:
   - `gate`: the project's REAL build/test/lint commands — this is the merge
     gate; agents' work only lands when these pass.
   - `area_map`: directory-prefix → area-token map that powers footprint
     scheduling (parallel agents without merge conflicts). Map each top-level
     source directory to a short token (`"src/api": "api"`).

4. **Optional hardening** (recommended for repos that ship):
   - `koryph signing enable --project <id>` — SSH commit signing, key served
     from a vault (Proton Pass/1Password/macOS Keychain/encrypted file).
   - `koryph posture apply oss-solo-maintainer --repo <owner>/<repo>` —
     branch protection + repo security settings; diff-first, shows changes
     before applying.
   - `koryph release setup --project <id>` — the release train (versioning,
     SBOM/signature/provenance releases).

5. **Validate**: `koryph validate <id>` then `koryph doctor` — both must be
   clean (validate reaches `validated` after the first successful run).

6. **Create dispatch-shaped work.** Tasks live in beads. To be dispatched a
   bead MUST have type `task`, `bug`, or `chore` (never `epic`/`feature`) and
   SHOULD carry one `area:<token>` label per area it touches (tokens from
   `area_map`; unlabeled beads serialize behind everything). Use the
   installed `/koryph-plan` skill to decompose a design or prompt into a
   correctly-footprinted, dependency-linked graph, or create directly:
   `bd create "title" --type task --labels "area:api"`.

7. **First run** (single pass, review + auto-merge):

   ```sh
   koryph run --project <id> --once --auto-merge --review
   ```

   Watch with `koryph board` / `koryph roster --project <id>`. Merged work
   lands on the default branch only after review findings are addressed and
   the gate is green.

## Operating contract (read first)

- [CLAUDE.md](https://github.com/koryph/koryph/blob/main/CLAUDE.md): the koryph protocol every agent follows — beads-only task tracking, Conventional Commits + DCO + SSH-signed commits, protected paths, the green gate, and the `refactor-core` self-hosting rule.
- [README](https://github.com/koryph/koryph/blob/main/README.md): project invariants (account-safe, subscription-first, beads-as-truth), install, and the package layout table.
- [AGENTS.md](https://github.com/koryph/koryph/blob/main/AGENTS.md): canonical cross-runtime agent instructions.

## User guide

- [Installation](https://github.com/koryph/koryph/blob/main/docs/user-guide/installation.md): install `koryph`; per-user machine-local registry.
- [Quickstart](https://github.com/koryph/koryph/blob/main/docs/user-guide/quickstart.md): register a project and run a first wave end-to-end.
- [Zero to shipped](https://github.com/koryph/koryph/blob/main/docs/user-guide/zero-to-shipped.md): the full journey across the three pillars (Build/Protect/Ship) with today's shipped commands.
- [Projects & accounts](https://github.com/koryph/koryph/blob/main/docs/user-guide/projects-and-accounts.md): the `~/.koryph` registry, per-project account isolation, identity verification.
- [Running waves](https://github.com/koryph/koryph/blob/main/docs/user-guide/running-waves.md): the wave loop (scan → batch → preflight → dispatch → poll → review → merge), `--once`/`--only`/`--budget`.
- [Billing & quota](https://github.com/koryph/koryph/blob/main/docs/user-guide/billing-and-quota.md): subscription-first dispatch, the quota governor, throttling, calibration.
- [Signing](https://github.com/koryph/koryph/blob/main/docs/user-guide/signing.md): SSH commit signing via vault providers (Proton Pass, KeePassXC, 1Password, …).
- [Collaboration](https://github.com/koryph/koryph/blob/main/docs/user-guide/collaboration.md): the shared beads/Dolt task graph across collaborators.
- [Intake](https://github.com/koryph/koryph/blob/main/docs/user-guide/intake.md): pluggable issue intake — GitHub, Linear, JIRA — into planning beads.
- [Doctor](https://github.com/koryph/koryph/blob/main/docs/user-guide/doctor.md): `koryph doctor` — config validation, zombie-lease and orphan-worktree detection, `--fix`.
- [IDE integration](https://github.com/koryph/koryph/blob/main/docs/ide-integration.md): editor/account isolation and IDE setup.

## Developer guide

- [Architecture](https://github.com/koryph/koryph/blob/main/docs/architecture.md): system overview and Mermaid diagrams of the wave loop and data flow.
- [Packages](https://github.com/koryph/koryph/blob/main/docs/developer-guide/packages.md): the `internal/*` package map (engine, dispatch, merge, sched, quota, govern, …) and the dispatch-shape / footprint rules.
- [Global governor](https://github.com/koryph/koryph/blob/main/docs/developer-guide/global-governor.md): the cross-process, daemonless concurrency governor (flock + fair-share leases under `~/.koryph`).
- [Testing](https://github.com/koryph/koryph/blob/main/docs/developer-guide/testing.md): test layout, fixtures, and the green gate.
- [Releasing & versioning](https://github.com/koryph/koryph/blob/main/docs/developer-guide/releasing.md): semver, engine-version pinning, keyless cosign.

## Optional

- [Contributing](https://github.com/koryph/koryph/blob/main/CONTRIBUTING.md): contributor rules.
- [Security](https://github.com/koryph/koryph/blob/main/SECURITY.md): security policy and reporting.