codesight: A Static Context Map for AI Coding Assistants

The token tax codesight is trying to remove

Every new assistant session begins with the same overhead. The model reads files to work out where routes live, which ORM models exist, how authentication is wired, and which files a change will touch. None of that work is the task you actually asked for, and it repeats on the next session because the assistant retains nothing between conversations. codesight's README frames the problem in exactly those terms: the assistant wastes thousands of tokens every conversation just figuring out the project. The fix is a generated markdown artefact that describes the repository once, so the assistant reads a summary instead of eight source files. The audience is developers using Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Windsurf, Cline or Aider on a repository large enough that orientation costs real money. On a small project the generated map may cost more tokens to read than simply opening the files, which is the boundary worth keeping in mind.

Static analysis, not model inference

codesight is a TypeScript CLI with zero runtime dependencies, requiring Node.js 18 or later. Its distinguishing design choice is that the context map is compiled from the repository itself rather than written by a language model. TypeScript projects get full AST precision; the README is explicit that other languages use regex detection across the same framework and ORM detectors. The pipeline is: walk the project, detect frameworks and ORM models, extract routes, middleware, schema fields and relations, then emit markdown. Outputs include CODESIGHT.md as the base context map, an optional .codesight/wiki/ directory of per-topic articles (index.md, overview.md, auth.md, payments.md, database.md, users.md, ui.md, log.md), a KNOWLEDGE.md primer in knowledge mode, and per-tool config files via --init. Because no model is called, the run is deterministic and free, and the README claims a 200ms figure for wiki generation. That is a claim from the project, not something verified here. The trade-off is that a regex detector can misread dynamic dispatch, metaprogramming or unusual routing conventions, and the emitted map will be confidently wrong rather than silent.

Getting it running and what each flag writes

The entry point is a single npx call run from the project root. `npx codesight` produces the base context map with no configuration, API keys or setup, according to the README. From there the flags branch. `npx codesight --wiki` writes the .codesight/wiki/ knowledge base. `npx codesight --init` generates CLAUDE.md, .cursorrules, codex.md and AGENTS.md, which is the flag that matters if you want per-assistant instruction files rather than one shared map. `npx codesight --mcp` starts the process as an MCP server exposing 14 tools for Claude Code and Cursor. `npx codesight --blast src/lib/db.ts` shows the blast radius for a single file, useful before refactoring. `npx codesight --profile claude-code` emits a config tuned to one assistant. `npx codesight --benchmark` prints a token-savings breakdown. `npx codesight --open` renders an interactive HTML report. `npx codesight --native-ast` is opt-in and pulls AST plugins for additional languages, documented in docs/wasm-plugins.md. `npx codesight --mode knowledge` maps markdown notes instead of code, and accepts a path such as `~/vault` or `./docs`, writing .codesight/KNOWLEDGE.md. The README also mentions --watch and --hook for keeping the wiki current during editing and on commit, though the exact hook installation mechanics are not spelled out in the material available here.

The wiki layer and why it is read selectively

The wiki is the part of codesight that most changes how a session starts. Instead of loading a full context map, the assistant reads one article whose topic matches the question. The README's own comparison table puts a session start at roughly 200 tokens reading index.md, against roughly 5K tokens for a full reload of CODESIGHT.md, and answers to a question like how authentication works at roughly 300 tokens from auth.md against roughly 12K tokens spent reading eight or more files. Those numbers come from the project and should be treated as illustrative rather than measured. The mechanism that makes selective reading possible is three MCP tools: codesight_get_wiki_index returns the catalogue, codesight_get_wiki_article fetches a named article, and codesight_lint_wiki reports orphan articles, missing cross-links and stale content. That lint tool is the honest admission that a generated wiki drifts: if you edit routing by hand and never regenerate, auth.md keeps describing the old shape. The README credits Karpathy's LLM wiki pattern as inspiration while noting the articles are compiled from AST rather than generated by a model, which is the substantive difference from wiki tools that summarise source by inference.

Knowledge mode and the files it will pick up

`npx codesight --mode knowledge` treats markdown as a second source of context. It scans the current directory, a docs folder, or an Obsidian vault, and writes .codesight/KNOWLEDGE.md as a compact primer. The README's example output shows a header line counting notes, decisions and open questions with a date range, followed by a Key Decisions section listing dated entries such as a payments provider choice. This is a different product from the code map, and it inherits different risks. The scanner reads .md files wherever you point it, so pointing it at a personal vault means personal notes become a committed artefact unless you exclude them. The README does not document ignore rules or a config file for excluding paths, which is a gap if your vault mixes work and private material. The value proposition is real for teams that keep architecture decision records: those decisions are context the assistant otherwise never sees, and they are cheap to render as a dated list.

Where codesight is the wrong tool

The clearest limitation is language coverage depth. TypeScript gets AST precision; JavaScript, Python, Go, Ruby, Elixir, Java, Kotlin, Rust, PHP, Dart, Swift, C#, and BrightScript/BrighterScript are handled by regex detection, per the README. On a Python service that builds routes dynamically, or a Ruby codebase leaning on metaprogramming, a regex pass can miss or misattribute routes, and the resulting map will look authoritative while being incomplete. The second limitation is that the map is a snapshot. Anything generated at a point in time goes stale, and the project's answer is --watch, --hook, or re-running the command; there is no evidence in the material of a CI check that fails when the wiki diverges from the code, only the lint tool that reports staleness. Third, committing generated markdown means merge conflicts on every branch that regenerates it, and the README states the wiki is intended to be committed to git. Fourth, the token-savings figures are the project's own and are not reproduced here. If your repository is small enough to fit in a single context window, the generated map adds a file to read rather than removing several.

How it compares with repomix and aider's repo map

The nearest alternative in kind is repomix, which packs a repository into a single AI-friendly file. The approach differs in a way that matters. repomix concatenates source, so the assistant receives the actual code and decides what to read; codesight summarises structure and expects the assistant to fetch detail through MCP tools or by opening files itself. Concatenation preserves ground truth, at the cost of a large payload. Summarisation is cheaper per session but introduces an extraction step that can be wrong, particularly outside TypeScript. Aider's repo map takes a third route: it ranks symbols by relevance to the current task using a graph over definitions and references, producing a focused map per query rather than a fixed set of articles. codesight's wiki is topic-partitioned and static, which is simpler to reason about and easier to commit, but it cannot re-rank itself for the question at hand. Choose repomix when fidelity matters more than tokens, aider's map when you want per-query relevance, and codesight when you want a durable, reviewable artefact that lives in the repository and is served through MCP.

Licence, maintenance and what to check before adopting

codesight is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and licence text are retained. This is not legal advice; if you vendor the tool or ship generated artefacts inside a product, read the LICENSE file in the repository and confirm your own obligations. Maintenance cost is mostly the regeneration loop: the wiki is meant to be committed, so every structural change to routes, models or middleware is a candidate for a re-run, and the README offers --watch and --hook as the automated answers. The material does not describe a versioned migration path for the generated file formats, and no releases were retrieved, so treat the output schema as something that can change between versions. Before adopting, verify four concrete things in your own repository: run `npx codesight` and inspect exactly which files appear at the root; run `npx codesight --wiki` and read auth.md and database.md against your actual code; run `npx codesight --blast` on a file you know is heavily imported and check the radius matches your mental model; and decide whether .codesight/ belongs in git or in .gitignore, because the README's persistence argument assumes the former.

Editorial conclusion

Adopt codesight if your repository is TypeScript or JavaScript and you are already paying the token cost of re-explaining the codebase to Claude Code, Cursor or Codex at the start of each session. Do not adopt it expecting deep analysis of a Python or Go monorepo, because the README states those languages fall back to regex detection rather than AST parsing. Before committing the generated files, verify two things in your own tree: what `npx codesight` actually writes at the root, and whether the wiki articles for your highest-traffic modules (auth, payments, database) describe your code accurately rather than merely listing symbols.

Official sources

1. Houseofmvps/codesight on GitHub
2. Issues
3. License: MIT
4. Project website
5. README