ACKit — AgentContextKit
npx --yes @cynrath/agent-context-kit@latest readiness
- Detect conflicting agent instructions (
AGENTS.md / CLAUDE.md / provider scopes)
- Find unsafe repository context (secrets, connection strings, absolute paths)
- Measure repository readiness across instructions, security and context efficiency
- Reduce wasted agent context (duplicate guidance, oversized files, low-value includes)
- Enforce evidence-backed task completion with independent verification
- Generate provider-aware context packs (Codex / Claude / Copilot / Gemini / generic)
✨ Demo (30 seconds)
# 1 — onboard (dry-run, writes nothing)
$ ackit init --dry-run
✔ plan: AGENTS.md shim + 4 built-in skills
# 2 — score readiness (explainable, no LLM)
$ ackit readiness
Readiness 88/100 ██████████████████░░ (threshold 80 — pass)
Instructions 90/100
Security 90/100
Context Efficiency 70/100
# 3 — graph + optimize
$ ackit instructions --explain
codex/AGENTS.md → claude/CLAUDE.md (provenance: frontmatter applyTo)
$ ackit optimize --explain --json | jq .suggestions[0].tokenWasteEstimate
42
# 4 — provider-aware pack & dashboard
$ ackit pack --profile codex --max-tokens 50000 | head -5
# ACKit Context Pack — 12 files, 34210 tokens
$ ackit dashboard --port 0 --open # localhost-only, CSP, live polling
→ http://127.0.0.1:54321
🔐 Trust flow (60 seconds)
$ ackit task complete TASK-0007
completion gate blocked: MISSING_VERIFIER_VERDICT: profile 'standard'
requires an independent verdict (run 'ackit verification bundle' + record)
$ ackit evidence verify TASK-0007 --criterion AC-001 --type test --ref "pnpm vitest run (green)"
$ ackit verification bundle TASK-0007 --format json --out .ackit/reviews/bundle.json
$ ackit verification record TASK-0007 --verdict .ackit/reviews/verdict.yaml --bundle .ackit/reviews/bundle.json
TASK-0007: verdict VR-0001 registered (PASS)
$ ackit status TASK-0007
blockers: (none — completion eligible)
- verdict VR-0001 (PASS): fresh; independent
$ ackit task complete TASK-0007
TASK-0007: completed
$ ackit checkpoint export TASK-0007 --format json --out .ackit/reviews/handoff.json
# ... second process, zero shared memory ...
$ ackit checkpoint import .ackit/reviews/handoff.json
TASK-0007: handoff CP-0001 fresh (bundle 9f2c…); resume context renders
Stale state blocks with VERDICT-STATE-STALE (naming what changed);
a fresh bundle + verdict restores eligibility. The full flow runs as a
test (tests/e2e/trust-flow-demo.test.ts) and is walked through in
docs/guides/demo-trust-flow.md —
offline, no API key.
🧭 Table of Contents
❓ Why
| Before | With ACKit |
|---|
| Convention-based — nothing is verified | Deterministic local analysis with stable JSON/SARIF contracts |
| Cloud-coupled — code leaves the machine | Offline-by-construction — zero network in product code |
| Secrets leak into prompts/logs | Redacted at construction — evidence never contains plaintext secrets |
One AGENTS.md for all providers | Provider-aware — Codex/Claude/Copilot/Gemini/generic, includeScopes/applyTo |
| “It worked on my machine” | Machine-checkable gates — ackit scan --ci, ackit readiness --strict |
This repository dogfoods itself: it was built by following the same docs/tasks task system it ships.
What ACKit is not: an autonomous coding agent, a model runtime, a browser
automation framework, an agent router, or a cloud orchestration service. ACKit
is the deterministic, offline-first engineering layer those agents share —
repository context, explicit intent, structured tasks, plan discipline,
evidence-backed completion, resumability, independent verification, policy
enforcement, drift detection, and provider interoperability. Model execution
and autonomous coding stay with your chosen agent (Codex, Claude Code,
OpenCode, Copilot, Gemini, Cursor, Cline, any MCP-capable agent).
🎁 Features at a glance
📦 Install
Requires Node ≥ 22.
# global (recommended)
npm install --global @cynrath/agent-context-kit
ackit --version # 0.5.4
# one-shot, pinned
npx --yes @cynrath/[email protected] --version
npx --yes @cynrath/[email protected] --help
# from source
pnpm install --frozen-lockfile && pnpm build
node dist/cli/index.js --help
🚀 Quickstart
ackit init --dry-run # plan shims + 4 built-in skills (writes nothing)
ackit scan --ci # gate: exit 1 at/over threshold (medium)
ackit readiness # 0–100, N/A renormalization, --strict/--fail-below
ackit instructions --explain # graph v2 with provenance
ackit optimize --explain # 8-class advisor, waste estimates
ackit pack --profile codex --max-tokens 50000 # provider-aware, budgeted
ackit diagnostics --json | jq .profile
ackit dashboard --port 0 --open # localhost-only
Every command supports --json and --help. Full tour → docs/guides/getting-started.md
🖥️ CLI Overview
Details: docs/reference/cli.md · Exit codes: docs/reference/exit-codes.md · Schemas: docs/reference/schemas.md
0 ok · 1 threshold/new-findings · 2 usage/config · 3 environment · 4 security boundary · 5 internal. See docs/reference/exit-codes.md.
⚙️ Configuration
Optional root ackit.yml (strict, additive — v1 still valid):
schemaVersion: 1
scan:
severityThreshold: medium
limits:
maxFiles: 50000
context:
maxTokens: 80000
policy:
extends: []
rulePacks: [] # declarative packs (local or node_modules)
readiness:
weights: { instructions: 25, security: 25, contextEfficiency: 20, taskHygiene: 10, skills: 10, policy: 10 }
strictThreshold: 80
profile: codex # codex|claude|copilot|gemini|generic
profiles:
extend: [] # repo-relative custom profiles
Validate: ackit config check · Schema: schemas/ackit.schema.json · Reference: docs/reference/config.md
🏗️ Architecture
flowchart LR
A[Repository] --> B[Filesystem Engine<br/>realpath containment]
B --> C[Instruction Graph v2<br/>scope → precedence]
B --> D[Scanner<br/>redacted findings]
B --> E[Context Pack<br/>budgeted ranking]
C --> F[Readiness 0–100<br/>6 categories]
D --> F
E --> F
C --> G[Optimize v2<br/>8-class + waste]
D --> G
F --> H{CLI / SDK / MCP / Action / Dashboard / VS Code}
G --> H
- Single door to filesystem — one containment engine
- Redaction before reporters — findings constructed already-safe
- Determinism — same repo+config → byte-identical JSON/fingerprints
- Offline-by-construction — no network in product code
Trust chain (v0.5)
flowchart LR
T[Task / Intent / Workflow] --> E[Evidence]
E --> V[Bound Verification<br/>bundle v2 + verdict v2]
V --> I[Verdict Independence + Freshness<br/>reviewed bundle + replay/stale refusal]
I --> S[Canonical Status<br/>ackit.status.v1, read-only]
S --> H[Portable Handoff v2<br/>export / import / resume]
H --> P[CLI / SDK / MCP / Action / VS Code]
Task/intent/workflow → evidence → bound verification → verdict
independence/freshness → status → handoff/resume →
CLI/SDK/MCP/Action/VS Code. Details: docs/guides/demo-trust-flow.md ·
docs/concepts/evidence-verification.md ·
docs/concepts/checkpoints.md.
More: docs/architecture/overview.md
🤖 GitHub Action
Official Cynrath/[email protected] (SHA-pinned for high-assurance):
permissions:
contents: read
jobs:
ackit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@f548e57e544e1ff5a4c46bf1e1b8685f8e4a348a
- uses: Cynrath/[email protected]
with:
command: scan
args: "--json"
fail-threshold: high
upload-sarif: "false"
# optional: upload SARIF via github/codeql-action/upload-sarif@v3
# optional: upload findings via actions/upload-artifact@v4
Inputs command/args/fail-threshold/upload-sarif, outputs findings-json/sarif-path, annotations/SARIF 2.1.0/job summary, least-privilege. Shareable local output: ackit scan --format markdown (copyable summary) or --format sarif for code scanning. Guide: docs/guides/ci.md · Action: action.yml
👀 Watch / Dashboard & Diagnostics
ackit scan --watch # debounced 400ms, incremental cache, SIGINT → exit 0
ackit dashboard --port 0 --open # localhost-only, CSP, XSS-escaped, live polling
ackit report serve ./report.html --port 0
ackit diagnostics --json | jq .profile
ackit diagnostics bundle --out ./ackit-diag.zip --redact-check
Guides: docs/guides/watch-dashboard.md · Reference: docs/reference/diagnostics.md
🔌 SDK
import { scanRepository, scoreRepository, buildInstructionGraph } from "@cynrath/agent-context-kit";
const result = await scanRepository({ canonicalPath: process.cwd() });
console.log(result.findings.length);
// cancellable
const ac = new AbortController();
setTimeout(() => ac.abort(), 10);
await scanRepository({ canonicalPath: "." }, { signal: ac.signal });
ESM-only, sideEffects:false, AbortSignal cancellable, no process.exit. Reference: docs/reference/sdk.md · Example: examples/sdk-consumer.mjs
🧩 VS Code
ACKit is available on the VS Code Marketplace as
Cynrath.ackit-vscode.
From source:
pnpm --filter vscode build
vsce package # → ackit-vscode-0.5.4.vsix
Features: readiness tree, Problems ACKITxxx, graph “instructions for current file”, tasks/policy/optimize, palette Refresh/Show Graph/Optimize/Diagnostics, file watcher debounced, no telemetry.
Guide: docs/guides/vscode.md
📚 Docs
Context7 / Docs7: Maintained indexing settings live in context7.json; Docs7 navigation uses docs/docs.json. See the Context7, Docs7 and verification guide for owner claiming, badge requests and optional Docs7 Free hosting. Existing documentation hosting remains unchanged.
🔗 Ecosystem
Community integration for ACKit and GitHub Spec Kit: Spec Kit bridge
(@cynrath/ackit-spec-kit-bridge) connects
Spec Kit's intent-driven development artifacts to ACKit's deterministic repository context, task
lifecycle, evidence, verification, and completion gates. Offline-first, no telemetry.
🔌 MCP Setup
{ "mcpServers": { "ackit": { "command": "ackit", "args": ["mcp", "serve"] } } }
Reference: docs/reference/mcp.md
🛠️ Requirements & Development
Requirements: Node ≥ 22 · pnpm 11 (development) · git optional (incremental features)
Development:
pnpm install --frozen-lockfile
pnpm lint && pnpm format:check && pnpm typecheck
pnpm build && pnpm test && pnpm smoke:cli
pnpm run smoke:package # pack → temp install → CLI smoke
See CONTRIBUTING.md for the docs-first workflow.
🔖 Versioning
Development: 0.5.4 on master · Latest stable: 0.5.4 · Changelog · Releases · latest → 0.5.4 via OIDC Trusted Publishing with provenance. Stable pointer: release-state.json. Legacy .NET/NuGet 1.0.0-rc.1 at 258918b is frozen.
📄 License
MIT — LICENSE
