Documentation

Quick Start

npm install -g archondev

cd your-project && archon

archon plan "Add user authentication"

Smart Onboarding: Three Scenarios

After login and tier selection, ArchonDev reads the waters and routes you to the right workflow without guesswork.

User Journey Governance (Lite + CLI)

ArchonDev is optimized as a full journey system, not just command docs. Both Lite and CLI flows are designed to reduce decision fatigue, prevent dead ends, and move users from setup to confident execution quickly.

Quality Level / Posture

Set how strict your AI should be. Run lean in prototypes and lock discipline in production and enterprise.

5-Phase Interview System

A conversational interview that guides you through defining your project, then generates a formal specification.

Project Constitution

The Constitution is a formal, immutable specification generated from the interview. It's the contract between you and the AI for what gets built.

Generate prd.json from Constitution

Once frozen, transform your Constitution into executable atoms:

CLI Reference

Use these commands to keep execution on course: approve design, execute with gates, and review in the right order.

.archon/active/architecture.md Format

Your source of truth for governance. Uses YAML frontmatter.

---
name: My Project
version: "1.0"

boundaries:
  - path: "src/db/**"
    protection: STRICT
    description: "Database layer"

invariants:
  - id: INV-001
    type: NO_DIRECT_IMPORT
    path: "@supabase/supabase-js"
    enforcement: BLOCKING

protectedPaths:
  - pattern: "src/db/schema.ts"
    reason: "Schema changes require migration"
---

DEPENDENCIES.md

Track file-level dependencies to prevent regressions.

Code Review

AI-powered code review for any codebase. Non-destructive analysis.

Task Extraction Protocol

AI confirms all items from multi-part requests before starting. Nothing gets forgotten.

Accessibility Check

If Archon detects a web project, it will prompt you to run A11y/SEO/GEO checks and remember your preference in .archon/config.yaml.

WCAG 2.2 AA compliance checks with legal liability warnings.

SEO Optimization

GEO for AI Search

Generative Engine Optimization — get your product cited by AI assistants.

GitHub Integration

Connect your GitHub account for cloud execution with automatic PR creation.

Cloud Agents

Run AI agents in the cloud. Close your laptop while work continues.

Requirements: Credits tier + connect GitHub first with archon github connect

Session Management

Save your session and continue on another device.

Semantic Indexing

Semantic search across your codebase. Local (free) or cloud options.

Local Indexing (Free with Ollama)

# Install Ollama first: https://ollama.ai
ollama pull nomic-embed-text
archon index init --local
archon index update
archon index search "authentication flow"

Cloud Indexing (pgvector)

Uses OpenAI embeddings stored in Supabase. Requires Supabase Pro plan.

archon index init --cloud
archon index update --cloud
archon index search "authentication flow" --cloud

Smart Model Routing

Automatically routes operations to the optimal AI model tier for cost optimization. Simple tasks use cheap/fast models; complex planning uses powerful models.

Model Tiers

Configure Preferences

Parallel Execution

Run multiple agents simultaneously using git worktrees with dependency-aware scheduling.

Dependency Scheduling

ArchonDev analyzes atom dependencies and file conflicts to schedule execution in parallel waves.

Manual Parallel

Parallel Cloud (Credits)

History & Revert

Each atom execution creates a git commit. Revert individual atoms without affecting other changes.

CLI Users

Lite Package Users

Say show atom history or revert atom to your AI. Uses git under the hood:

# List atom commits
git log --oneline | grep -E '\[(ATOM|US)-[0-9]+\]'

# Revert specific commit
git revert <commit-hash>

Eject

Remove all ArchonDev metadata, leaving a clean standalone codebase you fully own.

CLI Users

Lite Package Users

Say eject archondev to your AI, or manually remove:

• • .archon/, archondev-scenarios/, AGENTS.md
• • IDE rules: .cursorrules / .windsurfrules / CLAUDE.md / etc.

Keep: .archon/active/architecture.md (useful standalone), progress.txt (history)

Deploy

One-click deployment with automatic platform detection.

Supported: Fly.io, Vercel, Netlify, Railway, Render

Cleanup

Keep your workspace lean for optimal AI performance. Large files consume context.

Working with Existing Projects

Add governance to projects created by other AI agents or manual coding.

# Step 1: Review existing code
archon review init
archon review analyze
archon review run --all

# Step 2: Set up governance
archon init --analyze

# Step 3: Fix issues
archon plan "fix critical issues from review"

VS Code Extension

Real-time architectural governance with quick-fix suggestions.

• • Real-time violation detection in Problems panel
• • Quick-fix suggestions (Ctrl+. / Cmd+.)
• • Protected path warnings
• • Boundary enforcement for cross-module imports

Installation: Download archondev-0.2.0.vsix from the downloads page, then Extensions → ... → Install from VSIX

Tiers & Billing

BYOK Key Security

• • Your API keys stay on your machine and are never uploaded to ArchonDev servers.
• • Keys are encrypted at rest with AES-256-GCM in ~/.archon/keys.json.
• • The key file is set to owner-only permissions (0600).
• • BYOK runs locally; cloud execution is Credits-only.

If your device is compromised, an attacker could access local files. Treat API keys as sensitive secrets.

Troubleshooting