If the AI writes an illegal import, the write is rejected. The same check fails the pull request.
If the AI writes an illegal import, the write is rejected. The same check fails the pull request.
Not an API Gateway. Not a folder linter. If the check is not required on the PR, the rules file is just documentation.
One rules file. One check. One next step.
ArkGate 4.7.2 is prepared. npm
latestremains 4.7.1 until this patch is published. If the AI writes an illegal import, the write is rejected. Optional ArkRun extra on schema1.2. 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.7.2 notes · 4.7.1 · 4.7.0 · 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 config + host router + CI plan
npx arkgate-check --doctor # what's wrong, what to do first
npx arkgate-check --doctor --all # full details
That is the product. Stuck? Run --doctor and do action #1.
start → doctor → new files in the right folder
↘ leftover mess: map, then one small refactor
Keep the rules file out of product PRs. Local check:
ark-check --changed --base origin/dev. Changing the rules themselves uses --contract-session.
Aliases ark / ark-check / ark-mcp still work. npm / pnpm / yarn. No install lifecycle scripts.
Import rules for TypeScript, enforced twice: the editor hook rejects the write, and a
required CI check rejects the pull request. ark.config.json is the rules file those
checks read.
| When | Tool |
|---|---|
| While the AI writes | The write is rejected 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 |
| ArkRun (opt-in extra) | Kernel usage + complete declarations | arkRun on schema 1.2 |
Absence of ArkRules or ArkRun changes no inter-layer verdict. Label residual [Layer] vs [ArkRules].
Details: configuration · use path.
Not an API Gateway, a folder linter, a web framework, ORM, or job runner. Optional ArkRules and ArkRun extras are off unless you turn them on. In-memory stores are not production durability.
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. Without that
status the rules file is just documentation — 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 ArkRun companion (@arkgate/runtime) is separate
and is not a production-readiness claim. createStrictArkKernel is the factory: each call creates
an isolated instance (no process-wide singleton). Managed components declare uses / reactsTo /
raises / sends; getDependencyInformationPackage() is a JSON snapshot and never leaks factories.
requestGraph() slices that snapshot into process or technical graphs (nodeIds,
degreesOfSeparation, include/exclude query) with a Mermaid helper. send() is local /
localBlocking / broker (broker falls back to in-process local; ephemeral
defaults true; no cloud SDKs in the package). Opt-in startInspector() binds 127.0.0.1,
refuses NODE_ENV=production, and lazy-loads HTTP for JSON snapshots, SSE, and /graph. The kernel is
not bundled in the arkgate tarball.
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 rejects the illegal write — 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 1,616 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
Socket researchers found 18 Chrome extensions and one Edge extension delivering a wallet drainer, credential theft, and other malicious payloads.
Product
Create ClickUp tasks from Socket alerts, automate ticketing with custom rules, and keep alert and task status synchronized.
Product
Create and manage Asana tasks directly from Socket alerts, with manual task creation, automated ticketing rules, and two-way sync.