One architecture config. One check. One coach.
Your AI writes most of the code. ArkGate keeps that work inside an architecture you can trust — and makes sure a “green” check means something real.
ArkGate 4.6.6 is current (this train). 4.6.5 remains npm
latestuntil publish. A tree is adopted only with a required GitHub status runningarkgate-check --strict-merge, or.ark/adoption-stance.jsonstance: "advisory-only". Doctor is compact (--doctor --allfor Details). 4.6.6 notes · 4.6.5 · Docs hub · Product voice
| You are… | Go here |
|---|---|
| Anyone (ship with AI, minimal jargon) | Use ArkGate |
| Developer (hosts, CI, config, brownfield) | Develop with ArkGate |
| Contributor (improve this library) | CONTRIBUTING |
Full map: docs/README.md
npm install -D arkgate typescript
npx arkgate start # preview files + commands
npx arkgate start --apply # compact contract + host router + CI plan
npx arkgate-check --doctor # control plane: status light + primary next action
npx arkgate-check --doctor --all # encyclopedia (Details)
That is the product. Doctor is the control plane — when stuck, do primary next action #1. JSON still carries improvement compass and coach (not a score). Compact human output does not.
start → doctor (+ compass) → /ark-adopt (session 0) → day-to-day /ark-place
↘ /ark-explore then /ark-autopilot when leftover design remains
Teams: keep the constitution out of product PRs. Local gate
ark-check --changed --base origin/dev. Steward law PRs use --contract-session.
Aliases ark / ark-check / ark-mcp still work. npm / pnpm / yarn. No install lifecycle scripts.
A machine-readable architecture file (ark.config.json) plus enforcement:
| When | Tool |
|---|---|
| While the AI writes | Pre-write block on supported hosts; warning only elsewhere |
| Before merge | arkgate-check as a required CI status |
| Plane | What it guards | Config |
|---|---|---|
| Layers (always) | Who may import whom — imports, placement, purity, isolation | ark.config.json layers + rules |
| ArkRules (opt-in; structure rules inside a layer) | Habits inside a layer — structure sensors + domain invariants as data | arkRules → arkrules/<Layer>.json |
Absence of ArkRules changes no inter-layer verdict. Label residual [Layer] vs [ArkRules].
Details: configuration · use path.
Not a web framework, ORM, or job runner. Optional experimental runtime is separate and not required for the gate.
Name note: npm package arkgate — not affiliated with the separate Archgate CLI project.
ArkGate is overkill for small trees with no AI agents and no multi-layer boundaries, for
single-developer hobby CRUDs under no integration pressure, and for teams that will not maintain
ark.config.json or a required CI status running arkgate-check --strict-merge. In those
cases stay with a boundary linter alone (see Why not only ESLint / Nx / cruiser?).
Anyone path: docs/use.md — When not to adopt. Limits of a green
check: 4.3.0 — What ArkGate is / isn't.
| Light | Means | Your move |
|---|---|---|
| Suggest | Thin / new tree | Finish start → doctor |
| Adapt | Not fully protected | Doctor action #1 |
| Enforce | Honest import edges, and no new UI business-rule files vs merge-base | Keep write path + CI |
| Enforce · design-weak | Edges clean; design residual remains | Shape residual — not “done” |
Details: docs/use.md.
| Host | Local write boundary | MCP validation | CI / merge path | Repair payload |
|---|---|---|---|---|
| Claude Code | Hard block for listed ops (PreToolUse Write / Edit / MultiEdit) when installed + trusted | Advisory; the agent must call it | Required GitHub status context running arkgate-check --strict-merge (alias ark-check) | Emitted on hook deny; host must re-inject (hard path when installed + trusted) |
| Grok Build | Hard block for listed ops (PreToolUse write / search_replace (plus aliases)) when installed + trusted | Advisory; the agent must call it | Required GitHub status context running arkgate-check --strict-merge (alias ark-check) | Emitted on hook deny; host must re-inject (hard path when installed + trusted) |
| Google Antigravity | Hard block for listed ops (PreToolUse write_to_file / replace_file_content / multi_replace_file_content) when installed + trusted | Advisory; the agent must call it | Required GitHub status context running arkgate-check --strict-merge (alias ark-check) | Emitted on hook deny; host must re-inject (hard path when installed + trusted) |
| Cursor | Hard block for listed ops (preToolUse Write / StrReplace) when installed + trusted | Advisory; the agent must call it | Required GitHub status context running arkgate-check --strict-merge (alias ark-check) | Envelope may emit (--hook-repair); reinjection not guaranteed |
| OpenAI Codex | Hard block for listed ops (PreToolUse apply_patch in Codex CLI and local ChatGPT Desktop/App Server) when installed + trusted | Advisory; the agent must call it | Required GitHub status context running arkgate-check --strict-merge (alias ark-check) | Envelope may emit (--hook-repair); reinjection not guaranteed |
| OpenCode | Advisory / best-effort at write (MCP + optional plugin; not a hard boundary) | Advisory; the agent must call it | Required GitHub status context running arkgate-check --strict-merge (alias ark-check) | No hard-boundary payload |
Read the CI column: for every host, the repository-wide hard guarantee is a required
GitHub status context that runs the CLI — not “CI file present,” and not the CLI binary name alone.
Codex hard write covers only a complete local apply_patch; Cursor covers only listed
preToolUse ops. In both cases the project hook must be installed + trusted, while shell/direct
filesystem writes, hosted or specialized opt-out paths, and human edits still rely on CI.
This table describes the supported profile after its files are installed and the host loads/trusts them. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair envelopes may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run arkgate-check --doctor (or ark-check --doctor) for the evidence actually detected in the current repository.
The split above is a deliberate trade-off, not a gap. ArkGate validates at the earliest boundary
each host offers and enforces at the earliest boundary a repository can make non-bypassable: the
required merge status. Hard hooks (Claude Code, Grok Build, Google Antigravity, Cursor, and
Codex’s complete local apply_patch) deny their listed write operations at write time; advisory
surfaces (MCP, rules, OpenCode plugins) coach the agent while it works. But any local boundary can
be routed around — another tool, a hosted/specialized path, a direct filesystem write, or a human
edit — so the only guarantee ArkGate claims for every path is the
arkgate-check --strict-merge check, and only when the repository makes that status required.
Local checks optimize feedback speed; the merge gate owns correctness.
A useful consequence: the contract doubles as a pressure sensor. Recurring violations or baseline
exceptions concentrated on one layer edge are evidence that the current design stopped fitting the
code — a reason to reshape the contract deliberately (start with /ark-explore), never to weaken
the gate.
Setup per host: docs/ai-gates.md · Develop path: docs/develop.md
For authoritative MCP contract evidence, call ark_identity with the exact project root, then
call ark_manifest with that root plus the returned project id. A contained descendant requires
the matching id. The legacy ark://manifest resource remains compatibility-only and always
unverified/non-authoritative because standard resources/read cannot portably carry that
expectation.
| ArkGate | Typical boundary linter | |
|---|---|---|
| CI import rules | ✅ | ✅ |
| Hard-block AI writes on supported hosts | ✅ | ❌ |
Project-bound contract agents can read (ark_manifest) | ✅ | ❌ |
| Placement + preflight for multi-file changes | ✅ | ❌ |
| Honest governed % + dual plan (edges vs shape) | ✅ | ❌ |
| Opt-in intra-layer ArkRules (structure + invariants) | ✅ | ❌ |
| Incomplete analysis cannot look green | ✅ | varies |
npx arkgate start --apply
npx arkgate status --json # session/project snapshot (identity, activation, last check)
npx arkgate-check --doctor
npx arkgate-check --plan
npx arkgate-check --coverage
npx arkgate-check --strict-merge # CI / required status
npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
# optional: refresh shared home skills (Claude/Grok/Codex; never downgrades)
# npx arkgate-check --install-agent-gates --skills-only --agent-homes --force
# optional: same 13 skills via Agent Skills ecosystem (no new names)
# npx skills add ./node_modules/arkgate/templates/agent-skills
More: docs/develop.md · skills install: docs/agent-guide.md · enthusiast track: docs/enthusiast/
Gates need no app runtime. The experimental @arkgate/runtime companion is separate and is not a production-readiness claim.
Default stores (InMemoryEventBuffer, InMemoryAuditStore, InMemoryReadModelStore,
InMemoryWorkflowStore) are reference in-memory only — fine for tests and demos; they
do not survive restarts and are not production durability. Implement the store interfaces
for real systems. Details: docs/production-hardening.md.
git clone https://github.com/pedroknigge/arkgate
cd arkgate && npm ci && npm run build
npm test && npm run check:architecture
Full guide: CONTRIBUTING.md · queue: ROADMAP.md
Website: arkgate.online · npm: arkgate
MCP: io.github.pedroknigge/arkgate
Node ≥ 18 · MIT
Ark doesn’t invent your product. It keeps AI-generated TypeScript inside an architecture you can trust — and tells you when it isn’t really enforcing anything yet.
FAQs
When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.
The npm package arkgate receives a total of 2,595 weekly downloads. As such, arkgate popularity was classified as popular.
We found that arkgate demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Research
/Security News
Ten malicious OpenAPI React Query Codegen versions were published to npm in the Mini Shai-Hulud attack, all with valid provenance.
Security News
Socket joins more than 100 technology, cybersecurity, and financial organizations calling for a global surge in cyber defense.
Product
Enterprise security teams can now detect malware, credential theft, suspicious network activity, and risky updates across Microsoft Edge extensions.