archmap

The architectural context layer for AI agents and teams

AI coding agents break things because they don't understand your architecture. archmap scans your codebase and generates architectural context that agents and tools consume automatically.

npx archmap init

One command. Your agent now knows every module boundary, dependency rule, and implicit contract.

Surface	What it provides
CLI	Generate and inspect context
SUMMARY.md	Context readable by any agent
JSON	Context structured for tools
MCP	Context queryable in real-time
CI	Context used as guardrail
VS Code	Context visible in your editor

Benchmarked on real projects

Repo	Language	Files	AST coverage	Modules	Duration
express	JavaScript	7	100%	2	726ms
fastify	JavaScript	35	100%	4	1050ms
zod	TypeScript	185	100%	18	3714ms
flask	Python	24	100%	1	566ms
gin	Go	99	100%	8	1475ms

See the demo repo for a complete before/after example.

What it does

archmap scans your codebase and generates .archmap/ containing:

• Module map — every module, its public API, and its dependencies
• Dependency graph — who imports what, with reference counts and line numbers
• Semantic rules — three tiers: rules (MUST), conventions (SHOULD), observations (INFO)
• Implicit contracts — co-change patterns from git history
• Health score — 0-100 per project and per module, weighted by severity
• SUMMARY.md — a concise markdown summary optimized for AI agent context windows
• CLAUDE.md integration — automatically injects architecture context

Why

Without archmap	With archmap
Agent rediscovers your codebase every session	Architecture is pre-computed and cached
Agent breaks implicit contracts	Agent knows which files must change together
Agent violates module boundaries	Agent sees dependency rules before coding
You write CLAUDE.md manually and it gets stale	CLAUDE.md auto-updates on every commit

Quick start

# Scan your project
npx archmap init

# View architecture overview (interactive TUI)
npx archmap show

# List rules grouped by tier
npx archmap rules

# Check rules in CI
npx archmap ci

# Auto-update on every commit
npx archmap hook install

Output

.archmap/
  config.json        # Configuration
  manifest.json      # Scan metadata, health score, parsing stats
  modules.json       # Module definitions and public APIs
  dependencies.json  # Full dependency graph
  rules.json         # Tiered rules (schema v2)
  contracts.json     # Implicit contracts from git history
  SUMMARY.md         # AI-optimized markdown summary

Example SUMMARY.md

# Architecture Map

> Auto-generated by archmap v0.8.2. Do not edit manually.
> Health: **A+** (100/100) | 3 rules, 5 conventions, 42 observations
> Parsing: **100% AST** (all files parsed with tree-sitter)

## Rules (MUST respect)

- **Clean Architecture: domain must not depend on infrastructure** (85%)
  - Action: This project follows clean-architecture. Violating this degrades the architecture.

## Conventions (SHOULD follow)

- **[85%] src/auth → src/db is one-directional
  - This module imports from 5 other modules but deliberately avoids src/routes.

## For AI Agents

1. **Rules** (MUST): Never violate items in the "Rules" section above
2. **Conventions** (SHOULD): Follow unless you have a specific reason not to
3. **Observations** (INFO): Be aware of these patterns

Semantic rule tiers

archmap uses a 3-tier system. Rules emerge from convergence of multiple independent signals, not from single heuristics.

Tier	Meaning	In CI	How it's inferred
rule	MUST respect	error (exit 1)	3+ signals converge, OR config boundary, OR arch pattern confirmed
convention	SHOULD follow	warning	2 signal kinds converge
observation	informational	info only	Single signal

Signal sources: static analysis (dependencies, exports, naming), git history (co-changes, removed deps, change frequency), config files (eslint, tsconfig, workspaces), and architectural pattern detection (Clean Architecture, MVC, Hexagonal, Layered).

Health score

Each scan produces a health score (0-100) weighted by:

• Module size — violations in larger modules penalize more
• Category severity — boundary violations (1.5x) > layer (1.3x) > naming (0.5x)
• Drift — weakening trends and unstable hotspots reduce score
• Per-module scores — identify which modules need attention

Manual rules

Define team rules in .archmap/rules.yml:

rules:
  - description: "Never import from legacy/"
    category: boundary
    scope: ["src/*"]
    action: "This module is deprecated. Use src/v2/ instead."

Manual rules are always tier rule — they represent explicit team decisions.

Rule overrides

In .archmap/config.json:

{
  "ruleOverrides": {
    "boundary-003": "suppress",
    "co-change-007": "promote:rule"
  }
}

Configuration

.archmap/config.json is created on first run:

{
  "version": 1,
  "exclude": ["node_modules", "dist", "build", ".git", "vendor", "__pycache__"],
  "moduleRoots": ["src", "lib", "app", "packages"],
  "languages": ["typescript", "javascript", "python", "go", "rust", "java"],
  "gitHistory": {
    "maxCommits": 1000,
    "minCoChangeConfidence": 0.7,
    "trendWindow": 100
  },
  "agentIntegration": {
    "updateClaudeMd": true,
    "updateCursorRules": false
  },
  "ruleOverrides": {}
}

Agent integration

Claude Code

archmap automatically updates your CLAUDE.md with architecture context between fenced markers:

<!-- archmap:start -->
... architecture summary ...
<!-- archmap:end -->

Your manual content in CLAUDE.md is preserved.

Cursor

Enable in .archmap/config.json:

{ "agentIntegration": { "updateCursorRules": true } }

Any agent

Point your agent to .archmap/SUMMARY.md or the structured JSON files.

CI mode

# Tier-aware: rules=error, conventions=warning
npx archmap ci

# Conventions also fail the build
npx archmap ci --strict

# Only enforce rules above 90% confidence
npx archmap ci --min-confidence 0.9

# Fail if any file falls to regex parsing
npx archmap ci --strict-ast

# JSON output for CI parsing
npx archmap ci --json

Example GitHub Actions:

- name: Architecture check
  run: npx archmap ci

CI also warns when AST coverage drops, listing specific files that fell to regex fallback.

AST-first parsing

archmap uses tree-sitter (WASM) for accurate AST parsing. If a grammar can't be loaded, it falls back to regex — and tells you exactly which files used which method:

Files scanned:    90
Parsing:          95% AST (85 AST, 5 regex fallback)

Use --strict-ast to fail if any file falls to regex. The manifest, SUMMARY.md, MCP, and CI all expose per-file fallback data.

MCP Server

9 tools for real-time architecture queries:

{
  "mcpServers": {
    "archmap": {
      "command": "npx",
      "args": ["archmap-mcp", "."]
    }
  }
}

Tool	Description
get_modules	List all modules with public APIs
get_module	Get details for a specific module
get_dependencies	Query dependency graph (optionally filtered)
get_rules	List rules — filter by tier, category, confidence
get_contracts	List implicit co-change contracts
check_impact	Given a file, what else might need to change?
get_summary	Full architecture summary as markdown
get_health	Project health score and per-module breakdown
get_parsing_stats	AST vs regex breakdown with file-level detail

Interactive TUI

npx archmap show

• Health score and parsing stats in header
• Rules grouped by tier (MUST/SHOULD/INFO) with trend icons
• Module browser with per-module health scores
• Dependency layers and cross-module relationships

VS Code Extension

• Sidebar — modules with health scores, rules grouped by tier
• Status bar — current module, exports, deps, health
• Hover — imported symbol origin and module info
• Rules panel — tier icons, trend arrows, category icons, action tooltips
• Parsing stats — AST coverage shown in rules panel header
• Compatibility check — warns if .archmap/ was generated by an incompatible version

Programmatic API

import { scanProject, loadConfig, generateMarkdown } from 'archmap';

const config = await loadConfig('./my-project');
const result = await scanProject('./my-project', {
  gitHistory: true,
  strictAst: false,
  verbose: false,
  config,
});

console.log(result.health);           // Health score
console.log(result.stats.parsing);    // { ast: 90, regex: 0, pct: 100, regexFiles: [] }
console.log(result.rules);            // Tiered rules with actions
console.log(generateMarkdown(result)); // SUMMARY.md content

Key principles

• AST-first parsing — tree-sitter WASM with transparent regex fallback. Output shows exactly which method was used per file.
• Multi-signal inference — rules emerge from convergence of independent signals, not single heuristics
• Fully offline — your code never leaves your machine. No API keys. No network calls.
• Zero config — works out of the box with npx archmap init
• Honest about limits — parsing stats, confidence scores, and signal counts are always visible

Quick setup templates

Ready-to-copy files in templates/:

File	Purpose
mcp.json	MCP server config for Claude Code
archmap-ci.yml	GitHub Actions workflow
.cursorrules	Cursor integration
rules.yml	Manual rules starter

Supported languages

TypeScript, JavaScript, Python, Go, Rust, Java — all with tree-sitter AST parsing and regex fallback.

Links

• Demo repo — before/after example
• Benchmark report — precision on real projects
• npm

License

MIT