Archondev

<p align="center"> <img src="https://archondev.io/images/logo-watermark.png" alt="ArchonDev" width="180" /> </p> <h1 align="center">ArchonDev</h1> <p align="center"> <strong>Govern AI Code Your Way</strong><br> CLI for total control. Drop-in for your existing tools. </p> <p align="center"> <a href="https://www.npmjs.com/package/archondev"><img src="https://img.shields.io/npm/v/archondev.svg" alt="npm version"></a> <a href="https://archondev.io">Website</a> • <a href="https://archondev.io/docs">Documentation</a> • <a href="https://archondev.io/download">Download</a> • <a href="https://archondev.io/changelog">Changelog</a> </p>

---

What is ArchonDev?

ArchonDev is an AI-powered development governance system that prevents your AI coding assistant from making architectural mistakes, forgetting context, and introducing regressions.

The Problem: AI coding assistants are powerful but unreliable. They hallucinate, ignore your architecture, forget what they learned, and break things they just fixed.

The Solution: ArchonDev adds governance — architectural rules your AI must follow, quality gates before every change, and persistent learning across sessions.

---

Two Ways to Use ArchonDev

Option 1: Full CLI (Recommended)

The complete AI development system. It manages your entire development process so you can focus on the big picture — not constantly correcting your AI.

# macOS/Linux:
npm install -g archondev && archon

# Windows PowerShell:
npm install -g archondev; archon

What you get:

• AI that reads and respects your architecture before writing code
• Quality Level / Posture — Right-sized architecture (prototype/production/enterprise)
• Adversarial planning (Architect proposes, Sentinel critiques)
• Automatic quality gates before changes are applied
• Learning persistence — mistakes are remembered and avoided
• Dependency tracking — prevent regressions with "what-breaks-what" map
• Bug reporting with root cause analysis
• AI-powered code review for any codebase
• Multi-provider key support with adversarial features
• Risk scoring — Numeric 0-100 risk assessment before execution
• Ship pipeline — One command: review → test → version → changelog → PR
• Visual QA — Headless browser health checks with diff-aware page testing
• Session retrospective — Quantitative metrics on atoms, gates, and hotspots

Option 2: Lite Package

Copy governance files into any project. Works with your existing AI tools: Cursor, Claude Code, Windsurf, Amp, Copilot, Gemini, and more.

Download Lite Packages →

What you get:

• .archon/active/architecture.md template with best practices
• Quality Level / Posture — Tell AI if it's prototype, production, or enterprise-grade
• IDE-specific rule files (.cursorrules, CLAUDE.md, GEMINI.md, etc.)
• Progress tracking templates
• DEPENDENCIES.md — Track file-level dependencies to prevent regressions
• First-Run Walkthrough — Guided onboarding when AI detects your governance files
• Code Review Mode — Structured code review without changing your code
• Local Database — Track atoms and learnings in SQLite (no CLI required)
• Memory Management — Context handoff protocol for long sessions
• Task Extraction Protocol — AI confirms all items before starting, nothing gets forgotten
• Pre-Deploy Accessibility — WCAG 2.2 AA check before going live, legal liability warnings
• Works with any AI coding assistant

Local Governance SQLite (Dev Only)

Governance data for this repo lives in .archon/governance.db and is local-only. It is never synced to Supabase.
To initialize or refresh it:

pnpm exec tsx scripts/init-governance-db.ts

---

Commands

| Command | Description | |---------|-------------| | archon | Interactive mode — just run and follow prompts | | archon init | Initialize in your project | | archon login | Authenticate with ArchonDev | | archon config ai | Switch from Free mode to BYOK and configure provider keys | | archon status | Show login status and current mode | | archon plan <description> | Create a work item with AI planning (extracts and confirms multi-item requests) | | archon execute <atom-id> | Execute with quality gates | | archon list | List all work items | | archon show <atom-id> | Show details | | archon watch | Live TUI dashboard with status | | archon bug report <title> | Bug report with root cause analysis | | archon review init | Initialize AI-powered code review | | archon review analyze | Scan project and populate review tasks | | archon review run | Run AI review on pending tasks | | archon usage | Usage by period and model | | archon keys add <provider> | Add your own API key — BYOK (Bring Your Own Key) | | archon keys list | Show configured API keys by provider | | archon preferences | Interactive settings menu (models, keys, usage) | | archon models | List available AI models | | archon deps list | View file dependency rules | | archon deps add | Add a new dependency rule | | archon deps check --files <list> | Check for downstream impacts | | archon deps graph | Generate Mermaid dependency diagram | | archon a11y check | Run WCAG 2.2 AA accessibility audit | | archon a11y fix | Auto-fix common accessibility issues | | archon a11y badge | Add accessibility compliance badge | | archon a11y pre-deploy | Interactive pre-deployment check | | archon seo check | Run SEO meta tag audit | | archon seo fix | Apply recommended SEO fixes | | archon geo identity | Generate brand identity phrases for AI citation | | archon geo schema | Generate JSON-LD schemas | | archon governance status | Show governance status (AGD) | | archon governance architecture update | Update architecture with change reason | | archon governance task update | Update governance tasks | | archon governance handoff | Log handoff + current context | | archon governance migrate | Migrate legacy governance files | | archon governance sqlite-init | Initialize or refresh local governance SQLite DB | | archon github connect | Link GitHub account for cloud execution | | archon github status | Check GitHub connection status | | archon session save [name] | Save current session to cloud | | archon session resume [id] | Resume session on another device | | archon execute ATOM --cloud | Execute in cloud (creates PR when done) | | archon cloud status | List cloud executions | | archon parallel cloud ATOM-001 ATOM-002 | Legacy command (disabled in free/BYOK mode) | | archon index init [--local\|--cloud] | Initialize semantic indexing | | archon index update [--cloud] | Index changed files | | archon index search "query" [--cloud] | Semantic code search | | archon parallel status | Show parallel execution status | | archon ship | Ship pipeline: review → test → version → changelog → PR | | archon ship --dry-run | Run all ship checks without committing | | archon qa | Visual QA with headless browser health checks | | archon qa --url <url> | Test specific URL | | archon retro | Session retrospective with quantitative metrics | | archon deploy | One-click deploy (auto-detect platform) | | archon cleanup check | Analyze workspace for bloat | | archon cleanup run | Execute cleanup tasks | | archon cleanup auto [enable\|disable] | Enable/disable auto cleanup on start |

Notes:

• Content-only requests (stories, outlines, lessons, visuals) use lightweight planning to avoid blocking.
• BYOK shows per‑model usage and cost by today/week/month/year in archon preferences → “View usage details.”
• You can paste multi‑line requests into interactive prompts; Archon captures them as a single response.
• Proposal approvals like approve plan now bind to the pending proposal context in chat mode.
• Governance boundary/path checks in execute now steer with actionable guidance and set atoms to BLOCKED rather than hard failing.
• Analysis-first requests now return recommendations first and accept natural confirmations (yes, go ahead, create) to create governed tasks.
• Chat continuation supports natural directives (continue, move forward), and path-scope governance blocks now attempt automatic re-plan + retry recovery.
• Chat now preserves your high-signal original request better across exploratory turns (for example: check folders), and avoids duplicate plan/execution prompts.
• After explicit approvals in chat (yes, approve plan), execution continues directly without extra confirmation prompts.

Tip: Use archon plan --edit to adjust title and acceptance criteria before planning. Web Checks: If Archon detects a web project, it prompts to run A11y/SEO/GEO checks and stores your preference in .archon/config.yaml.

Pricing

| Mode | Cost | What You Get | |------|------|--------------| | Free (Download / Governance) | $0 | Governance/workflow layer with no built-in AI calls | | BYOK (CLI + AI) | $0 to ArchonDev | Use your own provider keys; provider bills tokens directly |

No paid tiers, no credit purchases, and no Archon token markup.

BYOK Key Security

• Your API keys are stored locally in ~/.archon/keys.json (never uploaded to ArchonDev servers).
• Keys are encrypted at rest with AES-256-GCM and the file is set to owner-only permissions (0600).
• Archon uses your keys only to call your chosen providers on your behalf.
• If your device is compromised, an attacker could access local files. Treat keys as sensitive secrets.

How It Works

1. Login & Choose Mode — Create account, choose Free or BYOK
2. AI Interview — Natural conversation about your project (or skip to defaults)
3. Define Your Rules — ARCHITECTURE.md with boundaries and invariants
4. AI Reads Rules First — Every session starts by understanding your architecture
5. Changes Are Validated — Quality gates check code before