architectos

> Strict Product Mandate: ArchitectOS never modifies user code directly; it exclusively analyzes, explains, calculates impact, and generates actionable refactoring plans. Code modifications are executed by AI Agents or human developers.

⚡ Quickstart & Core Commands

# 1. Initialize and review repository
npx architectos

# 2. High-level repository health, security & UI review (with optional CI threshold)
architectos review
architectos review --threshold 80

# 3. Component deep-dive (supports --why, --ui, --dead, --duplication, --taint)
architectos analyze toolbar.tsx
architectos analyze toolbar.tsx --why
architectos analyze --ui
architectos analyze --dead
architectos analyze --duplication
architectos analyze --taint auth.controller.ts

# 4. View historical score timeline and trend
architectos history

# 5. Cross-graph downstream change impact & risk rating
architectos impact auth.ts

# 6. Structured refactoring migration plan
architectos plan toolbar.tsx

# 7. Symbol resolver & natural language architecture query
architectos resolve WorkspaceRepository
architectos resolve "Where is tenant isolation enforced?"

# 8. Native MCP server gateway & live watcher
architectos watch
architectos mcp

🏛️ The ArchitectOS Pipeline

architectos review               # High-level health & problem breakdown (--threshold 80)
      ↓
architectos analyze      # Deep-dive (--why, --ui, --dead, --duplication, --taint)
      ↓
architectos impact       # Cross-graph downstream change risk
      ↓
architectos plan         # Step-by-step refactoring migration plan
      ↓
architectos resolve      # Hallucination shield & symbol resolver
      ↓
architectos history              # Historical score timeline & trend tracking
      ↓
AI Agent / Developer executes refactor

🎯 Engine Precision & Accuracy Features

• 25 CWE-Mapped SAST Engine: High-precision rules covering SQLi, XSS, RCE, ReDoS, Prototype Pollution, NoSQLi, Open Redirect, Unsafe Deserialization, and Weak Cryptography.
• Context-Aware Noise Filter: Automatically suppresses false positives inside test blocks (`describe`/`it`), JSDoc comments, dead conditional branches, and when known sanitizers (`DOMPurify`, `escapeHtml`) are detected.
• Multi-File Taint Tracking Engine: Traces untrusted user inputs (HTTP `req.body`/`searchParams`) down to dangerous execution sinks across multi-file import graphs.
• Code Duplication Scanner: Token-fingerprinted Jaccard similarity engine detecting copy-pasted code blocks across monorepo packages.
• Framework Entrypoint Whitelist: Eliminates false positives for Next.js (`GET`, `POST`, `generateMetadata`, `middleware`), Remix, Vitest, and CLI entrypoints.
• Tarjan SCC Cycle Detection: Mathematically sound circular dependency cycle detection for complex monorepos.
• Public Scoring Transparency: Fully documented formulas and deduction rules in SCORING.md.

🧪 Real-World Benchmark Verification (v1.2.1 Engine Breakdown)

ArchitectOS is battle-tested and dogfooded across major open-source codebases with transparent sub-metric scoring:

*Note: Pure CLI / backend repositories (e.g. `architectos`) omit UI Architecture scoring.*

🤖 Native MCP Server Integration

Add ArchitectOS to your Claude Code, Cursor, or Codex MCP configuration:

{
  "mcpServers": {
    "architectos": {
      "command": "npx",
      "args": ["-y", "architectos", "mcp"]
    }
  }
}

Registered MCP Tools

• `architectos_review`: Repository health & problem breakdown.
• `architectos_why`: Root-cause coupling analysis.
• `architectos_impact`: Polyglot change impact calculator.
• `architectos_plan`: Step-by-step migration refactoring plan.
• `architectos_resolve`: Symbol resolver & hallucination shield.
• `architectos_dead`: Unused exports & zombie code detector.
• `architectos_ui`: Framework-agnostic UI component composition & boundary audit.
• `architectos_remember`: Store persistent architectural guardrail rules.

📄 License

MIT License © 2026 ArchitectOS Authors