Field manual · read cover to cover in about ten minutes

The toolbox that keeps your AI stack honest.

agentic-kit in one sentence: it's one npm package that installs your agentic tooling, heals it every time an upgrade quietly breaks something, and — the part that makes it different — runs scoped checks against the installed tools and reports gaps in the evidence.

pkg @pacphi/agentic-kit runtime deps zero node ≥ 22 platforms macOS · Linux · Windows license MIT

PANEL 01Start with why

Great tools drift. Trust shouldn't.

agentic-kit exists because of a very specific, very modern kind of heartbreak. You wire up an AI agent stack — persistent memory, self-learning, security scanning, background workers — and it's glorious. Then one npm upgrade later, some of it is quietly off. Not crashed. Not erroring. Just… silently doing nothing, while printing "OK."

These aren't hypotheticals. Each of these really happened, and each one now has a guard in the kit that traces back to a filed upstream issue:

Incident · memory

Writes that vanish while printing "OK"

npm upgrades drop native SQLite bindings. The memory CLI keeps reporting success — but nothing lands on disk. The kit now does a verified store→disk write and load-tests the natives.

Incident · security

A defense layer, silently dead

A package the CLI still imported simply stopped shipping (ruflo #2670) — and prompt-injection defense went dark without a peep. The kit proves security end-to-end against the real CLI.

Incident · statusline

Status displays that lie by omission

Statuslines regenerate themselves without telling you what's actually enabled. The kit's footer reports source-specific presence and metric checks, including absence/degraded states where provided. It is not proof that every capability is active.

Incident · daemons

Background workers burning tokens

Unsupervised daemons used to spend real money overnight. The kit sets up local-only ($0) workers by default; token-spending AI workers stay opt-in behind a machine-wide budget.

Incident · host transport

A retirement notice, filed under nobody's desk

OpenAI retired the standalone codex mcp-server transport, but a registration made under it doesn't un-register itself — it can keep sitting at user or project scope while sync reports convergence anyway. ak host align finds it, previews the exact scoped fix, and the dashboard's new Host alignment view offers the same repair with a recovery backup — never automatic.

DWG 01 · The golden circleafter S. SinekSheet 1 of 2

Most tooling starts at the outer ring — what it does. agentic-kit starts at the center: the conviction that in a fast-moving agent ecosystem, proof beats promises. Everything else on this page is that belief, mechanized.

The operating principle

Upstream ships fast, and that's good. This kit's job is the gap: detect the drift, converge to a healthy state, and prove it — never assume it.

PANEL 02What's in the box

Open the drawers

You install exactly one package by hand. Everything else — the whole stack below — is installed, wired, healed, and verified for you by ak setup. Here's what ends up under management:

Drawer A

ruflo (claude-flow)

The orchestration engine: persistent memory, self-learning, security scanning, swarms, and background workers for Claude Code. The kit installs it globally, builds its native SQLite past npm's allow-scripts gate, and pins its memory store so writes verifiably land.

memory + HNSWneural learningaidefence300+ MCP tools

Drawer B

agentic-qe

A quality-engineering fleet: AI test generation, coverage analysis, quality gates, security scans. The kit keeps its companion agentdb CLI pinned to ruflo's bundled version so the shared learning store stays coherent.

test generationcoveragequality gatesagentdb pinned

Drawer C

RuvNet Brain

An offline, source-cited knowledge base over the rUv stack (~2 GB, one-time, prompted). It powers the search_ruvnet tool, so answers about ruflo/AgentDB/RVF/SPARC cite real source instead of stale training priors.

offline KBcited answersdrift-checked

Drawer D

The hosts

The agent CLIs that drive sessions: Claude Code by default, Codex opt-in (both at once, in "ambidextrous" dual-host mode), and OpenCode as an explicitly-routed third. Absent hosts get installed; externally-managed ones (brew/mise) are detected and never touched.

claude — defaultcodex — opt-inopencode — explicit

Drawer E

The kit's own surfaces

What agentic-kit adds on top: an honest statusline footer, a local web dashboard with five areas (About · Overview · Usage · Observability · System), a maintainer admin panel, and the ak CLI itself — zero runtime dependencies, SQLite embedded.

statuslinedashboard :7431admin :7432ak / agentic-kit

The workbench — every daily-driver verb

Command

What it does, in a phrase

Status plus one suggested next action — the "what should I do?" answer.

ak setup

First-time setup for the machine, your user config, and the project you're standing in.

ak status

Read-only truth: per-subsystem ✓/⚠/✗, each drift row naming what sync would do about it.

ak sync

The one convergence verb: upgrade → heal → verify. When in doubt, run this.

ak dashboard

Local web dashboard — localhost-only, token-guarded, with guarded Maintenance actions.

ak host

See, pick, and reversibly tear down execution hosts, routing, and provider bindings.

ak run

Execute a multi-worker activity pipeline (feature, security, refactor…) across hosts.

ak about · system

What each component is and why it's there · your machine's actual footprint.

ak uninstall

Leave cleanly. Project memory and transcripts are retained by default; --purge offers the global packages too.

Power-user plumbing lives under ak x … (verify, harvest, statusline, mcp pick, reference sync…) — ak --help --all lists the lot. Use --dry-run where offered to preview managed changes, and consult command help for its scope.

PANEL 03How it works

The convergence loop

Everything the kit does is one loop, run over and over for the life of your machine: detect what's drifted, converge back to healthy, prove the result against the real CLIs. Three verbs, three commands.

DWG 02 · Detect → Converge → Proveruns after every upgradeSheet 2 of 2

Detect · ak status

Truth, not vibes

Every subsystem gets a ✓/⚠/✗ — natives load-tested, memory pin checked, hosts and providers compared against what you chose. Each drift row says exactly what sync would do about it.

Converge · ak sync

One convergence verb

Upgrades first, then re-applies everything an upgrade wipes: native builds, guidance blocks, provider wiring, routing policy, the Brain. The kit self-updates last, so new code never applies mid-run.

Prove · ak x verify

Evidence, end to end

Verification runs the real installed CLIs — a memory write that must land on disk, a security scan that must actually scan. If it can't be proven, status says so instead of guessing.

What that looks like — a real `ak status`, from a real machine

This historical excerpt was captured with agentic-kit 4.0.0-alpha.41; the capture date was not recorded. It illustrates the status layout, not current releases or current machine health. In particular, later fixes qualify the active-writer and billing assertions shown below. Use the current guides and status output for today's behavior.

historical excerpt · alpha.41

$ ak status
  ✓ versions    ruflo 3.34.0 (latest)
  ✓             agentic-qe 3.13.10 (latest)
  ✓             @openai/codex 0.147.0 (latest)
  ✓             opencode-ai 1.18.15 (latest)
  ✓ ruvnet-brain release v4.0.28 (latest)
  ✓ self        kit 4.0.0-alpha.41 (latest)
  ✓ natives     native better-sqlite3 in 1 agentdb location(s)
  ✓             ruflo memory runtime native (memory, cli)
  ✓ memory      native-agentdb active writer: 2253 active entries
  ✓ security    @claude-flow/security + aidefence present (defend functional)
  ✓ learning    1337 patterns learned, 1400 trajectories (this project)
  ✓ aqe         agentic-qe initialized here; RVF store healthy
  ✓ agentdb     agentdb 3.0.0-alpha.17 (coherent with ruflo)
  ✓ mcp         claude-flow registered (user scope), all families allowed
  ✓ hosts       claude 2.1.226 (external — self-managed)
  ✓             claude auth: oauth (subscription, $0)
  ✓             codex 0.147.0 (npm) · oauth (subscription, $0)
  ✓             opencode 1.18.15 (npm) · oauth (subscription, $0)
  ⚠ providers   provider config drifted (want claude+codex+opencode)
                → sync re-applies provider env + aqe router
  ⚠ routing     12 activities → 12 agent overrides — llm-config.json out of sync
                → sync re-applies agentOverrides
  ✓ daemons     2 running (one per active project is expected)
  ✓ blocks      CLAUDE.md managed blocks in sync (9 in registry)
  ✓ statusline  activation footer present and current
  ✓ qe-court    qe-court panel valid (vendor-diverse, jury independent of writer)

Abridged only by removing a few repeated sub-rows for width — every line shown is verbatim. The full output runs 38 lines and covers 23 subsystems.

The honesty mechanisms — how "proven" is built in

🧾

Every guard cites its incident

Each protection traces to a filed upstream issue, with the investigative history archived in docs/archive/. No superstition-driven code.

🪧

Bounded configuration ownership

Guidance lands between BEGIN/END markers in ~/.claude/CLAUDE.md (and Codex's AGENTS.md) — merged within owned spans. Project initialization and legacy whole-file provider teardown have separate limits; review the setup and provider guides.

🔍

Plans before mutations

Use the documented preview mode before authorizing changes. Some reads also refresh caches; a preview is not a guarantee that every upstream side effect is known.

📉

Regressions get remembered

Every sync appends a health snapshot; status flags backsliding — learning shrank, native slots dropped — instead of letting it pass silently.

Under the hoodPlain Node ≥ 22 ESM with zero runtime dependencies (SQLite embedded), one bin entry, and modules under src/. CI runs the suite on three OSes × Node 22/24/26; a nightly job installs the latest live upstream packages and re-proves the kit against them — so upstream drift is caught the day it ships, not the day it bites you. There's even a monthly dev-container build check.

PANEL 04Who it's for

Two chairs at the same workbench

The kit was built by and for agentic engineers — people composing multi-agent systems who need their substrate to be provably on. But its "one command, self-healing" shape makes it just as useful if you'd rather never think about any of this. Both chairs are legitimate.

Chair one

The agentic engineer

Provable substrate. Memory, learning, and security verified against real CLIs — your agents stand on ground you can trust.
Multi-host routing. Claude for architecture and review, Codex for implementation and testing — per-activity, tunable, with cross-host escalation ladders.
Observability. The dashboard indexes your actual Claude/Codex/OpenCode transcripts: usage, limits, sessions, live agent activity.
Evidence discipline. Provider, model, and billing claims are labeled observed / configured / inferred / unknown — never conflated.

Chair two

The vibe coder

One command in, one command forever. ak setup once; from then on, "when in doubt, ak sync" is the entire mental model.
Self-healing you never see. Upgrades that would silently break memory or security get caught and repaired before you notice.
A dashboard instead of config archaeology. Open ak dashboard and see what's on — no spelunking through dotfiles.
Explicit spend controls. Background workers are local-only ($0) by default; anything token-spending is opt-in behind a budget.

The shared payoff: extra lift. Your AI-assisted sessions inherit persistent memory, grounded knowledge, quality gates, and honest status — without you maintaining any of it by hand.

PANEL 05Setup, dissected

What ak setup actually touches

One command, three concentric scopes. Knowing which is which is the whole trick to feeling safe: machine scope is global packages, user scope is your config files, project scope only triggers when you run it inside a git repo.

Once per machine

Global tools, built properly

Installs/updates ruflo, agentic-qe, and the pinned agentdb CLI globally — shepherding native SQLite builds past npm ≥ 11.17's allow-scripts gate (the usual silent-breakage culprit). Installs any enabled host CLI that's entirely absent.

npm i -g, healednatives load-testedhosts installed if absent

then your user-level config —

Once per user

Guidance, knowledge, and MCP

Merges managed guidance blocks into ~/.claude/CLAUDE.md (and ~/.codex/AGENTS.md on Codex machines), offers one-time MCP registration with a tool-family picker, installs the RuvNet Brain (~2 GB, prompted — skip with --no-ruvnet-brain), and deploys the token-audit skill.

managed blocksMCP pickerBrain (prompted)

and, if you're standing in a git repo —

Per project

The repo gets its instruments

A sanitized ruflo init, an absolute memory-path pin, a verified store→disk write, the statusline footer, and a background daemon with local-only ($0) workers. Fair warning, disclosed up front: project init runs ruflo init --full --force and can replace existing agent configuration — docs/SETUP.md spells out the contract, and --minimal skips project scope entirely.

memory pin + proofstatusline$0 daemon--minimal to skip

Flags worth knowing--yes accepts every prompt (containers, CI) · --codex / --opencode enable extra hosts · --primary-host codex flips who leads · --no-aqe / --no-security / --no-ruvnet-brain trim subsystems · and ak uninstall reverses the footprint cleanly.

PANEL 06The deeper features

Where it gets genuinely clever

Past the install-and-heal loop, three features do the heavy lifting for day-to-day work: multi-host execution, the honest statusline, and the local dashboard.

Feature file · 01

Hosts × providers — two axes, never confused

A host is which agent CLI drives the session (Claude Code, Codex, OpenCode). A provider is which LLM serves inference (Anthropic, OpenAI, OpenRouter, Ollama…). The kit keeps these axes independent — OpenRouter is a provider behind a host, not another host — and converges both from one config with API keys kept out of kit.json; native authentication stores have their own persistence rules.

Enable both frontier hosts and the kit seeds a per-activity routing policy — each kind of work goes to the host and model that suits it, and your edits survive every sync:

Activity

Leads

Why

architecture · design · review

claude

deep reasoning

implementation · testing

codex

fast iteration

security-scan (example)

opencode

explicit route only

Then ak run feature "add rate limiting" materializes a whole pipeline — architect → coder → tester → reviewer — across hosts, with per-worker escalation ladders and --dry-run printing the exact plan first. Templates: feature, security, refactor, packaging, release.

Feature file · 02

A statusline that refuses to flatter you

Projects set up by the kit get an append-only footer under ruflo's own status line. Segments reflect their documented presence and metric checks — so the line below summarizes those particular observations, not every capability or session:

🧠 SONA patterns/trajectories · 📈 route-RL metrics · 🛡 aidefence · 🧿 Brain KB · ⚙ daemons · 🎓 AQE stats

Codex gets a separate managed native field preset (ak x statusline codex native), kept converged by sync without rewriting the rest of your Codex config.

Feature file · 03

The dashboard — local evidence and guarded maintenance

One command opens a self-contained local web app on 127.0.0.1:7431, guarded by a per-session token, that offers explicit, guarded actions in System → Maintenance. Five areas: About (a plain-words directory of everything the kit installed, and why), Overview (what's installed, wired, and routed — plus machine-wide intelligence), Usage (scorecards, limits, and sessions indexed from your local Claude/Codex/OpenCode transcripts), Observability (live and historical agent activity on an interactive canvas, with masked transcript evidence), and System (what the stack occupies on your machine — storage, runtime, catalog, and a project census).

Left to right, every tab and what's behind it — the floor plan, not just the five headline rooms:

About

HostsEngine & memoryQuality · Safety · KnowledgeThe kitConfigured for youcaptured below ↓

Overview

Summary — ak status, warnings first Hosts & Routing Providers Runtime Intelligence — machine-wide SONA/route-RL/AQE rollup, any project

Usage

Score — the scorecard below Limits — plan ceiling, ADR-0010 Findings Prompts — quality intelligence, Matrix A Context — startup budget Hooks Models — lifecycle drift, captured below Sessions → Transcript

Observability

LiveHistory — sanitized, owner-only

System

Summary — footprint, disk denominator Advisory — reclaimable, never auto-deleted Sessions — largest first Storage — by category × host Runtime — live processes Projects — captured above Maintenance — Host alignment and friends

ak adminseparate app, :7432

OverviewReviewHumansActivityGaps — captured above

Orange tiles get a real capture below, not just a description — the rest keep the one-line summary above until they earn their own.

Starting with tile 1 — About, the orientation surface (ADR-0026), landing view intentionally excepted. This capture is genuinely current: real markup, real client render logic, real shipped directory data, fed a synthetic /api/status so every chip state — installed, needs attention, not working, and honestly unknown — has something to show:

127.0.0.1:7431 · #about/hosts

Dashboard About tab: a directory of installed components — Claude Code, Codex, OpenCode as hosts, then ruflo, agent-browser, agentdb, deja-vu under Engine and memory — each card carrying a live installed/needs-attention/not-working chip.

The captures below are historical illustrations from the alpha.41-era page, not current UI or release evidence. Current behavior is documented in docs/DASHBOARD.md. First, Overview: the same subsystems as ak status, with the two warnings front and center and what sync would do about each:

127.0.0.1:7431 · #overview/summary · token-guarded

ak dashboard Overview area: System overview showing 2 warnings and 21 nominal subsystems, with providers and routing warning cards that each state the exact sync remediation, above a grid of green subsystem chips.

The Usage area turns your local transcripts into a scorecard — sessions, token volume, API-equivalent cost (clearly labeled list-price equivalent, not what a subscription bills), split by host, with a cost-per-day chart and a when-you-work heatmap:

127.0.0.1:7431 · #usage/score

ak dashboard Usage scorecard: 769 sessions, 17.2 billion tokens, 11,044 dollars API-equivalent, 128 engaged hours, 96.8 percent cache read rate, a cost-per-day bar chart, per-host cards for claude, codex and opencode, and a weekly work heatmap.

And Observability, watching live agent activity. This capture is pleasingly recursive: the session it's following is the Claude Code session that was writing this very page:

127.0.0.1:7431 · #observability/live

ak dashboard Observability Live view: one active session in the agentic-kit project, an execution map canvas showing a Claude Code coordinator node marked Process active just now, and a session stream panel awaiting selection.

A maintainer sibling, ak admin on :7432, tracks the project's own telemetry — repo traffic, npm momentum, CI state — with the same token discipline and zero external fetches from the page itself. Notice the tone: tiles say what they count and what they can't ("ak ships no opt-in counter — an honest gap, not a zero"):

127.0.0.1:7432 · ak admin · maintainer-only

ak admin panel: How many people section with tiles for 93 unique repo visitors, 3 contributors, 0 watching, and a deliberately blank opted-in installs tile explaining ak ships no telemetry, plus momentum sparklines for visitors, cloners and npm downloads.

The System tab's Projects view got sharper too: a worktree now nests under the repository it shares instead of masquerading as a separate installation — ampel and ampel-feature share one Git identity, so their language icons and skill counts group where they actually belong. Unlike the alpha.41 captures above, this one is genuinely current: real dashboard markup, styles, and client code, rendered today against the same fixture data its own Playwright regression test drives:

127.0.0.1:7431 · #inventory/project · repository grouping

Dashboard Projects view: the ampel repository and its ampel-feature worktree grouped under one heading with five language icons, versus five other single-language projects listed separately under Other projects.

And Usage's Models view — Model Lifecycle Intelligence, otherwise absent from this whole page until now. It separates configured from observed from catalogue-available, and when a routed model is being retired upstream, it says so with the exact fix:

127.0.0.1:7431 · #usage/models

Dashboard Usage → Models view: a route-needs-attention alert for GPT-5.4 retiring in favor of gpt-5.6-terra with the exact ak models plan fix command, plus an observed-usage table and a configured-routes table with live provider pricing.

Also genuinely current, same technique: real markup and client code, fed the exact JSON a real dashboard server emits for a hand-built model snapshot — not the mock's numbers, the pipeline's.

Feature file · 04

Host alignment — a retirement OpenAI announced that some configs never got the memo about

OpenAI retired the standalone codex mcp-server transport. A registration made under it doesn't un-register itself, though — it can keep sitting in ~/.claude.json or a project's .mcp.json, at user or project scope, while ak sync reports convergence anyway. ak host align audits both scopes (--all-projects adds a bounded census across every project it knows about) and previews the exact, scoped fix before touching anything; --apply asks for confirmation, then removes only that one registration, writes a recovery backup beside the file it edited, and remembers the exact recipe for next time.

The same repair now lives in the Maintenance dashboard too, under More views → Host alignment, filterable by User or Project. Opening a finding shows the same exact-registration preview and a Realign action — reversible only through its recovery backup, since automatic dashboard Undo doesn't cover this recipe yet, and that gap is disclosed rather than hidden. Ruflo's dual-mode execution and AQE's native provider routing are explicitly preserved; ambiguous or hand-edited configurations stay review items instead of getting an unsafe auto-apply. Full mechanism and upstream sourcing: ADR-0051 (docs/adr/0051-supported-peer-delegation-and-host-realignment.md).

127.0.0.1:7431 · #inventory/user · Host alignment

Maintenance dashboard Host alignment view, User scope selected, showing one repairable finding for a retired Claude host registration with its inspector open and a Repair registration action.

Not a historical capture — this is the dashboard's real markup, styles, and client code, rendered against the same synthetic fixture its own regression test drives. The row shown is a stale Claude registration one click from an exact, backed-up repair.

FIELD TESTTry it in the next ten minutes

Three ways in — pick your risk appetite

Path A · The real thing

Install it on your machine

The package declares Node ≥ 22 and requires npm. Use a maintained Node patch release with node:sqlite support. Setup can install missing enabled host CLIs; inference authentication is separate.

Choose ifYou're ready to actually run with it, on real projects.

Path B · Zero footprint

A Codespace / dev container

Open the repo in GitHub Codespaces and pick the "try the published release" configuration — the kit installs into a container with a sandbox repo; container resources and any configured shared mounts remain explicit boundaries.

Choose ifYou want to poke at it before installing anything locally.

Path C · Clean-room

The docker first-use env

cd docker && docker compose up --build ak replays a brand-new user's complete first run — install, setup, dashboard — with separate integration directories and a deliberate artifacts bind mount.

Choose ifYou like watching a full first-install prove itself end to end.

# Path A, in full — this is genuinely the whole thing:
npm install -g @pacphi/agentic-kit@next   # alpha channel until 4.0.0 GA
ak setup       # machine + user + (inside a repo) project — prompts disclosed
ak status      # see the proof: every subsystem, ✓/⚠/✗
ak dashboard   # and here's your stack, in a browser

From then on, the entire maintenance story is one habit: when in doubt, ak sync.

FIELD NOTESThe questions everyone asks

Straight answers

Do I need to install ruflo or agentic-qe myself first?

No — and that's the point. agentic-kit is the only package you install by hand. ak setup installs ruflo, agentic-qe, and friends globally for you, builds their natives properly, then heals and proves them. (If you already have them installed, setup detects and reuses them.)

Will it clobber my existing config?

Managed content lands inside clearly-marked BEGIN/END blocks, merged backup-first; ownership handling depends on the surface. Exact-value teardown preserves edited keys on supported paths, while legacy provider-router undo can restore a whole backup file. Review the setup and provider guides before teardown. The one loud exception: project setup runs ruflo init --full --force, which can replace existing agent configuration — it's disclosed up front, documented in docs/SETUP.md, and skippable with --minimal.

I only use Claude Code. Is the multi-host stuff going to get in my way?

No. The default is claude-only, zero change — nothing is written for hosts you haven't enabled, and no routing policy is seeded for claude-only projects. Codex and OpenCode are strictly opt-in (ak setup --codex, ak host pick), and reversible (ak host off).

Does anything phone home or spend tokens without asking?

The dashboard is offline-first and localhost-only with a per-session token; background daemons run local-only ($0) workers by default, with token-spending AI workers opt-in behind a machine-wide budget. The browser stays same-origin, but dashboard status checks can query version services and persist caches. Explicit scans/catalog refreshes can also contact their documented sources. ak admin deliberately proxies GitHub/npm server-side without sending its credential to the page.

And if I want out?

ak uninstall removes the kit's footprint cleanly — project memory and transcripts are retained by default — and --purge additionally offers to remove the global packages it installed. Consult ak uninstall --help and use --dry-run to inspect the selected teardown scope.