Archgate

Archgate turns your Architecture Decision Records into a governance layer that runs in CI, enforces rules in pre-commit hooks, and feeds live context to AI coding agents — so architectural decisions don't stay in documents, they stay in the code.

Write an ADR once. Enforce it everywhere.

How it works

Archgate has two layers:

1. ADRs as documents — markdown files with YAML frontmatter stored in .archgate/adrs/. Each ADR records a decision: what was decided, why, and what to do and not do.
2. ADRs as rules — each ADR can have a companion .rules.ts file that exports automated checks. Archgate runs these checks against your codebase and reports violations.

.archgate/
└── adrs/
    ├── ARCH-001-command-structure.md          # human-readable decision
    ├── ARCH-001-command-structure.rules.ts    # machine-executable checks
    ├── ARCH-002-error-handling.md
    └── ARCH-002-error-handling.rules.ts

When a rule is violated, archgate check reports the file, line, and which ADR was broken. Exit code 1 means violations — wire it into CI and it blocks merges automatically.

The CLI is free and open source. Writing ADRs, enforcing rules, running checks in CI, and wiring up pre-commit hooks all work without an account or subscription.

Installation

Standalone (no Node.js required):

# macOS / Linux
curl -fsSL https://cli.archgate.dev/install-unix | sh

# Windows (PowerShell)
irm https://cli.archgate.dev/install-windows | iex

# Windows (Git Bash / MSYS2)
curl -fsSL https://cli.archgate.dev/install-unix | sh

Via npm (or any Node.js package manager):

# npm
npm install -g archgate

# Bun
bun install -g archgate

# Yarn
yarn global add archgate

# pnpm
pnpm add -g archgate

You can also install as a dev dependency:

npm install -D archgate    # or: bun add -d archgate
npx archgate check         # run via package manager

Requirements: macOS (arm64), Linux (x86_64), or Windows (x86_64). See the installation guide for more options.

Quick start

# 1. Install
curl -fsSL https://cli.archgate.dev/install-unix | sh  # or: npm install -g archgate

# 2. Initialize governance in your project
cd my-project
archgate init

# 3. Edit the generated ADR to document a real decision
# .archgate/adrs/ARCH-001-*.md

# 4. Add a companion .rules.ts to enforce it automatically
# .archgate/adrs/ARCH-001-*.rules.ts

# 5. Run checks
archgate check

Writing rules

Each ADR can have a companion .rules.ts file that exports automated checks. See the writing rules guide for examples and the full rule API reference.

Supercharge with AI plugins

Make your AI agent architecture-aware. With the optional editor plugins, your AI coding agent reads ADRs before writing code, validates changes against your rules, and captures new architectural patterns back into ADRs — automatically.

Plugins are available for Claude Code and Cursor.

archgate login             # one-time GitHub auth
archgate init              # installs the plugin automatically

Get started with plugins — the CLI works fully without them, but plugins close the loop between decisions and code.

Documentation

Full documentation is available at cli.archgate.dev — including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI reference.

Contributing

See CONTRIBUTING.md for development setup and workflow.

License

Apache-2.0