codesight

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

Zero dependencies. AST precision. 30+ framework detectors. 14 ORM parsers. 14 MCP tools. Onenpxcall.

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 byKailesk Khumar, founder ofHouseofMVPsandKailxlabs

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

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

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

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

.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

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

# 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)

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

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

CI: addnpx codesight --mode knowledgealongside your existing codesight step. Both files stay current on every push.

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.

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 = readingindex.mdat 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 scaneliminates 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 —--wikieliminates 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

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.

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.

¹ 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.

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

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

SaaS A's 5 missed routes use dynamicurl.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.

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

- 5 affected filesacross API, auth, and server layers
- All routesthat touch the database
- 12 affected models(complete schema)
- BFS depth:3 hops through the import graph

Measured across the three benchmark projects:

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.

.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 frombuilt-in pluginsthat scan the dotfile directories (.github/,.husky/,.claude/) the main pass skips. They run automatically and stay silent on projects without those files — so they only ever add a section when there's something to report.

When TypeScript is installed in the project being scanned, codesight uses the actual TypeScript compiler API to parse your code structurally. No regex guessing.

AST detection is reported in the output:

Analyzing... done (AST: 60 routes, 18 models, 16 components)

No configuration needed. If TypeScript is in yournode_modules, AST kicks in automatically. Works with npm, yarn, and pnpm (including strict mode). Falls back to regex for non-TypeScript projects or frameworks without AST support.

AST-supported frameworks:Express, Hono, Fastify, Koa, Elysia (route chains + middleware), NestJS (decorator combining + guards), tRPC ( router nesting + procedure types), Drizzle (field chains + relations), TypeORM (entity decorators), React (props from interfaces + destructuring + forwardRef/memo).

By default codesight uses its built-in extractors (AST for TypeScript, regex for everything else). Opt in with--native-astto specify thatWebAssembly pluginsshould be used to acquire full-AST precision for non-TypeScript source files:

npx codesight --native-ast # use every discovered plugin (additive) npx codesight --native-ast=rust,go # only these languages (authoritative for their files) npx codesight --native-ast=none # force off (overrides config) npx codesight --native-ast-strict # like --native-ast, but fail if a named plugin is missing npx codesight --plugin-dir ./wasm # extra directory to search for plugins

Dispatch to WASM plugins islanguage-driven: each plugin self-describes (via adescribe()export) the file extensions it handles, soanylanguage works — not just the ones with built-in detectors. Where no plugin handles a file, built-in extraction stands; with--native-astunset, behavior is byte-identical to existingcodesightbehavior.

codesight's npm package ships no plugins— they are separate, opt-in artifacts. The project publishes prebuilt reference plugins (Rust/syn, Python/ruff, Go/go/parser) as checksummed GitHub release assets; drop the ones you want to use into~/.codesight/plugins/(or point--plugin-dirat them), then enable them with--native-ast. Alternately, you may build your own plugin forany languageagainst the contract.

→ Full contract, discovery rules, and download/install steps:docs/wasm-plugins.md.

// codesight.config.js export default {disableDetectors: ["cicd", "githooks", "skills"]};

Terraform is opt-in, not auto-loaded — it deliberately reaches outside the scanned directory (sibling../infrastructurerepos) and is most useful with an explicit service name, so it stays off until you ask for it:

// codesight.config.js import {createTerraformPlugin} from "codesight/plugins/terraform"; export default {plugins: [createTerraformPlugin({infraPath: "../infra"})]};

Not just paths. Methods, URL parameters, what each route touches (auth, database, cache, payments, AI, email, queues), and where the handler lives. Detects routes across 30+ frameworks automatically.

- GET /api/users/me [auth, db, cache] - PUT /api/users/me [auth, db] - POST /api/projects [auth, db, payment] - GET /api/projects/:id params(id) [auth, db] - POST /webhooks/stripe [db, payment] - GET /health`

### user - id: text (pk) - name: text (required) - email: text (unique, required) - role: text (default, required) - stripeCustomerId: text (fk) ### project - id: uuid (default, pk) - ownerId: text (fk, required) - name: text (required) - settings: jsonb (required) - _relations_: ownerId -> user.id

## Most Imported Files (change these carefully) - src/types/index.ts — imported by 20 files - src/db/index.ts — imported by 12 files - src/lib/auth.ts — imported by 8 files - src/lib/cache.ts — imported by 6 files - src/lib/env.ts — imported by 5 files

Blast Radius: src/db/index.ts Depth: 3 hops Affected files (10): src/api/users.ts src/api/projects.ts src/api/webhooks.ts src/auth/session.ts src/jobs/notifications.ts src/server.ts src/auth/index.ts src/jobs/cron.ts src/cli.ts src/index.ts Affected routes (33): GET /api/users/me — src/api/users.ts POST /api/projects — src/api/projects.ts POST /webhooks/stripe — src/api/webhooks.ts ... Affected models: user, session, account, project, subscription, notification, audit_log

- DATABASE_URL required — .env.example - REDIS_URL (has default) — .env.example - STRIPE_SECRET_KEY required — src/lib/payments.ts - STRIPE_WEBHOOK_SECRET required — .env.example - RESEND_API_KEY required — .env.example - JWT_SECRET required — src/lib/auth.ts

Token Savings Breakdown: ┌──────────────────────────────────────────────────┐ │ What codesight found │ Exploration cost │ ├──────────────────────────────┼────────────────────┤ │ 38 routes │ ~15,200 tokens │ │ 12 schema models │ ~ 3,600 tokens │ │ 0 components │ 0 tokens │ │ 30 library files │ ~ 6,000 tokens │ │ 12 env vars │ ~ 1,200 tokens │ │ 5 middleware │ ~ 1,000 tokens │ │ 20 hot files │ ~ 3,000 tokens │ │ 138 files (search overhead) │ ~11,040 tokens │ ├──────────────────────────────┼────────────────────┤ │ codesight output │ ~ 3,936 tokens │ │ Manual exploration (1.3x) │ ~46,020 tokens │ │ SAVED PER CONVERSATION │ ~42,084 tokens │ └──────────────────────────────┴────────────────────┘

codesight treats Roku channels as first-class projects. Themanifestfile at the channel root anchors detection — the same file Roku itself uses to identify a channel, so zero configuration is needed for the common case.

Standard single-channel layout(about 90% of Roku repos, matches the Roku docs' getting-started template and projects likerokucommunity/brighterscript-template):

/ manifest source/ # Main.brs + shared .brs libraries components/ # .xml + paired .brs component handlers images/

codesight also recognizes therokucommunity/brighterscript-templatelayout where the channel lives undersrc/and the root carries absconfig.jsonfor BrighterScript tooling.

Multi-channel monorepo layout(less common — used by larger codebases that ship several branded channels from one repo withroku-deploy+gulpto merge a sharedcommon/layer with per-channel assets at build time):

/ package.json # depends on roku-deploy, gulp gulpfile.js src/apps/ common/ # shared layer, merged into every channel at build creatorA/ manifest creatorB/ manifest`