ArchGuard
Architectural guardrails for AI coding agents
Requires Node.js 18 or later
The Problem
Your AI agents write code that works but violates your architecture.
Without guardrails, AI coding agents make decisions that drift from your established patterns. ArchGuard extracts your architectural decisions and makes them available to every agent, every time.
Analyze
Extract architectural decisions from your codebase into structured, versioned knowledge.
Sync
Push decisions into CLAUDE.md, cursor rules, or any agent configuration file.
Review
AI agents query decisions in real-time via MCP, getting guidance before writing code.
By the Numbers
How It Works
Three commands. Full coverage.
archguard analyze
Point ArchGuard at your codebase. It reads your source files, identifies patterns, conventions, and architectural decisions, then structures them into versioned knowledge.
$ archguard analyze ./src
Scanning 43,000 lines across 312 files...
Found 133 architectural decisions
Extracted 345 evidence items
Linked decisions to source locations
Output: .archguard/decisions.jsonarchguard sync
Push extracted decisions into your agent configuration files. CLAUDE.md, .cursorrules, or any custom format. Your agents get architectural context before they write a single line.
$ archguard sync --target claude
Syncing 133 decisions to CLAUDE.md...
Added: API design conventions (12 rules)
Added: Database access patterns (8 rules)
Added: Error handling standards (15 rules)
Added: Testing requirements (11 rules)
CLAUDE.md updated with 133 decisionsarchguard serve
Start the MCP server for real-time guidance. AI agents query architectural decisions on demand, getting contextual answers before making implementation choices.
$ archguard serve --port 3100
MCP server running on localhost:3100
4 tools available:
- get_architectural_guidance
- list_decisions
- get_decision_detail
- search_evidenceMCP Tools
Real-time architectural guidance
Four MCP tools that give your AI agents instant access to your architectural decisions. No more guessing, no more violations.
get_architectural_guidance
The killer feature. Agents describe what they want to build, and get back relevant architectural decisions, patterns, and constraints specific to your codebase.
list_decisions
Browse all extracted architectural decisions with their categories, confidence levels, and linked evidence.
get_decision_detail
Deep dive into a specific decision. See the full rationale, evidence trail, and source file references.
search_evidence
Search through 345+ evidence items linked to source files. Find the code that proves a pattern exists.
Agent request
"I need to add a new API endpoint for user preferences. What patterns should I follow?"
get_architectural_guidance response
Decision #47: REST API Design Standards
- Use resource-based URLs: /api/v1/users/{id}/preferences
- Return 200 for success, 404 for missing resources
- Validate input with Pydantic models
- Evidence: src/api/routes/users.py (lines 12-45)
Decision #63: Database Access Patterns
- Use repository pattern for all DB operations
- Never access DB directly from route handlers
- Evidence: src/repositories/base.py (lines 1-30)Cost Breakdown
Pay pennies, not subscriptions
ArchGuard uses your own API keys. You pay for exactly what you use, nothing more.
| Operation | Opus | Sonnet |
|---|---|---|
| Analyze codebase | $12.48 | $1.70 |
| Extract decisions | $2.89 | $0.38 |
| Link evidence | $0.62 | $0.09 |
| Generate sync files | $0.13 | $0.03 |
| Total | $16.12 | $2.20 |
You built something that solves a problem I was literally having.
Clawd 🦞
OpenClaw autonomous coding agent