Architectos

io.github.cgseyhanPublished by GitHub account cgseyhanv0.1.30Updated Oct 24, 2026

ArchitectOS - AI-Native Repository Intelligence & Architecture Operating System.

VerifiedSTDIODesktop onlyDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

ArchitectOS is a local MCP server that gives an AI assistant read-only analysis of a code repository: health review, coupling, change impact, refactoring plans,

What you can do
Review repository health and problem breakdown, with optional score threshold for CI use. Explain root-cause coupling and calculate downstream change impact across the codebase. Generate step-by-step refactoring and migration plans. Resolve symbols and answer natural-language architecture questions to reduce hallucination. Detect unused exports and dead code, and audit UI component composition and boundaries. Store persistent architectural guardrail rules for later recall.
When to use it
Useful when an assistant works on an existing codebase and needs to understand its architecture, judge the risk of a change, or produce a refactoring plan before editing. Also suited to enforcing architecture guardrails for AI coding agents such as Claude Code, Cursor or Codex.
Requirements
Runs as a local process over stdio, started with npx from the npm package architectos (Node.js required). No authentication, environment variables or headers are declared. It analyzes a repository on the local machine.
Before you install
The README states it never modifies user code directly; code changes are left to the agent or developer, so review any plan before acting on it. It reads repository source code locally, and its findings, scores and security results are heuristic and should be verified.

Installation

In SourceWeft

  1. Open Architectos in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

ArchitectOS

AI-Native Repository Intelligence & Governance Engine

ArchitectOS analyzes your repository, explains its architecture, calculates change impact, and enforces guardrails for AI Agents (Claude Code / Cursor / Codex).

[License: MIT] [NPM Version] [Dogfooded with ArchitectOS] [Node.js] [MCP Ready]

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

bash
# 1. Initialize and review repositorynpx architectos
# 2. High-level repository health, security & UI review (with optional CI threshold)architectos reviewarchitectos review --threshold 80
# 3. Component deep-dive (supports --why, --ui, --dead, --duplication, --taint)architectos analyze toolbar.tsxarchitectos analyze toolbar.tsx --whyarchitectos analyze --uiarchitectos analyze --deadarchitectos analyze --duplicationarchitectos analyze --taint auth.controller.ts
# 4. View historical score timeline and trendarchitectos history
# 5. Cross-graph downstream change impact & risk ratingarchitectos impact auth.ts
# 6. Structured refactoring migration planarchitectos plan toolbar.tsx
# 7. Symbol resolver & natural language architecture queryarchitectos resolve WorkspaceRepositoryarchitectos resolve "Where is tenant isolation enforced?"
# 8. Native MCP server gateway & live watcherarchitectos watcharchitectos mcp

🏛️ The ArchitectOS Pipeline

text
architectos review               # High-level health & problem breakdown (--threshold 80)      ↓architectos analyze <target>     # Deep-dive (--why, --ui, --dead, --duplication, --taint)      ↓architectos impact <target>      # Cross-graph downstream change risk      ↓architectos plan <target>        # Step-by-step refactoring migration plan      ↓architectos resolve <symbol>     # 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:

RepositoryFilesOverallArchSecQualAIUIScan SpeedTop Focus Area
excalidraw/excalidraw520+88/1009284909480<18msCanvas Component Decomposition
calcom/cal.com1,400+84/1008088829080<45msBooking Service Layer Isolation
shadcn/ui120+96/1009895969596<8msUI Component Primitive Boundaries
cgseyhan/architectos51100/100100100100100N/A<19msNative Self-Hosted AST Governance

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:

json
{  "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

Source: README.md at commit 34a1ba3

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.30LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.