ArchPilot validates your repository against architecture rules and helps engineering teams move faster with AI-assisted development-without sacrificing architectural integrity.

Your AI writes code. ArchPilot protects architecture.

ArchPilot makes architecture visible, enforceable, and measurable as your system evolves.

🧭 Why this exists

Most teams rely on documentation or tribal knowledge to maintain architecture.

Over time, boundaries blur, dependencies leak, and architectural decisions drift without anyone noticing.

ArchPilot turns architecture into something you can actually validate, enforce, and track continuously.

AI accelerates code delivery-but architectural drift accelerates too.

ArchPilot gives teams deterministic architecture guardrails in local development, CI, and governance workflows.

🚀 What it does

ArchPilot turns architecture into something you can actually run and verify:

• Validate module boundaries and dependencies
• Enforce architecture rules and contracts
• Detect architectural drift over time
• Generate architecture scores and reports
• Surface architecture feedback in PRs and CI

No runtime agents. No external services. Fully deterministic and local-first.

🧩 Supported Stacks

ArchPilot supports practical deterministic architecture detection across modern application stacks.

Backend

• Node.js / TypeScript
• NestJS
• Express.js
• Java
• Spring / Spring Boot
• Kotlin
• FastAPI
• Django
• Flask
• PHP
• Laravel
• Go
• .NET
• Ruby on Rails

Frontend

• React
• Next.js
• Angular
• Vue

Infrastructure

• Terraform
• Ansible

ArchPilot detects stack shape from practical repository evidence - framework markers, manifests, project layout, and source structure - then applies conservative architecture discovery defaults locally.

No cloud scanning. No remote indexing. Deterministic local validation.

☁️ Local-first. Cloud-powered.

Start locally in minutes:

• Offline validation
• Local reports and artifacts
• PR review markdown
• CI validation
• Deterministic architecture checks

Then connect to ArchPilot Cloud to unlock:

• Repository history and trends
• Findings dashboards
• Team ownership and governance workflows
• Shared policies and exceptions
• Organization-wide architecture visibility
• Continuous governance across repositories

archpilot cloud status
archpilot cloud connect
archpilot cloud disconnect

Cloud setup only asks for your API token.

ArchPilot uses the canonical production API automatically-no server URL setup required for normal use. Learn more:

https://archpilot.org/docs

📦 Installation

Install globally:

npm install -g @archpilotlabs/archpilot

Or run without installing:

npx @archpilotlabs/archpilot --help

⚡ Quick Start

1. Initialize architecture

archpilot init

Creates .archpilot/ with architecture config, rules, and baseline artifacts.

2. Run validation

archpilot validate

Example output:

ArchPilot Architecture Review

Result: FAIL
Errors: 2   Warnings: 1
Score: 82 / 100

3. Fix issues

archpilot fix

Applies safe, deterministic fixes for missing architecture artifacts.

4. Use in CI

archpilot validate --ci

• Fails only on real architecture violations
• Keeps setup issues separate from architecture quality

🧑‍💻 CLI vs VS Code Extension

ArchPilot works in two ways:

• CLI (this package) → validation, CI, automation
• VS Code Extension → visual inspector, guided workflows, and architecture exploration

Both use the same validation engine and produce identical results. The extension enhances developer experience, but is not required.

🧠 Key Concepts

Architecture Health Score

Measures actual architecture quality based on violations.

Setup Readiness Score

Tracks completeness of configuration and onboarding.

Findings

• violation → real architecture issue
• setup-gap → missing config / skipped checks
• guidance → non-blocking recommendation

🔍 Core Commands

archpilot init
archpilot validate
archpilot validate --ci
archpilot fix
archpilot impact <file>
archpilot map
archpilot baseline check
archpilot review pr
archpilot review generate
archpilot report
archpilot cloud status
archpilot cloud connect
archpilot cloud disconnect
archpilot diagrams generate
archpilot policy init
archpilot exception init
archpilot safety init
archpilot bootstrap --with-contracts
archpilot contracts generate
archpilot governance upload

archpilot upload is an intentional shorthand alias for archpilot governance upload.

⚙️ Core Capabilities

• Architecture-as-code (.archpilot/)
• Dependency validation and module contracts
• ADR (Architecture Decision Record) support
• Drift detection and history tracking
• PR review and CI integration
• Architecture scoring and reporting

🎯 Philosophy

ArchPilot is built on four principles:

• Architecture should be explicit
• Rules should be executable
• Validation should be deterministic
• Feedback should be continuous

📄 License

Proprietary. See LICENSE file for details.

🌐 Learn More

• Website: https://archpilot.org
• Documentation: https://archpilot.org/docs