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 — proves the whole stack actually works instead of assuming it does.
+ +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:
+ + + +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.
+ +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.
+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:
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.
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.
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.
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.
+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.
The workbench — every daily-driver verb
+sync would do about it.feature, security, refactor…) across hosts.--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. And every mutating command takes --dry-run and prints its plan, with reasons, before touching anything.
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.
+ +ak statusTruth, 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.
ak syncOne verb heals everything
+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.
+ak x verifyEvidence, 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 is an unedited capture from the maintainer's own machine while writing this page. Note the two ⚠ rows: honest drift, each naming exactly what sync would do about it. A status that's all green all the time isn't honest — this one earns its checkmarks.
$ 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.
Managed blocks, never clobbering
Guidance lands between BEGIN/END markers in ~/.claude/CLAUDE.md (and Codex's AGENTS.md) — merged backup-first; your own content is never touched.
Plans before mutations
Every mutating command takes --dry-run and prints its plan with reasons. You always see the impact before anything changes.
Regressions get remembered
Every sync appends a health snapshot; status flags backsliding — learning shrank, native slots dropped — instead of letting it pass silently.
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.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.
+ +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. +
The vibe coder
+-
+
- One command in, one command forever.
ak setuponce; 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 dashboardand see what's on — no spelunking through dotfiles.
+ - No spend surprises. 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.
+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.
+ +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.
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.
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.
--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.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.
+ +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 in the environment, never written to disk.
+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:
+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.
A statusline that refuses to flatter you
+Projects set up by the kit get an append-only footer under ruflo's own status line. Every segment appears only when genuinely active — so the line below is a health certificate, not decoration:
+Codex gets a managed native equivalent (ak x statusline codex native), kept converged by sync without rewriting the rest of your Codex config.
The dashboard — observation only, localhost only
+One command opens a self-contained local web app on 127.0.0.1:7431, guarded by a per-session token, that never mutates anything. 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).
Every capture below is real — taken from the maintainer's machine while this page was being written. First, Overview: the same subsystems as ak status, with the two warnings front and center and what sync would do about each:
+ 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:
+
+ 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:
+
+ 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"):
+ Three ways in — pick your risk appetite
+ +Install it on your machine
+Node ≥ 22, npm, and the claude CLI are the whole prerequisite list. Two commands and the loop is yours.
A Codespace / dev container
+Open the repo in GitHub Codespaces and pick the "try the published release" configuration — the kit installs into a disposable container with a sandbox repo, and your machine never knows.
+The docker first-use env
+cd docker && docker compose up --build ak replays a brand-new user's complete first run — install, setup, dashboard — in total isolation from your host tooling.
# 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.
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; everything the kit writes is ownership-recorded so ak host off and ak uninstall can strip exactly its own footprint and nothing else. 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 one deliberate-egress surface, ak admin, proxies GitHub/npm server-side and never exposes your credential to the page.
And if I want out?
+ak uninstall removes the kit's footprint cleanly — project data is never touched — and --purge additionally offers to remove the global packages it installed. --dry-run shows the exact plan first, like every other mutating command.