Codesorb

Hallucination-free architecture intelligence for brownfield code analysis.

Codesorb parses codebases with tree-sitter AST and gives AI agents verified structural metadata: imports, exports, classes, functions, types, and dependencies. 91% cheaper than raw code, zero hallucinations on facts, 8 languages supported.

• ⚡ 54 files/sec — Fast, error-tolerant parsing via tree-sitter
• 💰 91% token savings — 10x more efficient than raw code for LLMs
• ✅ 100% accurate — AST-verified facts with file:line citations
• 🔌 Pluggable — CLI, REPL, MCP server, Skills, or Node.js API

What's New in v0.5.2

Boundary Intelligence

Detect external service boundaries and identify safe refactoring zones. Analyzes outbound HTTP calls across 9 languages, classifies each module as SAFE/MEDIUM/RISKY to change, and generates a markdown boundary report.

codesorb boundary-intelligence ./src
/codesorb:boundary-intelligence ./src

MCP tool: codesorb_boundary_intelligence — docs

JSON Execution Layer

Generate deterministic execution plans for multi-file code changes. Codesorb prepares AST-grounded prompts; your IDE LLM generates the plan; Codesorb validates JSON, detects circular task dependencies, and topologically sorts tasks.

# Step 1: Generate prompt from AST
codesorb_prepare_execution_plan --path ./src --objective "Extract UserRepository"

# Step 2: IDE LLM completes the prompt → JSON plan

# Step 3: Validate and sort
codesorb_apply_execution_plan --llm-response plan.json

MCP tools: codesorb_prepare_execution_plan + codesorb_apply_execution_plan — docs

30 MCP tools total. 25+ skills. No API keys required for AST tools.

Quick Start (30 seconds)

npm install -g codesorb
codesorb absorb .
# Open .codesorb-analysis/developer-report.md

See docs/QUICKSTART.md for a one-page install guide.

Three Pathways

| Pathway | Command | Time | Output | |---------|---------|------|--------| | Quick Start | codesorb absorb . | 30s | Full report suite (5 files) | | Developer Deep-Dive | codesorb parse . then graph, analyze-impact, audit | varies | Targeted analysis | | Enterprise Compliance | codesorb absorb . && codesorb compliance-wizard . | 5 min | Audit-ready artifacts |

Try It in 60 Seconds

In Claude Code (Recommended) — v0.5.2 Plugin

npm install -g [email protected]
codesorb setup --full-install

# Restart Claude Code, then use 25+ skills:
/codesorb:parse ./my-project
/codesorb:hotspots ./my-project
/codesorb:dark-pits ./my-project
/codesorb:blast-radius ./my-project --file=src/auth.ts
/codesorb:boundary-intelligence ./my-project

That's it. Results appear inline. Chain skills together:

/codesorb:parse ./src
/codesorb:hotspots ./src     # uses cached snapshot
/codesorb:dark-pits ./src    # uses cached snapshot

Ask Claude about them:

"Based on the dark pits above, which module should we refactor first?"

All 25+ skills available (22 AST + optional):

22 AST skills (no API key, no provider needed): parse, analyze-risks, find-cycles, analyze-coupling, generate-snapshot, hotspots, dark-pits, blast-radius, rank-modules, find-dead-code, breaking-changes, impact-estimate, performance-profile, audit-compliance, map-features, analyze-repos, git-history, extract-context, elicit-context, map-scenarios, audit, boundary-intelligence (external contracts + safe refactoring zones), prepare-execution-plan, apply-execution-plan (JSON execution layer).

Optional skills (prepare/apply pattern for IDE LLM composition): enrich-functions, detect-frameworks-llm, parse-unsupported.

# For AST skills: nothing required
# For optional skills: your IDE tool (Claude, Copilot, Cursor) handles LLM provider
# Codesorb uses prepare/apply pattern - IDE completes the LLM call
# See docs/skills/execution-plan-guide.md and docs/skills/LLM-SKILLS-GUIDE.md for details

See USER-JOURNEYS.md for per-platform guides and SKILLS-COMPOSITION-GUIDE.md for multi-skill workflows.

Via CLI (Alternative)

codesorb parse ./my-project
cat codesorb-snapshot.json | jq '.fileCount'

Why Codesorb?

For brownfield projects: Map existing systems, detect dark pits, plan refactoring with confidence.

For AI agents: AST-powered extraction prevents hallucinations. Claude Code, Cursor, Copilot get accurate context at 91% lower cost.

For architects: Dependency graphs, impact analysis, multi-repo orchestration — understand your system before changing it.

Supported Languages

8 languages with full AST support: TypeScript, JavaScript, Python, Java, Kotlin, Go, Rust, Ruby. Mixed-language repos supported.

Installation

Prerequisites: Node.js ≥ 22.0.0

Your code stays on your machine — no cloud upload.

# Global install (recommended)
npm install -g github:piyushmor/codesorb

# Or add to project
npm install github:piyushmor/codesorb

IDE Integration

Connect Codesorb to your IDE in 30 seconds:

codesorb setup                       # auto-detect all installed AI tools
codesorb setup --full-install        # Claude Code: MCP + 25 /codesorb:* skills
codesorb setup --client cursor       # Cursor: writes ~/.cursor/mcp.json
codesorb setup --client copilot      # GitHub Copilot: writes VS Code settings.json
codesorb setup --client vscode       # VS Code MCP config only

See docs/IDE-INTEGRATION.md for full setup instructions including VS Code extension install, Windsurf, and troubleshooting.

See docs/GETTING-STARTED.md for a 5-minute end-to-end tutorial.

Community Plugins

Extend Codesorb with custom skills published to npm:

codesorb list-skills                              # list built-in + installed plugin skills
codesorb install-skill codesorb-skill-my-rule     # install a community skill

Write and publish your own: docs/PLUGIN-DEVELOPMENT-GUIDE.md

Quick Command Reference

| Command | Purpose | |---------|---------| | codesorb parse <path> | Analyze repository structure | | codesorb graph <path> | Visualize dependency graph | | codesorb analyze-repos <paths> | Multi-repo analysis with business context | | codesorb interactive | Conversational REPL exploration | | codesorb mcp-server | Start MCP server for AI agents |

See FEATURES-AT-A-GLANCE.md for all 27 CLI commands with examples.

Key Facts

• 91% cheaper than raw code — Measured across Django, Rails, Spring Boot, K8s, NestJS, Tokio
• 100% accurate AST facts — Tree-sitter verified, file:line citations, zero hallucinations
• 54 files/sec parsing speed — Error-tolerant with proper error messages
• LLM fallback for unsupported languages — PHP, C#, Swift, etc. (with API key)

Documentation

Getting Started:

• Getting Started — 5-minute tutorial
• Features at a Glance — All 24 commands
• FAQ — Common questions
• Use Cases — Real-world examples

Language Guides:

• TypeScript / JavaScript
• Python
• Java
• Kotlin
• Go
• Rust
• Ruby
• Polyglot

Integrations & Skills:

• IDE Integration — VS Code, Cursor, Copilot, Claude Code setup
• Plugin Development — Write and publish custom skills
• Skills Reference — All 25 skills with mental models
• Integration Guide — Claude, Cursor, Copilot, MCP setup
• MCP Server — MCP setup and server configuration
• Plugin Architecture — Claude Code plugin
• Skills Composition — Multi-skill workflows
• LLM Skills Guide — Optional prepare/apply LLM enrichment
• Execution Plan Guide — JSON execution layer (v0.5.2+)

Reference:

• MCP Tools Reference — All 30 MCP tools with schemas (v0.5.2+)
• CLI Reference — Complete command guide
• API Reference — Programmatic API
• Architecture — 80/20 model, MCP design, sacred principles
• Architecture (detailed) — System design
• Dependency Graphs — Graph analysis
• Examples — Runnable examples

Advanced & Operations:

• Performance Tuning — Large-scale analysis
• CI/CD Integration — GitHub Actions, GitLab CI, etc.
• Multi-Repo Analysis — Cross-repository analysis
• Docker — Container setup and remote MCP configuration
• Troubleshooting — Error resolution
• Observability — Tracing and metrics

Reports & Exports:

• Export JSON architecture data today: codesorb_export MCP tool
• Generate Markdown architecture reports: use the example-report-generator skill (/codesorb:example-report-generator)
• Structured codesorb generate-report CLI command planned for Phase 5 (Reports/CLI/Compliance)

Contributing:

• CONTRIBUTING.md — Contribution guidelines
• Contributor Roadmap — For new contributors
• Architecture for Contributors — Code walkthrough

See docs/INDEX.md for complete documentation navigation.

Development

npm install            # install dependencies
npm run build          # compile TypeScript
npm test               # run all tests
npm run typecheck      # type-check only

See CONTRIBUTING.md and docs/contributing/DEVELOPMENT-SETUP.md for contributor setup.

License

Apache 2.0 — see LICENSE.

Contributing

See CONTRIBUTING.md for guidelines.

CI Test

Trigger benchmarks workflow