agentic-kit MCP server

🧰 @pacphi/agentic-kit

One npm package that installs, repairs, and checks ruflo (claude-flow), its compatible browser executor, and 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.

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 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-compatible tool) — a "try the published release" configuration installs ak into a disposable container for you. See 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.
• 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.

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.

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 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/.

The commands

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.

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 for the preview/authorize/apply/verify/undo journey and current platform limits.

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 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; provider and recovery limits: Maintenance runbook. 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.
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.
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.

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 for fields, ownership, rollback, and the current parity boundary.