https://github.com/archgate/cli
Enforce Architecture Decision Records as executable rules — for both humans and AI agents
https://github.com/archgate/cli
adr architecture bun claude-code cli cursor npm
Last synced: about 1 month ago
JSON representation
Enforce Architecture Decision Records as executable rules — for both humans and AI agents
- Host: GitHub
- URL: https://github.com/archgate/cli
- Owner: archgate
- License: apache-2.0
- Created: 2026-02-23T16:40:08.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-30T14:02:25.000Z (2 months ago)
- Last Synced: 2026-03-30T15:25:13.407Z (2 months ago)
- Topics: adr, architecture, bun, claude-code, cli, cursor, npm
- Language: TypeScript
- Homepage: https://cli.archgate.dev/
- Size: 1.21 MB
- Stars: 21
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Archgate
**Enforce Architecture Decision Records as executable rules — for both humans and AI agents.**
[](LICENSE.md)
[](https://github.com/archgate/cli/actions/workflows/release.yml)
[](https://cli.archgate.dev)
[](https://www.bestpractices.dev/projects/12659)
---
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):
```bash
# 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):
```bash
# 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:
```bash
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](https://cli.archgate.dev/getting-started/installation/) for more options.
## Quick start
```bash
# 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](https://cli.archgate.dev/guides/writing-rules/) for examples and the full [rule API reference](https://cli.archgate.dev/reference/rule-api/).
## 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**](https://cli.archgate.dev/guides/claude-code-plugin/) and [**Cursor**](https://cli.archgate.dev/guides/cursor-integration/).
>
> ```bash
> archgate login # one-time GitHub auth
> archgate init # installs the plugin automatically
> ```
>
> **[Get started with plugins](https://cli.archgate.dev/guides/claude-code-plugin/)** — the CLI works fully without them, but plugins close the loop between decisions and code.
## Documentation
Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)** — including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI reference.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and workflow.
## License
[Apache-2.0](LICENSE.md)