![](\"https://archpilot.org/media/branding/logo.svg\"){kind=logo}
\r\n\r\n \r\n
\r\n Architecture guardrails for AI-native software development\r\n
\r\n\r\nArchPilot validates your repository against architecture rules, helping engineering teams move faster with AI-assisted development without sacrificing architectural integrity.\r\n\r\n**Your AI writes code. ArchPilot protects architecture.**\r\n\r\n\r\n Validate • Enforce • Measure architecture continuously\r\n
\r\n\r\nArchPilot makes architecture **visible, enforceable, and measurable** as your system evolves.\r\n\r\n---\r\n\r\n## Why this exists\r\n\r\nMost teams rely on documentation or tribal knowledge to maintain architecture.\r\n\r\nOver time, boundaries blur, dependencies leak, and architectural decisions drift without anyone noticing.\r\n\r\nArchPilot turns architecture into something you can **actually validate, enforce, and track continuously**.\r\n\r\nAI accelerates code delivery but architectural drift can accelerate too.\r\n\r\nArchPilot gives teams deterministic architecture guardrails in local development, CI, and governance workflows.\r\n\r\n---\r\n\r\n## What it does\r\n\r\nArchPilot turns architecture into something you can actually run and verify:\r\n\r\n- Validate architecture across modern application stacks\r\n- Validate module boundaries and dependency governance\r\n- Enforce architecture rules and contracts\r\n- Detect architectural drift over time\r\n- Generate architecture scores and reports\r\n- Surface architecture feedback in local development, PRs, and CI\r\n\r\nAs repositories evolve, ArchPilot distinguishes governed architecture from high-confidence modules observed in the current source tree. Newly discovered modules are analyzed before governance acceptance, while adding them to `.archpilot/architecture.json` remains an explicit architecture review decision.\r\n\r\n**No cloud scan required. Deterministic and local-first.**\r\n\r\nArchPilot works alongside GitHub Copilot, Claude Code, Codex, Cursor, and other AI coding tools by continuously validating architectural boundaries before architectural drift becomes technical debt.\r\n\r\n---\r\n\r\n## Supported Stacks\r\n\r\nArchPilot provides **deterministic architecture validation** across modern application stacks using framework-aware analysis and explicit architectural evidence.\r\n\r\n### Backend\r\n\r\nFramework-aware validation\r\n\r\n- Spring / Spring Boot\r\n- NestJS\r\n- Express.js\r\n- FastAPI\r\n- Laravel\r\n- ASP.NET\r\n- Go\r\n\r\nLanguage-aware validation\r\n\r\n- Java\r\n- Node.js / TypeScript\r\n- PHP\r\n- Python\r\n\r\nFramework detection\r\n\r\n- Kotlin\r\n- Django\r\n- Flask\r\n- Ruby on Rails\r\n\r\n### Frontend\r\n\r\n- React\r\n- Next.js\r\n- Angular\r\n- Vue\r\n\r\n### Infrastructure Context\r\n\r\n- Terraform\r\n- Ansible\r\n\r\nInfrastructure repositories are detected as part of repository architecture discovery. Full architecture validation currently focuses on application stacks.\r\n\r\nArchPilot automatically detects supported stacks from repository evidence including framework markers, dependency metadata, manifests, project layout, source structure, and framework-specific constructs.\r\n\r\nValidation remains deterministic and framework-aware. When evidence is ambiguous, ArchPilot intentionally prefers conservative findings over speculative analysis.\r\n\r\n**No cloud scanning. No remote indexing. Deterministic local validation.**\r\n\r\n---\r\n\r\n## Local-first. Cloud-powered.\r\n\r\nStart locally in minutes:\r\n\r\n- Offline validation\r\n- Local reports and artifacts\r\n- PR review markdown\r\n- CI validation\r\n- Deterministic architecture checks\r\n\r\nThen connect to **ArchPilot Cloud** to unlock:\r\n\r\n- Repository history and trends\r\n- Findings dashboards\r\n- Team ownership and governance workflows\r\n- Shared policies and exceptions\r\n- Organization-wide architecture visibility\r\n- Continuous governance across repositories\r\n\r\n```bash\r\narchpilot cloud status\r\narchpilot cloud connect\r\narchpilot cloud disconnect\r\n```\r\n\r\nCloud setup only asks for your API token.\r\n\r\nArchPilot uses the canonical production API automatically; no server URL setup is required for normal use.\r\n\r\nLearn more:\r\n\r\nhttps://archpilot.org/docs\r\n\r\n---\r\n\r\n## Installation\r\n\r\nInstall globally:\r\n\r\n```bash\r\nnpm install -g @archpilotlabs/archpilot\r\n```\r\n\r\nOr run without installing:\r\n\r\n```bash\r\nnpx @archpilotlabs/archpilot --help\r\n```\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n### 1. Initialize architecture\r\n\r\n```bash\r\narchpilot init\r\n```\r\n\r\nCreates `.archpilot/` with architecture config, rules, and baseline artifacts.\r\n\r\n---\r\n\r\n### 2. Run validation\r\n\r\n```bash\r\narchpilot validate\r\n```\r\n\r\nTo focus on architecture changes introduced since the governance baseline:\r\n\r\n```bash\r\narchpilot validate --regressions\r\n```\r\n\r\nArchPilot automatically creates the initial governance baseline after the first successful full local validation. Regression validation can then distinguish newly introduced, existing, and resolved architecture findings.\r\n\r\nWhen you intentionally accept the current architecture findings as the new reference, run:\r\n\r\n```bash\r\narchpilot baseline refresh\r\n```\r\n\r\nThe governance baseline used for regression comparison is separate from the structural baseline used by `archpilot baseline create`.\r\n\r\nExample output:\r\n\r\n```text\r\nArchPilot Architecture Review\r\n\r\nResult: FAIL\r\nErrors: 2 Warnings: 1\r\nScore: 82 / 100\r\n```\r\n\r\n---\r\n\r\n### 3. Fix issues\r\n\r\n```bash\r\narchpilot fix\r\n```\r\n\r\nApplies safe, deterministic fixes for missing architecture artifacts.\r\n\r\n---\r\n\r\n### 4. Use in CI\r\n\r\n```bash\r\narchpilot validate --ci\r\n```\r\n\r\n- Fails only on real architecture violations\r\n- Keeps setup issues separate from architecture quality\r\n\r\n---\r\n\r\n## CLI vs VS Code Extension\r\n\r\nArchPilot works in two ways:\r\n\r\n- **CLI (this package)** - validation, CI, automation\r\n- **VS Code Extension** - visual inspector, guided workflows, and architecture exploration\r\n\r\nBoth use the same validation engine and produce identical results.\r\nThe extension enhances developer experience, but is not required.\r\n\r\n---\r\n\r\n## Key Concepts\r\n\r\n### Architecture Health Score\r\n\r\nMeasures actual architecture quality based on violations.\r\n\r\n### Setup Readiness Score\r\n\r\nTracks completeness of configuration and onboarding.\r\n\r\n### Findings\r\n\r\n- **violation** - real architecture issue\r\n- **setup-gap** - missing config / skipped checks\r\n- **guidance** - non-blocking recommendation\r\n\r\n---\r\n\r\n## Core Commands\r\n\r\n```bash\r\narchpilot init\r\narchpilot validate\r\narchpilot validate --ci\r\narchpilot fix\r\narchpilot impact