# 🧰 @pacphi/agentic-kit

[![CI](https://github.com/pacphi/agentic-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/pacphi/agentic-kit/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/@pacphi/agentic-kit/next?label=npm%40next)](https://www.npmjs.com/package/@pacphi/agentic-kit)
[![node](https://img.shields.io/node/v/@pacphi/agentic-kit)](https://nodejs.org)
[![license: MIT](https://img.shields.io/npm/l/@pacphi/agentic-kit)](LICENSE)
[![explainer](https://img.shields.io/badge/explainer-read_the_field_manual-C9581D)](https://pacphi.github.io/agentic-kit/)

**One npm package that installs, repairs, and checks [ruflo](https://github.com/ruvnet/ruflo) (claude-flow), its compatible browser executor, and [agentic-qe](https://github.com/proffesor-for-testing/agentic-qe), grounds them in *RuvNet Brain* — an offline, source-cited knowledge base over the rUv stack — and wires Claude Code + Codex (+ opencode) through one configurable activity-routing policy. macOS · Linux · Windows.**

```bash
npm install -g @pacphi/agentic-kit@next   # alpha channel until 4.0.0 GA
ak setup            # once per machine; run inside a git repo to set that project up too
ak setup --codex    # …or bring up Claude + Codex together in one shot
ak setup --opencode # …and wire ruflo + ruvnet-brain into opencode (third host)
```

> [!IMPORTANT]
> That's the only package you install by hand — **you do not need to install ruflo or
> agentic-qe yourself.** `ak setup` installs them globally for you (building natives past
> npm ≥11.17's `allow-scripts` gate), then runs scoped repair and verification checks.

`npm install -g` is the recommended interactive install, but it is not the only
way to run the package. Local dependencies, `npm exec`/`npx`, verified tarballs,
Git revisions, and contributor links have different package footprints while
`ak setup` retains the same machine/user/project effects. See
[Installation and scope](docs/installation.md) before choosing a non-global method
or deploying on a shared machine.

Want to try it before installing anything locally? Open this repo in GitHub
Codespaces (or any [dev container](https://containers.dev)-compatible tool) —
a "try the published release" configuration installs `ak` into a disposable
container for you. See [docs/devcontainers.md](https://github.com/pacphi/agentic-kit/blob/main/docs/devcontainers.md).

**What you get:**

- **One command** installs, repairs, and checks ruflo & agentic-qe — native SQLite, memory, security, statusline (past npm's `allow-scripts` gate).
- **Source-grounded knowledge:** *RuvNet Brain* — an offline knowledge base over the rUv stack — powers the `search_ruvnet` MCP tool, so answers about ruflo/AgentDB/RVF/SPARC cite real source instead of stale training priors.
- **Multi-host execution (optional):** Claude, Codex, and opt-in OpenCode can share one activity policy; `ak run` is the canonical executor, while `ak setup --codex` enables the subscription-backed Claude/Codex defaults.
- **Self-healing:** `ak sync` re-converges after every upgrade; `ak status` and a local dashboard report observed state and explicit evidence gaps.
- **Managed ruflo components:** ak applies and reports ruflo's opt-in agent pickers, MCP tool governance, learning profile, and promotional funnel — see [Managed ruflo components](docs/managed-tools.md#managed-ruflo-components).
- **Scoped verification:** `ak status --refresh=live` exercises named paths against real CLIs and
  reports their results; `ak status` shows each remembered result with its age, and a plain
  `--refresh=live` runs the quick, free subset first, while `--only CHECK` names one check
  (including a slow proof) directly. Registration,
  configuration, and one passing probe do not establish every capability or every running session.
- Cross-platform, **zero runtime dependencies** (SQLite embedded).

## Hosts, providers, and bindings

A **host** is the agent CLI driving a session (Claude Code, Codex CLI, or OpenCode). A
**provider** serves inference (Anthropic, OpenAI, OpenRouter, or Ollama). A **projection** is a
native configuration surface, and an **observability source** supplies transcript, usage, quota,
or catalogue evidence. A **binding** connects a host to a provider through a supported projection
and transport.

Those axes do not imply one another. OpenRouter is a provider behind a host, not another host.
Ollama can have independent bindings through Claude and Codex. Built-in OpenCode is an opt-in,
explicitly routable host through `ak run`, but it is not primary and has no built-in AQE provider
identity. Provider, model,
and billing claims state whether they are observed, configured, inferred, or unknown. Design
record: [docs/adr/0016-capability-driven-integration-adapters.md](https://github.com/pacphi/agentic-kit/blob/main/docs/adr/0016-capability-driven-integration-adapters.md).

For a capability-by-capability comparison of Claude, Codex, and OpenCode across
Ruflo, agentic-qe, and RuvNet Brain—including current limitations and upstream
issues—see [Host support](docs/host-support.md).

## Why this exists

ruflo promises persistent memory, self-learning, security scanning, and background
workers for Claude Code. In practice, a stock install drifts into quietly broken
states: native SQLite bindings get dropped by npm upgrades (memory writes vanish
while printing "OK"), packages the CLI still imports stop shipping
([#2670](https://github.com/ruvnet/ruflo/issues/2670) left prompt-injection defense
silently dead), pattern stores corrupt on interrupted writes, statuslines regenerate
without telling you what's actually on, and background daemons used to burn tokens
unsupervised. Upstream fixes land steadily — this kit's job is the *gap*: detect
drift, converge to a healthy state, and **prove it** rather than assume it.

The full investigative history behind each guard (with filed upstream issues) lives
in [docs/archive/](https://github.com/pacphi/agentic-kit/tree/main/docs/archive).

## The commands

```text
ak              status + one suggested next action
ak setup        first-time setup — machine and/or the project you're standing in
                [--codex] [--opencode] [--primary-host claude|codex]
                [--project] [--minimal]
                [--yes] [--no-aqe] [--no-security] [--reconfigure]
ak status       read-only dashboard: what's true, what's drifted   [--json] [--refresh[=live|machine]]
ak sync         converge to good: upgrade + heal + verify          [--dry-run] [--no-upgrade]
                [--skip SUBSYSTEM] [--retry-brain] [--json]
ak dashboard    open the local web dashboard (auto-opens your browser)
                [--port N] [--no-open] [--live-source 'surface=path']
ak admin        maintainer-only telemetry admin (localhost; GitHub/npm egress)
                [--port N] [--no-open]
ak about        what each installed component is and why it's there
ak system       machine footprint: install size, runtime, storage, catalog, projects
                [--refresh[=live|machine]] [--json]
ak maintain     findings, guidance, discovery, guarded one-action plans
                [report] [--refresh[=live|machine]] | inventory | show | guidance | discovery |
                sources | scans | activity | audit | reconcile | plan | apply | undo
ak usage        offline scorecard, prompt patterns, and provider account cache
                status | score | prompts | refresh openrouter
ak models       inspect model lifecycle evidence and swap impact
                status | refresh | diff | explain | plan
ak host         manage execution hosts, routing, and provider bindings
                status | pick | reset-routes | off | check-connection
ak audit hooks  read-only hook inventory across Codex, Claude, OpenCode, and adapters
ak audit context read-only managed-guidance, skill-metadata, MCP-registration, and window evidence
ak heal hooks   deterministic dry-run repair plan; explicit apply, verify, undo, recover
ak run          execute a host-neutral activity pipeline (including explicit OpenCode routes)
                <template> "<task>"  [--dry-run] [--route ...] [--max-concurrent N] [--timeout ms] [--json]
ak uninstall    leave cleanly                [--dry-run] [--this-project] [--remove-ruflo]
                [--remove-aqe] [--purge] [--yes]
```

> [!TIP]
> **When in doubt: `ak sync`.** Setup, sync, and uninstall support `--dry-run`. Maintenance uses a
> separate short-lived plan, digest, exact action IDs, and explicit `--yes` confirmation before it
> changes anything. See the [Maintenance runbook](docs/maintenance.md).

`ak` is the daily-driver alias; the full `agentic-kit` command is identical.
(Heads-up if you also use AutoKitteh: its CLI is also named `ak` — the full
command always works.)

Hook healing never edits trust state, plugin caches, generated runtime copies, opaque
OpenCode modules, or unsupported schemas. For exact verified profiles it can also retire
the frozen incompatible Ruflo Claude-hook projection one reviewed project at a time,
with an estate-wide transactional apply and guarded undo. See the
[hook assurance runbook](docs/hooks.md) for the preview/authorize/apply/verify/undo journey
and current platform limits.

<details>
<summary>What the verbs cover</summary>

| Verb | What it does |
| ------ | -------------- |
| **setup** | Installs/updates ruflo + agentic-qe globally (handling npm ≥11.17's `allow-scripts` so natives build; AgentDB ships inside ruflo, so ak installs no separate copy), installs and verifies the exact Ruflo-compatible **agent-browser** native executor without adding its plugin/skills (`--no-agent-browser` disables it), installs the **RuvNet Brain** (an offline knowledge base over the rUv stack, powering the `search_ruvnet` MCP — a ~2 GB one-time download, prompted; skip with `--no-ruvnet-brain`), merges the managed guidance blocks into the machine-wide guidance files (`~/.claude/CLAUDE.md`, plus `~/.codex/AGENTS.md` on codex machines), offers one-time MCP registration (user scope, with a tool-family picker), and — inside a repo — initializes the project: sanitized `ruflo init`, absolute memory-path pin, a **verified** store→disk write, statusline footer, and a background daemon with **local-only ($0) workers** (token-spending AI workers stay opt-in behind upstream's machine-wide budget). Project scope triggers on a `.git` entry in the current folder; without one it's skipped with a note. `--project` forces the same project setup in the current directory (e.g. a not-yet-`git init`-ed folder); it does not locate an ancestor repository. Project initialization runs `ruflo init --full --force` and can replace existing agent configuration, so read the [setup scope and project mutation contract](docs/setup.md) before using it on an existing project. `--minimal` skips it, `--yes` accepts all prompts (non-interactive), `--no-aqe` / `--no-agent-browser` / `--no-ruvnet-brain` / `--no-security` disable those subsystems, and `--reconfigure` re-offers MCP registration. `--codex` enables + installs the Codex host during setup (ambidextrous dual-host mode; both hosts become available for routing), and `--primary-host claude\|codex` picks which host leads (codex implies `--codex`). |
| **status** | Per-subsystem ✓/⚠/✗ (versions, the kit's own version, **ruvnet-brain**, natives, **memory-pin**, security, learning, aqe/RVF, the managed **agent-browser** package/native/config/browser readiness, MCP, **hosts**, **providers**, **routing**, daemons, guidance blocks, statusline), each drift row naming what `sync` would do about it, or marking a step you must take yourself as `→ manual:` (sync never plans those) — plus a **health-history** line that flags regressions since the last sync. Browser status is filesystem-only: it never runs doctor or launches Chrome. |
| **sync** | The one convergence verb: upgrades first when a new release exists, then re-heals everything an upgrade wipes, then re-checks and reports. Included in that heal: it **installs any enabled frontier host** (claude/codex/opencode) that's entirely absent — never touching an external (mise/brew/native) install — and **re-applies provider wiring** (the `ENABLE_*` host env, OpenCode's native configuration, the AQE default/fallback/agent overrides, and ruflo API providers) whenever it has drifted. On a dual-host project, sync also **seeds/heals the Claude/Codex default routing policy**. It appends a health-history snapshot, refreshes RuvNet Brain when enabled, and self-updates the kit last. A planned fix whose status row is still there afterwards is reported `unresolved:` and sync exits 1. A row whose fix you do by hand (`→ manual:`) never changes sync's exit code; a failing or warning one is listed under "needs your action". `--no-upgrade` skips self-update and package upgrades. `--skip <subsystem>` (repeatable) leaves one subsystem out of this run only, including the step it owns; it is reported "skipped by request" and never counts as a failure. A RuvNet Brain refresh that the installer refused is held until its release changes or the version-check interval passes (24 hours by default); `--retry-brain` permits one attempt past a fresh hold without clearing it, and cannot override `--no-upgrade`, `--skip ruvnet-brain`, or disabled Brain management. `--json` prints one JSON result on stdout (`plan`, `steps`, `unresolved`, `skipped`, `needsYourAction`, `converged`, `exitCode`) and sends the human lines to stderr. Model refresh/diff/plan findings remain advisory. |
| **dashboard** | Opens the local web dashboard (`127.0.0.1:7431`, localhost-only, never detaches) with five primary areas: **About · Overview · Usage · Observability · System**. Ordinary views remain observation-only. Choose **Refresh machine** in the header and press **Refresh** to remeasure the machine, refresh Maintenance evidence, and rebuild the inventory. **System → Maintenance** is the sole action surface, with four destinations: **Inventory** (scope → repository where applicable → type → resource → exact installation), **Guidance** (only outcomes the kit can ground), **Discovery** (where it looks), and **Activity** (receipts, undo, interruption audits). Every write is one exact placement and one action, with a server-derived short-lived plan, explicit confirmation, and a one-use capability. Advisory remains a measurement; the former Catalog tab redirects to Inventory and its cards now sit in System Summary. The page is self-contained, offline-first, protected by a per-session token, and never executes a browser-supplied command. Action targets resolve server-side; Discovery accepts validated source-root configuration. Full navigation and security semantics: [Dashboard guide](docs/dashboard.md); provider and recovery limits: [Maintenance runbook](docs/maintenance.md). **Auto-opens your browser** (`--no-open` for headless/SSH); `--port N` changes the port. Stop with Ctrl-C. (Also available as `ak x dashboard`.) |
| **usage** | `score` and `prompts` summarize retained local transcript evidence. `status` reads provider-account analytics from cache; `refresh openrouter` explicitly contacts the OpenRouter management API using `OPENROUTER_MANAGEMENT_KEY`, then writes a credential-free mode-`0600` cache. Cache reads make no OpenRouter request. Account rows have no grounded host/session/project correlation and are never merged into transcript totals. |
| **models** | Builds a private, host-scoped model inventory from Claude, Codex, OpenCode, Ollama, bounded local usage evidence, and a dated bundled record of Anthropic's public model/lifecycle facts. `status`, `diff`, `explain`, and `plan` are cache-only and read-only; `refresh --online` is the sole online-catalogue boundary. Public facts never imply account or OpenRouter routability. Swap plans enumerate routes plus Agentic QE/Ruflo consumers and print a copyable canonical action without executing it. The CLI exposes exact local evidence deliberately; the Dashboard exposes source-proven public catalogue identity and uses the owner-visible model read contract; secret-shaped values remain masked. See [Model lifecycle intelligence](docs/models.md). |
| **admin** | Opens the **maintainer admin** (`127.0.0.1:7432`, localhost-only, foreground) — the project-telemetry sibling of `dashboard`, with the same dark/light visual theme and persisted theme preference: unique repo visitors and cloners (GitHub traffic API, needs a push-access token via `GITHUB_TOKEN`/`GH_TOKEN`/`gh auth token` — panels degrade honestly without one), contributors and watchers, npm download momentum (last 7d vs prior 7d, sparklines — shown as trend only, never an absolute reach number, since mirrors/CI inflate the raw count), latest CI run status and open Dependabot alerts, a **"since you last looked"** delta strip over a local baseline, open issues/PRs from others (oldest first), and external humans ranked by recency (bots excluded). Access is gated by a **per-session token** carried in the URL fragment and sent header-only; the page makes **zero external fetches** (the server proxies GitHub/npm; your credential never reaches the page or the payload). Where `dashboard` is offline-first, `admin` does deliberate GitHub/npm egress — that contract split is why they're siblings, not tabs. `--port N`, `--no-open`; Ctrl-C stops. (Also available as `ak x admin`.) |
| **about** | A plain-words directory of every component the kit installs and configures — one entry per component: what it is, what it does for you, where to read more, and an honest state chip read from the same detection `ak status` uses (the prose is authored with the release; the chip is the only runtime fact). `ak about [entry-id]` opens one entry; `--category` narrows to `hosts`, `engine-memory`, `quality`, `safety`, `knowledge`, `kit`, or `configured`; `--no-detect` skips state resolution for an instant editorial read; `--json` emits the directory with resolved chips. The dashboard's About area renders this identical directory. |
| **system** | What the stack occupies on your machine. The default read is the cheap tier: the live agent-process census, the files growing fastest between scans, and the last full scan's figures carried forward with their date. `--refresh=machine` re-walks install trees, storage, the cross-host catalog, and the hosted repositories with recorded sessions, then persists the result; `--project-trees` also measures the working trees of your own projects; excluded local-only, unsupported-remote, and sessionless project candidates remain counted with reasons. Production runs this synchronous measurement in one worker so the dashboard can continue reporting activity; this is responsiveness containment, not a claim that the scan finishes sooner. `--json` emits the same snapshot payload `/api/system` serves. |
| **maintain** | Inventory-led maintenance. `inventory`, `show`, `guidance`, and `procedure` read the verified placement inventory and the outcomes the kit can ground; `discovery`, `sources`, and `scans` manage where it looks and resumable scan coverage; `activity`, `receipt`, and `audit` read receipts and run the read-only interruption audit. `ak maintain` (or `ak maintain report`) reads the last measurement; `--refresh[=live\|machine]` refreshes Maintenance evidence and the inventory first, adding live checks or a full machine re-measure as named. Every write is one action: `plan --executable` derives one action, `apply` needs the plan ID, digest, one action ID, and `--yes`, `undo` needs a committed reversible receipt, and `reconcile` records one audited outcome for one receipt. `recover` is a read-only alias for `audit`. Placements without a registered provider stay report-only. See [Maintenance](docs/maintenance.md). |
| **run** | **Canonical execution surface.** Executes the template vocabulary through host-neutral supervised adapters. It accepts an explicit OpenCode route (persisted or `--route`) alongside Claude/Codex; `--dry-run` prints the exact static plan (with each worker's escalation ladder); at runtime, successful dependencies pass runtime-only, sanitized handoffs capped at 2 KiB each/8 KiB fan-in, never exposed in public JSON. A handoff may cross hosts/vendors and must exclude secrets, credentials, raw logs, and transcript excerpts. `--escalate` advances a failed worker one rung of its route's ladder per attempt (bounded by the ladder; permission/consent and uncertain results are never escalated). `--timeout` is one absolute readiness→prepare→launch→observe budget per attempt, while separately bounded teardown proves whether resources terminated. An OpenCode worker runs an isolated loopback server with ephemeral basic authentication, returns only normalized observed facts, and aborts instead of approving a permission request. `ak run` does not turn OpenCode into an AQE provider or primary host. |
| **host** | Execution-host status, selection, primary-host choice, activity routing, reversible teardown, and the consent-gated connection check: `ak host status\|pick\|reset-routes\|off\|check-connection`. The plumbing spelling is `ak x host`. Inference providers and bindings remain separate concepts even though their controls share this workflow. |
| **uninstall** | Removes the kit's footprint (and any legacy shell-kit install); owned configuration is removed and ak's receipted edits inside Ruflo's install are put back, while project memory/transcripts are retained by default; `--purge` widens the documented package/config scope. |

</details>

Power-user mechanisms live under `ak x …` (`daemon-gc`, `harvest`,
`mcp status|pick|off`, `host status|pick|reset-routes|off|check-connection`, `reference diff|sync`,
`statusline status|codex native|codex extended|codex off`,
`improvement-eval`) — see `ak --help --all`. Named checks and slow proofs (`learning`, `security`,
`aqe`, `providers`, `harvest`, `memory`, `memory-routes`, `mcp`, `aqe-embedding`) run
through `ak status --refresh=live --only CHECK`.

One of those is worth calling out:

- **`ak x harvest`** — an **opt-in** (`kit.json` `harvest:true`), foreground learning-*write*:
  it records the session outcome through Ruflo's own `ruflo hooks post-task`, run from the
  project root with the project memory pin; `--distill` also runs Ruflo's memory distillation
  (`ruflo memory distill run`) on the project store. Off and `--dry-run`-safe by default; no
  daemon, ever. `ak status --refresh=live --only harvest` proves the path against an isolated
  temporary store.

## The status line

Projects set up by the kit get an append-only footer under ruflo's own status line,
with segments reflecting their documented presence and metric checks: 🧠 SONA patterns/trajectories (+
live micro-LoRA Δ‖W‖), 📈 route-RL metrics, a ⚠ aidefence OFF alarm (only when Ruflo has no
prompt-injection engine at all), 🧿 RuvNet Brain KB,
⚙ machine-wide daemon count, and 🎓 Agentic-QE stats.

That rich, command-backed footer is a Claude Code surface. Codex supports a
single native line made from built-in fields instead. Opt into a compact
machine-wide preset with `ak x statusline codex native` (or use `extended` on
a wide terminal); `ak sync` then keeps the selected preset converged without
rewriting unrelated `~/.codex/config.toml` settings. See
[Managed Codex status line](docs/codex-statusline.md) for fields, ownership,
rollback, and the current parity boundary.

## Requirements

The runtime requires Node 22.13.0+ on the 22.x line or Node 23.4.0+ on later
lines (`>=22.13.0 <23 || >=23.4.0`), where `node:sqlite` is available without a
flag. Use a maintained release in the tested Node 22/24/26 lines. CI separately
checks the minimum 22.13.0 runtime. See [Node SQLite history](https://nodejs.org/api/sqlite.html).

A supported Node release and npm are the runner prerequisites. Enabled host CLIs can be installed
by setup; authentication is separate and required for inference.
**ruflo and agentic-qe are not prerequisites; `ak setup` installs them for you**
(pre-installing them is fine too — setup just detects and reuses them). Everything
else — including SQLite — is embedded; there are no runtime dependencies. npm stays
required at runtime even though this repo develops with pnpm: the kit heals the
*npm-managed* global ruflo/agentic-qe trees (`npm root -g`, `npm i -g`), which is how
those packages are installed on target machines. (pnpm-managed globals: tracked follow-up.)

### Frontier hosts & LLM providers

`ak` detects the frontier-agent CLIs on your machine and can wire ruflo + agentic-qe to
the supported hosts — **Claude default, Codex and OpenCode opt-in**, so existing repos see zero change until
you opt in.

<details>
<summary>Two independent axes: hosts, providers, and per-activity routing</summary>

- **Hosts** — which agent CLI runs a worker: `claude` (Claude Code), opt-in `opencode`, and/or `codex`
  (OpenAI Codex), **both at once** in ambidextrous dual-host mode (enabling codex doesn't disable claude).
  Turn codex on at first-time setup with `ak setup --codex` (add `--primary-host codex` to
  make it lead), or later with `ak host pick`. A host that is *entirely absent* is
  installed for you (`npm i -g @anthropic-ai/claude-code` / `@openai/codex`); an
  externally-managed install (mise/brew/native) is detected, reused, and never shadowed.
- **Providers** — which LLM the routers use, independent of the host: agentic-qe's
  `AQE_LLM_PROVIDER` (`claude-code`/`claude`/`openai`/`gemini`/`openrouter`/`azure-openai`/
  `bedrock`/`cognitum`/`ollama`/`onnx`) plus an ordered fallback chain, and ruflo's API providers.
  API keys stay in the environment — never written to `kit.json`.

> [!NOTE]
> ruflo and agentic-qe keep **separate config stores** — they don't share one file. `ak`
> converges both from `kit.json`. Which store to edit for which knob is in
> [docs/providers.md](docs/providers.md#native-configs-one-front-door).

- **Per-activity routing** — when **both** hosts are enabled (and agentic-qe ≥ 3.13.1), `ak` seeds a
  policy that routes each kind of work to the host + model that suits it — Claude for architecture,
  design, review; Codex for implementation, testing — and materializes it into agentic-qe's
  `agentOverrides` (adopting upstream [#568](https://github.com/proffesor-for-testing/agentic-qe/issues/568)).
  It's seeded automatically (subscription-only, so no metered surprises), shown in `status` and the
  dashboard matrix, and **tunable per activity** (`ak host pick --route 'testing:claude:claude-sonnet-5-5'`)
  with your edits preserved across syncs. **`--primary-host claude|codex`** chooses which host leads:
  codex-primary *mirrors* the default table so Codex drives and Claude is the alternate — symmetric
  either way. `ak run <template> "<task>"` executes a materialized plan from that policy. Nothing is
  seeded for claude-only projects.

  **OpenCode is explicit, not seeded.** Enable it with `ak host pick --host claude,opencode`,
  then route a compatible activity through `ak run`, for example
  `ak run security "src/auth/" --route 'security-scan:opencode:provider/model'`.
  OpenCode routes are not projected to AQE, do not affect vendor-diversity claims, and cannot be a
  primary host.

`ak host status` shows each host as Managed by ak, Found, not managed, or Not installed, plus
what's wired and routed; `ak host pick` chooses and
applies (reversibly); `ak host off` restores the claude-only default. Full guide:
[docs/providers.md](docs/providers.md). Already on an older `ak` and adopting a later capability
(like dual-host)? [docs/upgrading.md](docs/upgrading.md) covers the `sync` vs `host pick` motion.
The detailed compatibility matrix is in [docs/host-support.md](docs/host-support.md).

</details>

### opencode host (opt-in)

[opencode](https://opencode.ai) is a third host alongside claude/codex — wired through its own
native surfaces rather than env flags.

<details>
<summary>What <code>ak setup --opencode</code> / <code>ak sync</code> converge</summary>

`ak setup --opencode` (or `integrations.hosts.opencode: true`
in `kit.json`) converges, on every `ak sync`:

- **`~/.config/opencode/opencode.json`** — connected `claude-flow`, `agentic-qe`, and
  `ruvnet-brain` MCP entries, plus Ruflo skill paths and explicit permission rules. Values are
  merged backup-first into the operator's existing JSON; collisions and user-authored tool or
  permission policies are preserved rather than overwritten.
- **Compact rUv gateway** — `claude-flow` and `agentic-qe` remain visibly connected in OpenCode,
  while their hundreds of direct tool schemas are blacklisted from provider requests and exposed
  lazily as `ak_ruflo_search` / `ak_ruflo_call` and `ak_aqe_search` / `ak_aqe_call`. RuvNet Brain
  remains a small direct MCP. The gateway asks through OpenCode's permission system before calls
  and opts a family back into direct exposure when user tool policy conflicts with projection.
- **Lifecycle hooks** — `~/.config/opencode/plugins/ruflo-hooks.js`: session restore/end,
  best-effort bash safety screening (defense-in-depth, fail-open if the local handler is
  unavailable), edit/task outcome recording for ruflo's learning substrate
  (opencode has no settings-hooks surface; its plugin events are the hook spine), plus a bounded
  repeated-tool guard. Three identical completed tool/argument/output calls in one user turn stop
  a fourth identical attempt; changed calls, outputs, user turns, and sessions do not collide.
- **Lazy specialists + skills** — one receipt-owned `ak-specialist` subagent replaces the eager
  107-profile task catalogue. The complete converted catalogue is embedded in the gateway and
  reached through `ak_agent_search`, stock OpenCode `task`, and `ak_agent_load`. Installed skills
  remain loadable through stock `skill`; only their eager system-prompt catalogue is compacted
  behind `ak_skill_search`. Optional external MCP dependencies named by a specialist are reported
  explicitly and are never presented as installed by Agentic Kit.
- **Guidance** — `~/.config/opencode/AGENTS.md` gets ak's managed blocks with
  the compact OpenCode workflow and direct RuvNet Brain grounding rule.

Everything is value- and SHA-receipted under `integrations.ownership.opencode` and stripped surgically by
`ak host off` / `ak uninstall` — your own opencode.json entries are never touched.

**Execution routing.** `ak run` is the host-neutral runner for explicit OpenCode routes. For
each worker it starts an owned `opencode serve` instance on loopback with an ephemeral basic-auth
password, creates an isolated session, and returns normalized terminal evidence. A timeout or
cancellation aborts the session before the owned server is terminated. A permission request is
reported as blocked and aborted — `ak` never supplies `--auto` or changes your OpenCode permission
policy. The configured `provider/model` selector is not provider or billing evidence; those facts
remain unknown unless OpenCode reports them in the terminal session data.
Design record: [docs/adr/0017-opencode-host.md](https://github.com/pacphi/agentic-kit/blob/main/docs/adr/0017-opencode-host.md).

</details>

## Troubleshooting

[docs/troubleshooting.md](docs/troubleshooting.md) — symptom → `agentic-kit` command.

[docs/installation.md](docs/installation.md) — global versus local, one-shot,
tarball, Git, and source-checkout installs, including user/machine/project impact.

[docs/host-support.md](docs/host-support.md) — Claude, Codex, and OpenCode support
across Ruflo, AQE, and RuvNet Brain, with limitations and current upstream risks.

[docs/devcontainers.md](https://github.com/pacphi/agentic-kit/blob/main/docs/devcontainers.md) — Codespaces/dev container setup,
both for contributing to this repo and for trying the published release.

[docs/dashboard.md](docs/dashboard.md) — dashboard navigation, deep links, keyboard behavior, and
the meaning of each primary and secondary view.

[docs/maintenance.md](docs/maintenance.md) — the inventory-led Maintenance workspace, including the
implemented Focus browser, contextual relationships, and exact
action boundaries: Inventory,
Guidance, Discovery, Activity, one-action plans, undo, interruption audit and reconciliation, the
`ak maintain` verbs, and the exact provider limits.

## How tools are managed

[docs/managed-tools.md](https://github.com/pacphi/agentic-kit/blob/main/docs/managed-tools.md) — the consistency contract every
managed tool follows (release-pinned installs, sync as the single updater,
disk-first version truth, one drift story across status/statusline/dashboard),
with the per-tool table and the checklist for adding a new tool.

## Domain design

[docs/ddd/](docs/ddd/) defines the shared language, bounded contexts, and invariants behind hosts,
inference providers, bindings, routing, orchestration, evidence, usage, and Observability. ADRs
explain why decisions were made; the domain documents define what those concepts mean across the
codebase.

## Credits

### Upstream & prior art

- [rUv](https://github.com/ruvnet) — [ruflo/claude-flow](https://github.com/ruvnet/ruflo); upstream issues filed from this kit's verification work: [#2219](https://github.com/ruvnet/ruflo/issues/2219), [#2222](https://github.com/ruvnet/ruflo/issues/2222), [#2239](https://github.com/ruvnet/ruflo/issues/2239), [#2360](https://github.com/ruvnet/ruflo/issues/2360), [#2549](https://github.com/ruvnet/ruflo/issues/2549), [#2670](https://github.com/ruvnet/ruflo/issues/2670)
- [Dragan Spiridonov](https://github.com/proffesor-for-testing) — [agentic-qe](https://github.com/proffesor-for-testing/agentic-qe)
- [Stuart Kerr](https://github.com/stuinfla) — [RuvNet Brain](https://github.com/stuinfla/ruvnet-brain), the source-grounded knowledge base over the rUv stack that `ak setup` installs and `ak sync` keeps current
- [Ciprian Melian](https://github.com/ciprianmelian) — prior art: [repair gist](https://gist.github.com/ciprianmelian/eb7e8ff7d24018141ca34bb8a7e216a6)

### Contributors

Thanks to everyone who opened PRs against this kit (v4.0.0-alpha.15 through the
current release):

- [@robertelee78](https://github.com/robertelee78) — [#67](https://github.com/pacphi/agentic-kit/pull/67), [#85](https://github.com/pacphi/agentic-kit/pull/85), [#86](https://github.com/pacphi/agentic-kit/pull/86), [#87](https://github.com/pacphi/agentic-kit/pull/87), [#89](https://github.com/pacphi/agentic-kit/pull/89), [#90](https://github.com/pacphi/agentic-kit/pull/90), [#91](https://github.com/pacphi/agentic-kit/pull/91), [#152](https://github.com/pacphi/agentic-kit/pull/152), [#165](https://github.com/pacphi/agentic-kit/pull/165) — built the OpenCode path from managed host integration and execution protocol through QE-court remands, usage/transcript attribution, bounded escalation, security and Windows hardening, a compact lazy Ruflo/AQE/RuvNet gateway, and a fail-closed cross-turn tool-loop guard
- [Anupam Mediratta](https://github.com/anupamme) — [#78](https://github.com/pacphi/agentic-kit/pull/78) — added seven-day Dependabot cooldowns to reduce exposure to newly published malicious or unstable package versions
- [Adrian Cockcroft](https://github.com/adrianco) — [#130](https://github.com/pacphi/agentic-kit/pull/130), [#131](https://github.com/pacphi/agentic-kit/pull/131) — fixed global npm-root discovery for kegged and versioned Node layouts, with a bounded cross-platform ancestor walk, `npm_config_prefix` support, and regression coverage; co-authored the Hermes adapter effort by defining the external host-adapter seam, Hermes conformance and security requirements, and field validation that shaped the subprocess-hook contract

> v4 (npm, cross-platform). The shell-based v3 kit is archived in
> [docs/archive/](https://github.com/pacphi/agentic-kit/tree/main/docs/archive) — `ak setup` migrates an existing shell-kit
> install automatically. A thin, reversible layer — not a fork. PRs welcome.

## Fleet evidence

Use `ak telemetry export --output ./snapshot.json` to produce a private, versioned JSON snapshot
of usage and retained maintenance evidence. `ak telemetry aggregate FILE...` combines the latest
snapshot per installation without counting repeated exports twice. No vendor dashboard or network
service is required. See [Fleet evidence export](docs/telemetry.md) for schema, coverage and limits.