Skip to content

Features

Every major koryph capability on one page, grouped in the order you meet them: adopt a repo, plan work, build in parallel, gate what lands, govern the spend, recover from failure, operate the fleet, protect the repo, ship a release. Each entry is a summary with a link to the chapter that operates it — this page is the map, not the territory.

New to koryph? Read the Concepts overview for the ideas in order, or The lifecycle for how these features chain into one loop from prompt to release. Items marked new shipped in the current release.

Adopt — one command to a working factory

  • The koryph adopt wizard (new) — point koryph at any existing git repo and one command takes it to a green koryph validate: detect → plan → consent → execute → verify. It installs missing prerequisites with consent, initialises and hardens beads, derives the account, gate, forge, and area_map, installs the agent scaffolding, and offers one signed adoption commit. Re-running it is a free health check. → koryph adopt
  • The /koryph-adopt skill (new) — once one repo is adopted, an agent session can drive the same wizard conversationally for any other repo. → koryph adopt
  • Agent-drivable onboarding — koryph adopt <root> --yes --json is the whole onboarding runbook in one non-interactive command that fails closed on anything ambiguous; llms.txt carries the manual fallback so any AI session can adopt koryph unassisted. → Quickstart
  • Lower-level verbs stay put — koryph project add, install-assets, validate, and doctor keep their contracts; adopt sequences them. → Projects & accounts

Plan — describe it, get a dispatchable task graph

  • Intent routing (new) — describe what you want to build, change, or fix in a normal agent session; the installed koryph-intent.sh hook detects work-shaped prompts and routes the session to the right planning command instead of letting it implement ad hoc. Advisory, fail-open, byte-frugal. → From prompt to beads
  • /koryph-design (new) — the front door for feature-sized asks: it clarifies the ask, grounds it in your actual repo, writes a design doc, stops for your approval, then hands off to decomposition. → From prompt to beads
  • Planning skills — /koryph-plan decomposes a design doc into an epic plus dependency-linked, footprint-labelled child beads; /koryph-import converts existing ROADMAP.md/TODO.md corpora; /koryph-issue files a single well-formed issue; koryph plan analyses a corpus for conflicts. → From prompt to beads
  • Beads and the ready-graph — work lives in beads, a dependency-aware issue database that travels with the repo through its own git remote. The set of unblocked beads is the frontier the scheduler feeds from — no human dispatcher. → Work: beads and the ready-graph
  • Issue intake — pull GitHub issues (and other trackers) into the planning funnel as beads. → Intake

Build — a fleet without merge conflicts

  • Footprint scheduler — every bead declares what it touches (area:*, fp:read:* labels); only mutually conflict-free work dispatches together, which is what makes "run eight agents at once" safe rather than reckless. → Parallelism: footprints
  • Rolling dispatch — slots refill continuously as work finishes; the fleet never idles waiting for the slowest member of a wave. → Time: rolling dispatch
  • Worktree isolation — each agent works in its own git worktree on its own branch; your checkout is never touched, and a misbehaving agent can be discarded without cleanup. → Safety: worktrees and the green gate
  • Personas and model tiers — tasks name the kind of worker they need (implementer, reviewer, architect, validator) and a tier (frontier / standard / light) rather than a hard-coded model; each runtime maps tiers to its own models. → People: accounts and personas
  • Runtime-neutral core — the adapter seam, runtime:<name> labels, and per-provider quota blocks are built; Claude Code and Codex are supported runtimes today and everything else is declared but unshipped — dispatch to an unshipped runtime is refused fail-closed rather than guessed at. → AI runtimes: support status

Gate — nothing lands that doesn't pass

  • Review pipeline — every finished branch gets a one-shot reviewer whose findings block the merge until addressed; then rebase onto current main. → Running waves

  • The green gate — your project's own commands are the merge gate. A real example, verbatim from koryph's own koryph.project.json:

    "gate": [
  "test -z \"$(gofmt -l .)\"",
  "go build ./...",
  "go vet ./...",
  "go test ./...",
  "make lint",
  "make reuse"
]

    If any command exits non-zero, the branch does not land. The gate is yours: swap in npm test, cargo clippy, pytest — koryph never chooses your toolchain. → Safety: worktrees and the green gate - Merge policies — auto (fast-forward when review is clean), manual (operator lands it), or pr (push the branch and open a PR for protected default branches, landed later with koryph land, fast-forward only). Epic labels override project config per subtree. → Running waves - Protected paths — merges touching CI workflows, hooks, or policy files are refused outright regardless of gate results; a human lands those deliberately. → Safety: worktrees and the green gate - Merge reconcilers — derived artifacts (lockfiles, generated indexes) collide at merge even when their inputs don't; declared reconcilers let those residual collisions self-heal. → Merge reconcilers - Epic validation — after the last child of an epic merges, a frontier-tier validator reviews the union of everything that shipped for completeness (did it meet the design, in letter and spirit?) and structural health (duplication, architecture drift). Gaps become follow-up beads and re-enter the loop; a passing epic files a docs-update bead before it closes. → Epic validation

Govern — the machine, the money, and the rate limits

  • Resource governor — footprints protect the merge; resources protect the machine. Beads declare external runtime demand (res:kind-cluster, res:docker, res:dev-server); each kind has a counted capacity on this host, so two 6 GB dev clusters never co-dispatch, and leak detection attributes anything left behind. → Machine: resources
  • Memory admission — dispatch subtracts every ramping lease's declared memory reservation before admitting the next agent, so a wave can't pass the free-RAM check and then thrash the host mid-provision. → Machine: resources
  • Adaptive concurrency governors — per-provider, per-account pools with AIMD adaptation: rate-limit responses halve the cap immediately (with settle windows and circuit breakers to prevent thrashing); sustained success probes it back up. The fleet runs at the edge of what your provider allows and never past it. → Money: governors and quota
  • Subscription-first billing — dispatch rides your flat-rate CLI subscription; per-token API spend requires explicit opt-in and only after the subscription window is exhausted. → Billing & quota
  • Quota tracking and calibration — live burn against your plan's 5-hour and weekly windows, measured from a background transcript scan and calibrated against observed usage; a governor ladder warns at 90%, throttles at 94%, gracefully stops at 97%, and hard-stops at 99% — so the fleet never torches an allocation you needed for tomorrow. → Billing & quota
  • Context economy — token telemetry, cache-hit tripwires, prompt-prefix hygiene, and output caps keep agent context lean so quota goes to real work. → Context economy

Recover — failure is an input, not an outage

  • Stall and death detection — structured heartbeat monitoring flags a silent agent within minutes, and a health patrol sweeps for dead agents and stuck claims on a fixed cadence, auto-fixing what it safely can. (new: patrol sweep, stale-park detection) → Typed recovery
  • Classified retries — every requeue carries its cause (gate, merge, conflict, rate-limit, budget-kill) with a bounded retry budget; a budget-killed agent warm-resumes its own session instead of starting over. → Typed recovery
  • Typed recovery — evidence classifies completion, code, semantic, security, runtime, budget, turn, mechanical, stop, and invariant outcomes. Bounded standard-tier repairs are distinct from frontier security/recovery analysis; retry count never promotes implementation. → Typed recovery
  • Historical model evidence — koryph models reports historical or explicitly typed provenance; applying a recommendation is an explicit routing override, not a retry side effect. → Typed recovery
  • Operator overrides that stick (new) — koryph merge --close-bead on a live loop records your manual merge in an override sidecar the engine folds in (instead of clobbering your hand-work); koryph inject adds a bead to a running loop without a restart; koryph status --frontier shows exactly why each ready bead did or didn't dispatch last wave. → Typed recovery

Operate — watch and steer, from any terminal

  • Terminal cockpit (overhauled this release) — koryph tui is a full cockpit over SSH: live threads with stall flags and escalation markers, epic burndown with P50/P90 ETAs, a filterable event feed, governor and quota gauges, estimator calibration, token economy, a hierarchical queue, and a live activity tail that follows an agent's thinking and tool calls in real time. → Terminal cockpit (TUI)
  • One-shot views — koryph board (fleet overview), koryph roster (per-bead lifecycle), koryph status [--frontier], koryph tail. → Quickstart
  • Live steering — koryph nudge (drop a note into a running agent's inbox), stop (graceful, never SIGKILL), drain (wind down), resize (change concurrency mid-run). → Running waves
  • Doctor — one command reports drift across settings, signing, credentials, release infra, zombie leases, orphan worktrees, and stranded epics — with --fix for what's safely automatic. → Doctor
  • Observability — structured JSONL logs, traces, and metrics under ~/.koryph/telemetry/, queryable with jq/DuckDB, with optional OTLP export. No telemetry ever leaves your machine otherwise. → Observability
  • VS Code extension — the same cockpit data in your editor: tree view, transcripts, quota status bar. → VS Code extension

Protect — hygiene as code

  • Account safety — each project pins the account its agents run under; identity is verified fail-closed before any dispatch, never inherited from whatever shell happens to be logged in. → People: accounts and personas
  • Posture profiles — branch protection, repo settings, and scanner presets as named, diffable, applyable bundles (koryph posture), with the built-in oss-solo-maintainer profile as the opinionated default. → Posture profiles
  • Repo settings as IaC — rulesets and repo settings live as committed JSON; koryph repo check exits non-zero on drift, apply is diff-first with snapshots and rollback. → Zero to shipped
  • Vault-served signing — SSH commit signing with keys resolved on demand from Proton Pass, 1Password, macOS Keychain, or an encrypted file — never plaintext on disk by default. → Signing
  • Agent containment — dispatched agents get a credential-free, allowlisted environment; worktree and boundary guard hooks confine them to their own tree and deny orchestrator-only operations. Defense in depth, stated honestly: hooks are controls, not a sandbox. → Security

Ship — releases someone else can trust

  • The release train — conventional commits accumulate into a Release PR; merging it triggers gate-before-tag, an artifact build (GoReleaser or your own commands — any language), and a draft-until-complete release. → Shipping: the release train
  • Supply chain by default — SPDX SBOMs, keyless cosign signatures, and SLSA build provenance attach before anything publishes; releases are immutable and verifiable by anyone. → Verifying a release
  • The release bot — a vault-backed bot identity provisioned in one browser click so Release PR checks flow unaided, with graceful fallbacks when you can't install one. → Release bot
  • CI setup — koryph ci setup renders forge-native pipelines that run your gate on every PR, for GitHub or GitLab. → CI pipeline setup
  • Docs publishing — a Zensical/MkDocs book published to your forge's Pages on every docs push, custom domain included. → Release pipeline setup

Customize any of it

koryph is opinionated about process, never about your project — and every opinion above has a dial. The checked-in koryph.project.json carries your gate commands, area_map, protected paths, merge policy, concurrency cap, per-stage personas and model tiers, resource vocabulary, epic-validation rounds and validator model, and adaptive-escalation thresholds. Machine-side, ~/.koryph/governor.json sets per-provider caps, resource capacities, and memory floors, and posture profiles are plain JSON you can fork. See Projects & accounts for the full schema, and Epic validation for a fully-worked gating config.

Looking ahead

Aspirations, not commitments. Everything above this section ships today; everything below is direction. Nothing here oversells.

  • koryph across a cluster. Today koryph's ceiling is one machine — the governor's capacity ledger, the resource kinds, and the worktrees are all host-scoped. We aspire to a Kubernetes operator that runs koryph across a cluster: fleets scheduled over nodes, resource kinds mapped to cluster capacity, the same footprint and gate discipline at rack scale. Be clear-eyed about the economics before wanting this: a single laptop can already exhaust a typical subscription plan's allocation, so cluster-scale koryph is inherently a pay-per-token proposition. The operator will be the right tool for two kinds of users — those running their own GPUs with self-hosted models, and those with the budget to pay per token on frontier models. For everyone else, koryph's subscription-first defaults will keep protecting the flat-rate case, and API spend will always be explicit opt-in.
  • More runtimes, verified. The adapter seam is built and the alpha table is public — see AI runtimes: support status. We intend to grow past a single vendor as fast as adapters can clear the safety bar, and contributions are welcome.
  • A greenfield front door. koryph adopt onboards existing repos; a planned koryph new will scaffold repo, license, CI, beads, posture, signing, and release train in one shot — tracked in the open in docs/designs/.
  • Evolving with the providers. The AI vendors are moving fast — hosted agent harnesses, session checkpointing, new quota models. koryph will evolve as their tools evolve; the constants are the discipline (footprints, gates, provenance) and the fence (local-first, ejectable, yours).

Where to next