codesight

codesight is a zero-dependency command-line tool that scans a project and writes what it finds into .codesight/ as structured markdown: one combined context map, plus a file each for routes, schema, components, libraries, env vars, middleware and the dependency graph, plus files for CI/CD, git hooks and Claude Code skills. The claim is about tokens, and install is npx codesight. Eight detectors run in parallel and the result is sized for one file load, so Claude Code, Cursor, Copilot, Codex, Windsurf, Cline and anything else that reads markdown starts from the project’s shape rather than discovering it with glob and grep. Around that core sit a wiki mode that splits the map into articles, a knowledge mode for a folder of notes, an MCP server with fourteen tools and per-session caching, a blast-radius query over the import graph, and --init, which writes CLAUDE.md, .cursorrules, .github/copilot-instructions.md, codex.md and AGENTS.md. Every savings figure is the project’s own, from benchmarks on three SaaS projects and a longer table covering the supported languages.

Who built itThe account that owns the repository, Houseofmvps, accounts for 93 of its 190 commits, recorded under two git names — 79 as Houseofmvps and 14 as Kailesk Khumar. The README names him as the founder of HouseofMVPs and Kailxlabs, with links to an X handle, a LinkedIn profile and both company sites, and package.json gives the same name with an address at houseofmvps.com and kailxlabs.co as his page. aguerlain-lr contributed 14 commits, Fyb3roptik six and the-wondersmith five, with thirteen further accounts appearing in the contributor list. The README also points at two earlier projects from the same account: a set of expert skills for Claude Code and an SEO plugin for it.

1. 01

   Five months, 190 commits, and no releases at all

   The repository was created on 2026-04-04, and its oldest commit, the same day, already carries a version: “v1.0.0: codesight — see your codebase clearly”. The monthly shape is steep then flat — 149 commits in April, 12 in May, 22 in June, 7 in July — and the newest commit is dated 2026-07-27, message “chore: update AI context map [skip ci]”. Between that date and October 2026 no commits land at all, though issues keep arriving: one on 2026-08-13 about FastAPI router prefixes, a pull request on 2026-09-08 about Slack’s reserved mention keywords. That gap is why this record is filed maintained rather than active. The version has to be assembled by hand, because the repository has neither releases nor tags — nothing marks one except commit messages, npm publishes and replies to issues. Versions named in the material run from that v1.0.0 to v1.19.0, which package.json carries and the maintainer cites while closing four bug reports on 2026-07-27; the README’s section headings are pinned to v1.6.2, v1.6.4, v1.6.7 and v1.9.3. Around it sit 1,410 stars, 123 forks, 6 watchers, 3 open issues, thirty issues and pull requests in total, and fifteen contributing accounts. The README banner claims 4,000+ downloads and 149 tests, and its first line states the proposition: AST precision, 30+ framework detectors, 14 ORM parsers, 14 MCP tools, one npx call.

2. 02

   What the output is, and the repository that eats it

   A normal scan writes .codesight/CODESIGHT.md plus one file per detector, three of which are built-in plugins reading the dotfile directories the main pass skips — .github/workflows, .circleci, .husky and .claude/. The project commits its own map, so the artifact reads as shipped: CODESIGHT.md at 20,893 bytes, libs.md at 12,996, graph.md at 2,936, plus files for routes, config, events, CI/CD, coverage, middleware and a wiki/ directory of ten more. A GitHub Actions workflow runs npx codesight@latest --wiki on every push and commits whatever changed as codesight-bot under a fixed message, chore: update AI context map [skip ci]; that account holds 54 of the 190 commits, just over a quarter of the history. On pull requests the same workflow posts the first fifty lines of CODESIGHT.md as a comment. The self-scan is candid about what it cannot see: the map reports the stack as raw-http | none | unknown | typescript, 0 models and 0 components, 68 library files and 60% test coverage, and four routes a repository with no server does not have — ALL /path, ALL /api, ALL /health and GET /api/users, every one tagged [inferred], the marker the generated wiki index itself calls regex detection that may have lower precision. The same wiki lists required env vars whose names live in the repository’s test fixtures and in its own detector pattern tables.

3. 03

   The token numbers are the project measuring itself

   Every savings figure in the README is the project’s own, and the README says how. Output tokens are measured from actual file size at four characters per token. Exploration tokens are estimated from what was extracted — routes × 400, models × 300, components × 250, hot files × 150, env vars × 30, times a 1.3 multiplier for revisiting files, minus the output size — which the README calls conservative. On three production SaaS projects: 46,020 of manual exploration against a 3,936-token map (11.7x), 26,130 against 3,629 (7.2x) and 47,450 against 4,162 (11.4x), for a self-reported average combined reduction of 91x once the wiki is read instead of the map. A second table runs the same measurement across open-source codebases in every supported language, from a 7,509-file Next.js workspace at about 9x to a 47-file Spring Boot project at about 41x, and the comparison table claims 7x to 12x for the base scan and 60x to 131x with targeted wiki queries. A footnote records a developer checking Claude Code at 40–70K tokens on the same projects. Two outside numbers sit against it. Issue #31 is a user whose monorepo produced ~221,169 tokens, which became the hierarchical monorepo mode in v1.12.4. Issue #54 is a user running the bundled evaluation, who found the aggregate reported as 87.0% average F1 while two of five fixtures emitted eleven and ten routes with almost none right.

4. 04

   The community rounds, and what each one changed

   Most of the feature surface arrived as outside pull requests. Fyb3roptik filed and fixed the one that matters most outside web work: the tool reported a Go project as TypeScript, then added a repoType field separating single projects, monorepos, microservices and meta-repositories, then brought Roku in — BrightScript, BrighterScript and SceneGraph, anchored on the plain-text manifest file Roku itself uses, with three new extractors and all eight detectors taught to map screens onto routes and interface contracts onto models. aguerlain-lr reported 221,169 tokens of output and then wrote the hierarchical mode that scans each workspace package on its own, merged as v1.12.4. vakuor reported that dot-folders could not be scanned and that .codesightignore treated negations unlike .gitignore; both were fixed — the first as v1.14.0, the second in commit 0bedd0d, where a negation now matches the exact entry name or relative path only. optimalcharb added Celery as an events framework, and the maintainer moved it out of the Routes row of the README into a new Events row before merging, because a task queue is not a routing framework. neilwashere contributed the skills and git hooks plugins and a Terraform plugin that was closed as already superseded by them. the-wondersmith contributed the five-pull-request stack that turned AST extraction into a plugin system.

5. 05

   One day, four bug reports, one release

   The clearest window on how the project is run is 2026-07-27, when four reports from one user, jonathanjie, were all closed as fixed in v1.19.0 within forty seconds of each other. Each named a file, a version and a cause, and each reply went further than the report. installGitHook hardcoded .git/hooks and only checked that .git existed, so --hook died with ENOTDIR in any git worktree checkout; the fix asks git itself, git rev-parse --git-path hooks, and falls back to .git/hooks only when .git is a real directory. detectTags was called with a whole file’s contents and its pattern list began with a bare /auth/i, so a comment describing a route as public tagged it authenticated; tagging is now scoped to each route’s own slice of the file, and the TypeScript extractor to the registration call plus the bodies of the same-file handlers it names. For every environment variable found by scanning code rather than a .env file, hasDefault was the literal false, because the pattern stopped at the variable name; it now captures the read-site fallback, except for the indexed form that raises KeyError. And --eval was rewritten so an aggregate can no longer hide a collapse: the summary prints the minimum F1 beside the average, calls out any category with true positives at zero and false positives above it, and exits non-zero below a 50% F1 floor.

6. 06

   The two methods the project wrote down

   Two documents carry what a reader would otherwise have to reverse-engineer. docs/wasm-plugins.md, 20,007 bytes, is the contract for the opt-in native-AST plugins: a module must be named codesight-<lang>-ast.wasm and export memory, alloc, dealloc and contractVersion, and report a contract version equal to the host’s, which is 1, or be rejected; capability is detected by export presence, so a plugin handles routes only if it exports parseRoutes. An optional describe() returns a language id and a list of extensions, and dispatch is language-driven, so a language with no built-in extractor works as long as the plugin declares its extensions. Plugins are instantiated once per scan as long-lived reactors under a minimal WASI import object — clock, random, exit and stderr only, with no filesystem or network — and the host stamps the contextual fields it knows while ignoring any it is handed. The npm package ships none; the project publishes Rust, Python and Go builds as checksummed release assets. The second is the evaluation suite: five fixtures, each a repository description paired with expected routes, models, env vars and blast radius, scored for precision, recall and F1. The boundaries are written down too: the generated wiki index lists eight classes of thing it cannot see, from routes registered in a loop to WebSocket handlers and raw SQL tables.