Roze - Motor de Análise Arquitetural
abp2204/roze
Análise arquitetural estática para mapeamento de DNA técnico em projetos
Ver no GitHubMCP server que mapeia a estrutura e comportamento de codebases complexas usando análise estática pura com Tree-Sitter. Identifica componentes críticos, traça cadeias de chamadas e gera dossiês arquiteturais sem chamadas LLM, funcionando diretamente dentro do seu agente de codificação.
Instalação
npx convez-ai abp2204/roze1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Onboarding em codebases complexas e legadas
- Identificação de componentes críticos e dependências de alto impacto
- Documentação automática de padrões arquiteturais e fluxos de chamadas
- Análise de complexidade cognitiva para refatoração estratégica
Veredito

Ferramenta sólida para engenheiros que trabalham com codebases grandes, especialmente em TypeScript/Next.js. A análise estática sem dependência de LLM é valiosa, mas o escopo atual é restrito a JavaScript/TypeScript e requer entendimento técnico profundo para extrair máximo valor.
README
A tradução para o português deste README ainda está na fila.
roze is a high-fidelity static analysis engine and MCP server. It uses Tree-Sitter to extract the structural and behavioral patterns of a codebase—identifying high-gravity components, mapping semantic actions, and tracing call-chains between entrypoints and side effects.
While roze is built on a language-agnostic foundation, the current toolset is highly optimized for TypeScript and JavaScript (especially Next.js, Prisma, and tRPC environments).
Zero LLM calls. Zero API keys. Pure static analysis.
Your coding agent does all the thinking — roze just gives it the right data.
Install
npx roze install
That's it. This patches your coding agent's MCP config so it can call roze's tools. Restart your agent.
Running the Analysis
You don't need to write a complex prompt. roze provides a built-in MCP Prompt called build_dossier that automatically tells your agent exactly what to do.
In Claude Code / Gemini CLI:
Type /prompt build_dossier and press enter.
In Cursor / Windsurf:
Open the MCP panel or agent chat, select the build_dossier prompt from the roze server, and run it.
Your agent will loop through the high-gravity files, analyze each one, and build an Architectural Dossier — a structured set of Decision Cards explaining the technical rationale of the code.
Supported Agents
| Agent | Config File |
|---|---|
| Claude Code | ~/.claude/claude_desktop_config.json |
| Gemini CLI | ~/.gemini/settings.json |
| Cursor | ~/.cursor/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
How It Works
┌─────────────────────────────────────────────────────────┐
│ Your Coding Agent (Claude / Gemini / Cursor) │
│ │
│ "Scan this project" ──► scan_project ──► get_file_ctx │
│ │ │ │
│ Agent synthesizes ◄──────┘ ◄──────────────┘ │
│ narratives + diagrams │
│ │ │
│ ▼ │
│ write_decision_card ──► .roze/dossier.json │
│ │ │
│ ▼ │
│ file:// Dossier UI │
└─────────────────────────────────────────────────────────┘
Three Levels of Analysis
-
Level 0 — Semantic Classification: Maps files to architectural "pillars" (Auth, Payments, Database, etc.) using import-path heuristics and library signatures.
-
Level 1 — Cognitive Complexity: Tree-Sitter AST analysis computes a complexity score per file based on link density, nesting depth, and mutation counts. Files scoring ≥ 15 are identified as High-Gravity.
-
Level 2 — Behavioral Traceability: Tree-Sitter powered call-graph analysis. It maps function-level dependencies and identifies Critical Functions (entrypoints, semantic actions, or high-outbound callers) so your agent can trace the exact ripple effect of a code change.
MCP Tools
roze exposes 8 tools over MCP stdio:
| Tool | Purpose |
|---|---|
scan_project | Call first. Scans the codebase, returns high-gravity files grouped by pillar. Starts file watcher. |
get_file_context | Returns full source + import graph neighbors for a specific file. |
write_decision_card | Persists a Decision Card (narrative + evidence + optional Mermaid diagram). |
get_strategic_overview | Returns dossier state without evidence snippets (saves tokens). |
inspect_pillar | Returns all Decision Cards for a pillar with full evidence. |
get_wild_discoveries | Returns the most complex files that don't fit standard patterns. |
mark_stale | Marks cards as stale when you modify files during a session. |
Recommended Agent Workflow
1. scan_project → get high-gravity files
2. For each file: get_file_context → read source + neighbors
3. Synthesize: "WHY does this code exist?"
5. write_decision_card → persist the narrative
6. Share the file:// UI link with the user
How It Works
Deep Analysis Pipeline
Unlike simple regex scanners, roze runs a deterministic 13-stage pipeline—from AST inventory and alias resolution to semantic classification and function-level scoring—to ensure every Decision Card is grounded in actual code paths.
Semantic Rulesets
roze uses specialized rulesets to understand framework-specific semantics. Current optimizations include:
- Next.js: Server Actions,
cookies(),headers(), and App Router conventions. - Database: Prisma model mutations and raw query patterns.
- API: tRPC procedure calls (
mutate/query) and standardfetch/axiospatterns. - Auth: Clerk, NextAuth, and custom rate-limiting/validation logic.
Dossier UI
After your agent writes Decision Cards, open the generated file in your browser:
file:///path/to/your/project/.roze/ui/index.html
The UI features:
- Dark theme with glassmorphism and subtle grid texture
- Pillar tabs for navigating architectural areas
- Decision Cards with fresh/stale status badges
- Mermaid diagrams rendered inline as SVG
- Evidence sidebar with Shiki syntax highlighting (tokyo-night)
- Wild Discoveries tab for the most complex outlier files
- Works entirely offline via
file://— no server needed
Architecture
packages/
├── brain/ # @roze/brain — analysis engine
│ └── src/
│ ├── scanner.ts # Tree-Sitter AST analysis (L0 + L1 + L2)
│ ├── dossier.ts # Atomic persistence + UI regeneration
│ ├── graph.ts # Import graph read/write
│ └── watcher.ts # Chokidar file watcher
├── cli/ # roze — MCP server + CLI
│ └── src/
│ ├── index.ts # #!/usr/bin/env node entry
│ ├── commands/
│ │ ├── install.ts # Agent config patcher
│ │ └── serve.ts # MCP server launcher
│ └── mcp/
│ ├── server.ts # @modelcontextprotocol/sdk setup
│ └── tools/ # 7 tool handlers
└── ui/ # @roze/ui — React dossier viewer
└── src/
├── App.tsx # Main app (reads window.__ROZE_DOSSIER__)
├── components/ # Header, PillarTabs, DecisionCard, etc.
└── index.css # Design system
Key Design Decisions
- No LLM calls: roze is a pure static analysis tool. The coding agent provides all synthesis.
async-mutex: All dossier writes are guarded by a mutex with atomic tmp+rename.startOnLoad: false: Mermaid is initialized manually — never auto-scans the DOM.base: './': Vite builds with relative paths so the UI works fromfile://URLs.console.logbanned: Brain and CLI use onlyconsole.errorto avoid corrupting MCP stdio.- Tree-Sitter WASM: Loaded from the
tree-sitter-wasmsnpm package — no network calls.
Development
Prerequisites
- Node.js ≥ 18
- npm ≥ 9 (for workspaces)
Setup
git clone https://github.com/abp2204/roze.git
cd roze
npm install
Build
npm run build
This runs in sequence: brain → cli → ui → bundle-ui (copies UI dist into CLI dist).
Dev UI
npm run dev:ui
Starts the Vite dev server for the UI package at http://localhost:5173.
Test Install Locally
node packages/cli/dist/index.js install
Test MCP Server
node packages/cli/dist/index.js serve
Then send JSON-RPC messages over stdin (see MCP specification).
Publish
npm run release
Builds everything and publishes the roze CLI package to npm.
How the Dossier Stays Fresh
When scan_project runs, it starts a Chokidar file watcher. When source files change:
- The watcher detects the change
- Matching Decision Cards are marked stale (amber badge in UI)
- The
stalePathsarray in the dossier tracks which files need re-analysis - Your agent can call
get_strategic_overviewto see what's stale, then re-scan
You can also manually mark files stale with mark_stale if you modify code during a session.