Product
Socket for ClickUp Is Now Available
Create ClickUp tasks from Socket alerts, automate ticketing with custom rules, and keep alert and task status synchronized.
By Jeppe Hasseriis - Aug 26, 2026
New:Socket for Asana Is Now Available.Learn more →
ArkGate — Architecture Co-pilot for AI TypeScript
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.7.0 is on npm
latest. 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.0 notes · 4.6.7 · 4.6.6 · Docs hub · Product voice
Choose your path
| 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
Start in one minute
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.
What it is
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 |
Two planes (4.0)
| 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 a web framework, ORM, or job runner. Optional ArkRun extra and companion kernel (@arkgate/runtime) are separate and not required for the gate. In-memory stores are not production durability.
Name note: npm package arkgate — not affiliated with the separate Archgate CLI project.
When not to adopt
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.
Status lights (not settings)
| 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 enforcement support
| 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.
Why the hard guarantee lives at the merge gate
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.
Why not only ESLint / Nx / cruiser?
| 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 |
Common commands
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/
Optional ArkRun kernel
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.
Durability stance
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.
Documentation
Contribute to this library
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 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.
Package last updated on 25 Aug 2026
Related posts
Product
Socket for Asana Is Now Available
Create and manage Asana tasks directly from Socket alerts, with manual task creation, automated ticketing rules, and two-way sync.
By Jeppe Hasseriis - Aug 25, 2026
Security News
Open VSX Unblocks Extension IDs Used in Malware Campaign
Open VSX has removed three extension IDs from its malicious-extension list as the legitimate publishers they impersonated move to claim the names for themselves.
By Sarah Gooding - Aug 24, 2026