keryx — Documentation Index

Developer documentation for the keryx CLI.

These pages describe what the current main implementation actually does. Product intent and future design work live separately, under docs/requirements/ in the repository; where the two disagree, this section is the one that describes shipped behaviour.

Contents

• onboarding.md — Install, first-run walkthrough, the typical build loop, and TTY/CI behavior.
• complete-setup-and-agent-workflows.md — Complete global installation, project configuration, commands, operational scripts, and agent prompts.
• agent-installation-playbook.md — Agent-executable Gherkin setup, repair, validation, and handoff scenarios.
• architecture.md — System overview, layered architecture, invariants, cross-module data flows, integrations.
• harness.md — The agent runtime: doors, providers, sessions and forking, policy, containment, evidence and the completion gate, record/replay.
• integrations.md — The harness adapter registry: keryx integrations install|doctor|uninstall|matrix, install-state and drift, the generated capability matrix, and per-harness notes (Gemini CLI, Kiro, GitHub Copilot agent, Zed).
• hooks.md — The keryx shell lifecycle hook runtime: the ten events, config files, composition with the policy engine, built-ins, the keryx hooks CLI, and the W3/W8 extension points.
• modules.md — Per-module reference: purpose, CLI surface, key files, mechanics, and data paths.
• learning.md — The self-learning loop: observe, extract, review/accept, apply, promote, graduate, prune — what is observed, what is never stored, the confidence model, and consent guarantees.
• cli-reference.md — Every command, subcommand, flag, and exit code.
• commands-by-task.md — Every command grouped by task, generated from the same table keryx help and the TUI's /help modal use.
• workspace-and-lifecycle.md — The .metaproject/ contract, manifest, agent entrypoints, and init/update lifecycle.
• limitations.md — Known gaps, platform support, optional AI features, and what to use instead.

Releases

• Changelog — what has landed in each release, with a standing known-gaps list.
• Releases — tagged versions, each published to npm with provenance.

Guides — organised by what you are trying to do

• Give an agent context about my repository
• Give a subagent a name instead of a paragraph
• Use Shared Agent Context (workspaces, FWK, proposals)
• Choose an approval mode: ask, trust, auto
• Run an agent against a repository without giving it my machine
• Drive a foreign ACP agent (Gemini CLI) under keryx's policy
• Let an external agent write, then review and land its diff
• Agent web search
• Use local SearXNG for agent web search
• Drive keryx from a bot or another product
• Answer a remote approval from a bot or another product
• Review a branch and keep a durable record
• Review every pull request with a bot, and measure it
• Run a review unattended, on a schedule or a trigger
• Let an arbiter answer the orchestrator's questions
• Jev in the delivery loop
• Get a GitHub and board digest on a schedule
• Take work in from GitHub as cards in Telegram
• /goal — deterministic starts, optional autonomous continuation
• Slate for external agents
• Keep the wiki current
• Run keryx in CI
• Undo a turn with /rewind
• Keep a record of what an agent recommended and what you chose
• Move skills, rules, agents, and memory between projects and machines
• Write a rubric (judge) eval scenario

Start here: new to the project? Begin with onboarding.md, then pick the guide that matches your task.