ArchPilot validates your repository against architecture rules, helping 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 can accelerate 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 architecture across modern application stacks
• Validate module boundaries and dependency governance
• Enforce architecture rules and contracts
• Detect architectural drift over time
• Generate architecture scores and reports
• Surface architecture feedback in local development, PRs, and CI

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

ArchPilot works alongside GitHub Copilot, Claude Code, Codex, Cursor, and other AI coding tools by continuously validating architectural boundaries before architectural drift becomes technical debt.

Supported Stacks

ArchPilot provides deterministic architecture validation across modern application stacks using framework-aware analysis and explicit architectural evidence.

Backend

Framework-aware validation

• Spring / Spring Boot
• NestJS
• Express.js
• FastAPI
• Laravel
• ASP.NET
• Go

Language-aware validation

• Java
• Node.js / TypeScript
• PHP
• Python

Framework detection

• Kotlin
• Django
• Flask
• Ruby on Rails

Frontend

• React
• Next.js
• Angular
• Vue

Infrastructure Context

• Terraform
• Ansible

Infrastructure repositories are detected as part of repository architecture discovery. Full architecture validation currently focuses on application stacks.

ArchPilot automatically detects supported stacks from repository evidence including framework markers, dependency metadata, manifests, project layout, source structure, and framework-specific constructs.

Validation remains deterministic and framework-aware. When evidence is ambiguous, ArchPilot intentionally prefers conservative findings over speculative analysis.

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 is 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/)
• Smart Init architecture discovery
• Cross-stack architecture validation
• Dependency governance and module contracts
• ADR (Architecture Decision Record) support
• Drift detection and history tracking
• PR review and CI integration
• Architecture scoring and reporting

Deterministic by Design

ArchPilot intentionally avoids speculative code analysis.

Findings are produced from explicit architectural evidence such as:

• Framework annotations and decorators
• Dependency relationships
• Route and API definitions
• Authorization constructs
• Transaction boundaries
• ORM and query APIs
• Event and messaging infrastructure
• Architecture configuration and contracts

When evidence is ambiguous, ArchPilot prefers not to report a finding rather than generating false positives.

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
• Changelog