sens

Why Sens?

If you use Claude Code on a subscription, your pain isn't a per-token bill — it's the usage limit and the context window filling up. Every time the agent opens 20 files just to orient itself, it burns your quota and bloats the context (which then compacts and quietly loses memory).

Sens keeps a compact index of your project and serves it to Claude over MCP, so the model asks focused questions instead of reading everything:

"where is login?" · "who uses it?" · "does something like this already exist?" · "what's dead code here?"

One engine, two payoffs:

• 🪙 Fewer tokens / cleaner context → your subscription lasts longer and long sessions stay sharp.

• 🧹 Cleaner code → reuse what already exists instead of duplicating, and surface dead code.

Related MCP server: RepoMap

Contents

• Quick start · What Claude gets · Slash commands · CLI · Dashboard

• Does it actually help? · How it works · Configuration · Dead code · Roadmap · License

Quick start

Add Sens as an MCP server. In your project's .mcp.json (or Claude Code's MCP config):

{
  "mcpServers": {
    "sens": {
      "command": "npx",
      "args": ["-y", "sens-mcp", "mcp"]
    }
  }
}

Or register it once for every project:

claude mcp add sens -s user -- npx -y sens-mcp mcp

That's it. Claude Code launches Sens on demand — no per-project install, no manual server to run. Then just ask Claude naturally: "use sens to map this project", "any dead code? check with sens".

What Claude gets (MCP tools)

Working rules

Sens's MCP server also hands Claude a short set of working rules it follows when writing or changing code — reuse what exists instead of duplicating, keep code minimal but maintainable, and leave nothing orphaned — each tied to the tool that lets it verify the rule (already_exists/find_symbol before writing, dead_code before finishing, who_uses before a rename). They load automatically over MCP; run sens rules to read them, or sens rules --write to drop a SENS_RULES.md you can reference from your CLAUDE.md / AGENTS.md.

Slash commands

Sens also registers prompts, so it shows up in Claude Code's / menu:

CLI

You can also drive Sens yourself:

npx sens-mcp index          # build/update the index (cached by file mtime)
npx sens-mcp map [subdir]   # compact project map
npx sens-mcp find <name>    # where a symbol is defined
npx sens-mcp who <name>     # where a symbol is used
npx sens-mcp outline <file> # a file's signatures, no bodies
npx sens-mcp exists <kw...> # does something like this already exist?
npx sens-mcp dead-code      # unused symbols (candidates)
npx sens-mcp deps <file>    # what a file imports and what imports it
npx sens-mcp report         # self-contained HTML report → .sens/report.html
npx sens-mcp dashboard      # interactive web dashboard
npx sens-mcp rules          # print the coding rules (--write to save SENS_RULES.md)
npx sens-mcp usage          # which Sens tools the model has actually called

Installed globally (npm i -g sens-mcp) the command is just sens <command>.

Dashboard

sens dashboard starts a local web UI (default http://localhost:4319):

• an interactive graph of your project — files as nodes, imports as edges (drag, click a node to see its symbols);

• live stats and a clickable dead-code list;

• a symbol search;

• a one-click Connect to Claude Code (writes .mcp.json) and a Rebuild index button.

npx sens-mcp dashboard --root . --port 4319   # --no-open to skip opening the browser

Does it actually help?

A reproducible benchmark suite (bench/run.ts) measures this on Sens's own repo and fixtures — run it yourself with npm run bench. No estimates, no anecdotes: every number below comes straight from that script.

Re-run npm run bench on your own machine or project to reproduce (or challenge) these numbers. Re-index speed varies with CPU and disk, so treat it as a range, not a fixed multiplier.

How it works

Pluggable per-language parsers behind one language-agnostic index. Sens walks your source (respecting .gitignore), extracts top-level symbols with compact signatures, resolves references, and caches the result in .sens/index.json — only rebuilt when file mtimes change; a schema version invalidates stale caches across upgrades.

Languages:

• JavaScript / TypeScript (.ts .tsx .js .jsx .mts .cts) via ts-morph — cross-file references are resolved semantically (it follows your imports).

• Python, Go, Rust, Java, C#, C, C++, PHP, Ruby, Kotlin via tree-sitter — functions, classes/structs, methods, constants, and an import graph per file.

Everything lands in one language-agnostic index, so a mixed repo (e.g. a TS frontend + a Python or Go backend) is indexed as a single project. For the tree-sitter languages, cross-file references are resolved by name — the best a syntax-only parser can do without whole-program type inference — so who_uses / dead-code are slightly more approximate than for JS/TS: they over-count rather than miss, which keeps dead-code candidates conservative. Adding a language is a small self-contained parser (src/indexer/languages/); more are on the roadmap.

Configuration

Optional sens.config.json at your project root:

{
  "ignore": ["**/generated/**"],
  "entryPoints": ["src/public-api.ts"]
}

• ignore — extra globs to skip (on top of .gitignore, node_modules, dist).

• entryPoints — files whose exports are your public API, so they're never flagged as dead. **/index.* files are treated as entry points by default.

Dead code — read this

Dead-code results are candidates, not certainties. Sens can't see:

• dynamic usage (string-based access, reflection);

• framework "magic" (e.g. Vue/Nuxt auto-imported components — SFC support is on the roadmap);

• a public API meant for external consumers (use entryPoints).

Test files count as usage sources but are never themselves reported as dead. Verify before deleting.

Roadmap

• Enforcement hook (warn/block when an edit introduces dead code or a duplicate)

• Semantic already_exists (embeddings) + near-duplicate detection

• More languages via tree-sitter; Vue/Svelte SFCs

• Dashboard: symbol-level graph, live file watching

• A reproducible benchmark suite (npm run bench)

Contributing

Issues and PRs welcome. To develop locally:

npm install
npm run build      # bundle to dist/
npm test           # vitest
npm run typecheck

npm link makes sens a global command pointing at your local build.

License

MIT — do what you want, just keep the copyright notice. See the note below on why.