Codesight

Your AI assistant wastes thousands of tokens every conversation just figuring out your project. codesight fixes that in one command.

4,000+ downloads and counting.

Zero dependencies. AST precision. 30+ framework detectors. 13 ORM parsers. 13 MCP tools. One npx call.

Works with TypeScript, JavaScript, Python, Go, Ruby, Elixir, Java, Kotlin, Rust, PHP, Dart, Swift, C#, and BrightScript/BrighterScript (Roku). TypeScript projects get full AST precision. Everything else uses battle-tested regex detection across the same 30+ frameworks.

[](https://www.npmjs.com/package/codesight) [](https://www.npmjs.com/package/codesight) [](https://www.npmjs.com/package/codesight) [](https://github.com/Houseofmvps/codesight/stargazers) [](LICENSE)

---

[](https://x.com/kaileskkhumar) [](https://www.linkedin.com/in/kailesk-khumar) [](https://houseofmvps.com) [](https://www.kailxlabs.co)

Built by Kailesk Khumar, founder of HouseofMVPs and Kailxlabs

Also: ultraship (39 expert skills for Claude Code) · claude-rank (SEO/GEO/AEO plugin for Claude Code)

---

0 dependencies · Node.js >= 18 · 27 tests · 13 MCP tools · MIT · tested on 25+ OSS projects across 14 languages

Works With

Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Windsurf, Cline, Aider, and anything that reads markdown.

Install

npx codesight

That's it. Run it in any project root. No config, no setup, no API keys.

npx codesight --wiki                       # Generate wiki knowledge base (.codesight/wiki/)
npx codesight --init                       # Generate CLAUDE.md, .cursorrules, codex.md, AGENTS.md
npx codesight --open                       # Open interactive HTML report in browser
npx codesight --mcp                        # Start as MCP server (13 tools) for Claude Code / Cursor
npx codesight --blast src/lib/db.ts        # Show blast radius for a file
npx codesight --profile claude-code        # Generate optimized config for a specific AI tool
npx codesight --benchmark                  # Show detailed token savings breakdown
npx codesight --native-ast                 # Opt-in: use user-supplied WASM AST plugins (see docs/wasm-plugins.md)
npx codesight --mode knowledge             # Map knowledge base (.md notes → KNOWLEDGE.md)
npx codesight --mode knowledge ~/vault     # Map Obsidian vault, ADRs, meeting notes, retros

Wiki Knowledge Base (v1.6.2)

Inspired by Karpathy's LLM wiki pattern — but compiled from AST, not an LLM. Zero API calls. 200ms.

npx codesight --wiki

Generates .codesight/wiki/ — a persistent knowledge base of your codebase that survives across every session:

.codesight/wiki/
  index.md      — catalog of all articles (~200 tokens) — read this at session start
  overview.md   — architecture, subsystems, high-impact files (~500 tokens)
  auth.md       — auth routes, middleware, session flow
  payments.md   — payment routes, webhook handling, billing flow
  database.md   — all models, fields, relations, high-impact DB files
  users.md      — user management routes and related models
  ui.md         — UI components with props
  log.md        — append-only record of every wiki operation

Why this cuts token usage further:

Instead of loading the full 5K token context map every conversation, your AI reads one targeted article:

| Question | Without wiki | With wiki | |---|---|---| | "How does auth work?" | ~12K tokens (reads 8+ files) | ~300 tokens (auth.md) | | "What models exist?" | ~5K tokens (CODESIGHT.md) | ~400 tokens (database.md) | | New session start | ~5K tokens (full reload) | ~200 tokens (index.md) |

Persistent across sessions. The wiki lives in .codesight/wiki/, committed to git. Every new Claude Code, Cursor, or Codex session starts with full codebase knowledge from the first message.

Auto-regenerates. Use --watch to keep the wiki current as you code. Use --hook to regenerate on every commit.

3 new MCP tools for wiki access:

| Tool | What it does | |---|---| | codesight_get_wiki_index | Get the wiki catalog (~200 tokens) at session start | | codesight_get_wiki_article | Read one article by name: auth, database, payments, etc. | | codesight_lint_wiki | Health check: orphan articles, missing cross-links, stale content |

The key difference from general-purpose wiki tools: codesight already knows your routes, schema, blast radius, and middleware from AST — no LLM needed to extract code structure. The wiki is a narrative layer on top of data your codebase already contains.

Knowledge Mode (v1.9.3)

Not just code — your decisions, meeting notes, ADRs, and retrospectives carry as much context as the codebase itself. --mode knowledge maps them the same way codesight maps code.

npx codesight --mode knowledge              # Scan current directory for .md files
npx codesight --mode knowledge ~/vault      # Scan an Obsidian vault
npx codesight --mode knowledge ./docs       # Scan a project docs folder

Outputs .codesight/KNOWLEDGE.md — a compact AI context primer:

# Knowledge Map — my-project
> 47 notes · 12 decisions · 8 open questions · 2025-09-01 → 2026-04-01

## Key Decisions (12)
- [2026-03-20] Going with Polar.sh over Stripe Connect — simpler global payments
- [2026-03-15] Decided to use PostgreSQL — better JSON support and Drizzle compatibility
- [2026-02-10] Will use Redis for rate limiting — BullMQ already in stack

## Open Questions (8)
- Should we support PayPal later?
- When do we start the Stripe marketplace application?

## Note Index (47)

### Decision Records (8)
- `decisions/adr-002-payments.md` — 2026-03-20 — Going with Polar.sh over Stripe Connect
- `decisions/adr-001-database.md` — 2026-03-15 — We need a relational database...

### Meeting Notes (14)
### Retrospectives (6)
### Specs & PRDs (5)
### Research (4)

What it detects automatically:

| Note type | Signals | |---|---| | Decision records | ADR format (## Decision), "decided to", "going with", "chose X over Y" | | Meeting notes | Attendees:, Action items:, filename: standup, sync, 1on1 | | Retrospectives | "What went well", "Stop doing", filename: retro, retrospective | | Specs / PRDs | ## Goals, ## Requirements, filename: prd, spec, roadmap | | Research | filename: research, analysis, benchmark, comparison | | Session logs | filename: session, daily, weekly |

Supports:

• Obsidian vaults (YAML frontmatter, [[backlinks]], #tags)
• Notion exports (.md files with frontmatter)
• ADR tooling (adr-tools, Log4brains, raw markdown)
• Any folder of markdown files

Used together:

Read .codesight/CODESIGHT.md   → what the code does
Read .codesight/KNOWLEDGE.md   → why decisions were made

CI: add npx codesight --mode knowledge alongside your existing codesight step. Both files stay current on every push.

Benchmarks (Real Projects)

Every number below comes from running codesight on real production codebases — both small SaaS projects (v1.6.2) and large open-source platforms with 4K–10K+ files (v1.6.4). Output tokens are measured from actual file size (chars / 4). Exploration tokens are estimated from what was extracted — routes × 400, models × 300, components × 250, etc. Route counts and model counts are cross-checked against actual source files.

Three-Level Token Reduction

codesight saves tokens at two distinct layers. The wiki (v1.6.2) adds a second layer on top of the base savings:

| Project | Manual exploration | codesight scan | codesight --wiki (targeted) | Total reduction | |---|---|---|---|---| | SaaS A | 46,020 tokens | 3,936 tokens (11.7x) | ~550 tokens | 83.7x | | SaaS B | 26,130 tokens | 3,629 tokens (7.2x) | ~440 tokens | 59.4x | | SaaS C | 47,450 tokens | 4,162 tokens (11.4x) | ~360 tokens | 131.8x |

Average combined reduction: 91x. The wiki's "targeted" number = reading index.md at session start (~200 tokens) + one relevant article (~160-350 tokens depending on project). Your AI never loads the full context map for targeted questions.

The two savings layers are independent and compound:

Layer 1 — codesight scan eliminates manual file exploration. Instead of your AI running glob/grep/read across 40-138 files to understand the project, it reads one pre-compiled map.

Layer 2 — --wiki eliminates loading the full map for every question. Instead of loading 3K-5K tokens of full context at session start, your AI reads a 200-token index and pulls the one relevant article (~160-350 tokens) for each question.

Without codesight:   AI reads 26K-47K tokens per session exploring files
With codesight:      AI reads ~3K-5K tokens (the compiled map)
With --wiki:         AI reads ~200 tokens at start + ~300 per targeted question

Base Scan Results

| Project | Stack | Files | Routes | Models | Components | Output Tokens | Exploration Tokens | Savings | Scan Time | |---|---|---|---|---|---|---|---|---|---| | SaaS A | Hono + Drizzle | 138 | 38 | 12 | 0 | 3,936 | 46,020 | 11.7x | 186ms | | SaaS B | Hono + Drizzle, 3 workspaces | 53 | 17 | 8 | 10 | 3,629 | 26,130 | 7.2x | 201ms | | SaaS C | FastAPI + MongoDB | 40 | 56 | 0 | 0 | 4,162 | 47,450 | 11.4x | 890ms |

SaaS C has 0 models because it uses MongoDB — no SQL ORM declarations for codesight to parse. This is correct detection, not a false negative.

Multi-Language OSS Benchmark (v1.6.7)

Tested against real open-source codebases spanning every supported language and framework. Output tokens are measured from actual file size. Exploration tokens are estimated (routes×400 + models×300 + components×250 + revisit multiplier). Zero false positives across all tests.

| Language | Stack | Files | Routes | Models | Components | Output tokens | Est. exploration | Savings | |---|---|---|---|---|---|---|---|---| | TypeScript · Next.js | Next.js + tRPC + Prisma · 110+ workspaces | 7,509 | 479 | 173 | 1,309 | 158,660 | ~1,485,000 | ~9x | | TypeScript · NestJS | NestJS + TypeORM + Mongoose | 162 | 19 | 8 | 0 | 5,300 | ~67,500 | ~12.7x | | TypeScript · Hono | Hono | — | 8 | 0 | 0 | — | — | ✓ | | TypeScript · Remix | Remix + Prisma | 36 | 11 | 0 | 9 | — | — | ✓ | | TypeScript · SvelteKit | SvelteKit | — | 0³ | 0 | 23 | — | — | ✓ | | TypeScript · Nuxt | Nuxt | 141 | 8 | 0 | 64 | — | — | ✓ | | JavaScript · Express | Express + Mongoose | 51 | 10 | 5 | 0 | 1,241 | ~20,800 | ~17x | | Ruby · Rails | Rails + ActiveRecord | 4,172 | 607 | 116 | 0 | 21,711 | ~386,100 | ~17.8x | | PHP · Laravel | Laravel + Eloquent | 3,896 | 652 | 59 | 0 | 30,739 | ~493,285 | ~16x | | Python · Django | Django + pyproject.toml | 4,232 | 7¹ | 56 | 0 | 83,842 | ~631,020 | ~7.5x | | Python · Flask | Flask + SQLAlchemy | 30 | 12 | 5 | 0 | 1,148 | ~16,705 | ~14.5x | | Python · FastAPI | FastAPI + SQLModel (monorepo) | 143 | 21 | 2 | 36 | 2,487 | ~38,090 | ~15.3x | | Elixir · Phoenix | Phoenix + Ecto | 1,406 | 198 | 54 | 0 | 9,589 | ~152,100 | ~15.9x | | Go · Gin | Gin + GORM (enterprise app) | 388 | 202 | 169 | 0 | 15,266 | ~262,730 | ~17.2x | | Go · Echo | Echo | — | 7 | 0 | 0 | — | — | ✓ | | Go · Fiber | Fiber | — | 5 | 0 | 0 | — | — | ✓ | | Rust · Actix | actix-web | 528 | 30 | 0 | 0 | 1,355 | ~27,170 | ~20x | | Rust · Axum | Axum | — | 6 | 0 | 0 | — | — | ✓ | | C# · ASP.NET | ASP.NET Core + Entity Framework Core | 256 | 13 | 7 | 0 | 5,126 | ~63,570 | ~12.4x | | Java · Spring | Spring Boot + Java (Maven) | 47 | 16 | 0 | 0 | 319 | ~13,208 | ~41x² | | Swift · SwiftUI | SwiftUI | 388 | 0 | 0 | 62 | 7,499 | ~76,830 | ~10.2x | | Swift · Vapor | Vapor backend | 294 | 81 | 0 | 0 | 6,146 | ~95,160 | ~15.5x | | Dart · Flutter | Flutter + go_router | 204 | 10 | 0 | 89 | 8,500 | ~86,125 | ~10.1x |

¹ Django project is GraphQL-first — 7 REST utility endpoints detected accurately, 0 false positives. ² High ratio on small boilerplate: Spring Boot route metadata compresses very well. ³ SvelteKit RealWorld app uses page routes (+page.svelte), not JSON API endpoints (+server.ts). 0 routes is correct.

How exploration tokens are estimated: routes×400 + models×300 + components×250 + hot_files×150 + env_vars×30, times a 1.3 revisit multiplier, minus the output size. This approximates what an AI would spend asking "what routes exist?", "show me the schema", etc. in a manual exploration session. Output token count is the actual measured file size.

Wiki Breakdown (v1.6.2)

| Project | Full CODESIGHT.md | Wiki index only | Index + 1 article | Wiki articles generated | |---|---|---|---|---| | SaaS A | 3,936 tokens | ~200 tokens | ~550 tokens | 9 | | SaaS B | 3,629 tokens | ~200 tokens | ~440 tokens | 11 | | SaaS C | 4,162 tokens | ~200 tokens | ~360 tokens | 17 |

"How does auth work?" — without wiki: loads 3,945 tokens. With wiki: reads auth.md (~350 tokens). 11x improvement per targeted question, 84x total vs manual.

Detection Accuracy

Verified against actual source files. Route counts cross-checked against route definitions; schema models cross-checked against ORM table declarations.

| Project | Route Recall | Schema Recall | False Positives | Detection Method | |---|---|---|---|---| | SaaS A | 38/43 (88%) | 12/12 (100%) | 0 | Schema: AST (Drizzle), Routes: AST (Hono) | | SaaS B | 17/17 (100%) | 8/8 (100%) | 0 | Full AST (Hono + Drizzle + React) | | SaaS C | 56/59 (~95%) | 0/0 (correct) | 0 | AST (FastAPI + MongoDB) |

SaaS A's 5 missed routes use dynamic url.match(/pattern/) inside request handlers — a developer pattern that static analysis cannot resolve at scan time. This is an inherent limit of static analysis, not a framework gap. SaaS C missed an estimated 3 of 59 FastAPI routes. Zero false positives across all three projects.

Blast Radius Accuracy

Tested on a production SaaS: changing the database module correctly identified:

• 5 affected files across API, auth, and server layers
• All routes that touch the database
• 12 affected models (complete schema)
• BFS depth: 3 hops through the import graph

What Gets Detected

Measured across the three benchmark projects:

| Detector | SaaS A (138 files) | SaaS B (53 files) | SaaS C (40 files) | |---|---|---|---| | Routes | 38 | 17 | 56 | | Schema models | 12 | 8 | 0 | | Components | 0 | 10 | 0 | | Env vars | 12 | 7 | 15 | | Hot files | 20 | 20 | 20 |

---

How It Works

codesight runs all 8 detectors in parallel, then writes the results as structured markdown. The output is designed to be read by an AI in a single file load.

What It Generates

.codesight/
  CODESIGHT.md     Combined context map (one file, full project understanding)
  routes.md        Every API route with method, path, params, and what it touches
  schema.md        Every database model with fields, types, keys, and relations
  components.md    Every UI component with its props
  libs.md          Every library export with function signatures
  config.md        Every env var (required vs default), config files, key deps
  middleware.md    Auth, rate limiting, CORS, validation, logging, error handlers
  graph.md         Which files import what and which break the most things if changed
  cicd.md          GitHub Actions / CircleCI pipelines (when present)
  githooks.md      lefthook / husky / raw .git/hooks (when present)
  skills.md        .claude/commands + .claude/skills (when present)
  report.html      Interactive visual dashboard (with --html or --open)

The last three come from **built-in plugins

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Houseofmvps
• Source: Houseofmvps/codesight
• License: MIT
• Homepage: https://github.com/Houseofmvps/codesight

Install and usage instructions live in the source repository linked above.