github.com/Houseofmvps/codesight @main

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. 14 ORM parsers. 14 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.

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 · 145 tests · 14 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 (14 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: AST plugins for more languages (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:

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:

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:

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:

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

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.