okyashgajjar/costwise-mcp

---

Coding agents should behave like experienced engineers

An experienced engineer walks into a codebase and does not:

• Re-read the same files every time they answer a question.
• Re-discover symbols they already found ten minutes ago.
• Keep a 5,000-line build log in their head because they might need it later.
• Carry every detail of every conversation around forever.

They remember where things live. They open only what they need. They hold facts, not files.

Most AI coding agents do the opposite. They re-explore the same repository over and over. They dump whole files into context. They grow the conversation window until every turn becomes expensive — not because the answer is hard, but because everything else in the window has to be re-read and re-cached.

CostWise is a local MCP server that makes coding agents behave more like that experienced engineer. It gives them fast, token-budgeted access to your repository — so they stop reading whole files to find small facts.

---

How CostWise fixes it

A tool that connects over MCP cannot control how or when the client caches. Cache breakpoints and TTLs are the client’s decision. There is exactly one lever the server controls:

How many tokens ever enter the resident context window in the first place.

Shrink that, and both costs fall: a smaller window is cheaper to read every turn and cheaper to rewrite when the cache is invalidated. CostWise does four things in service of that goal.

1. Answer from a local index, not from files

CostWise parses your repository once with Tree-sitter and stores symbols, references, and call edges in a local SQLite index. Navigation questions — “where is this defined,” “who calls this,” “what references this” — are answered from the index in a few tokens instead of by dumping source files.

Results are compressed scopes sized to the kind of question asked. The model gets the location, not the file; the implementation body, not the whole module; the caller list, not the grep output.

2. Remember facts instead of repeating them

The remember tool persists a small durable fact — a decision, an entry point, a gotcha — to a per-repository store. The recall tool retrieves it later. Facts the model would otherwise re-derive or re-paste each turn are written down once and read back only when relevant.

3. Stash large output instead of pasting it inline

The stash_context tool parks a large blob — a file, a command output, a test log — out of the conversation and returns a short handle. The full content stays on disk, recoverable. The recall tool pulls back only the slice that matches a query, within a token budget.

A 5,000-line build log pasted inline is re-read and potentially re-written to the cache every turn for the rest of the session. Stashed, it costs about 20 tokens (the handle) and is pulled back only in the slice you need.

4. A session-awareness skill that makes the model use all of the above

A small piece of guidance (about 275 tokens) is delivered to every connected editor through the MCP protocol’s instructions field. It teaches the model the lean workflow once per session: route large output through stash_context, persist durable facts with remember, prefer narrow retrieval over file reads.

It is also installable as a native Claude Code skill, AGENTS.md entry, or rules file for any editor that reads them. The same canonical source backs all delivery paths.

---

Supported Languages

CostWise indexes 11 languages using Tree-sitter AST parsers — symbol definitions, references, and call edges are all precomputed and stored in a local SQLite index.

Go, Python, JavaScript, and TypeScript use bespoke extractors with deeper analysis; the other seven use a generic spec-driven extractor built on Tree-sitter’s common conventions. All languages get symbols, references, call edges, and full-text search.

---

Installation

---

What you get

CostWise provides 10 MCP tools that fall into three categories.

Retrieval tools answer questions from a pre-built index instead of by reading files:

• search_code — semantic search by natural language question.
• find_symbol — locate where a symbol is defined.
• read_symbol — return a symbol’s full implementation body.
• find_references — every usage of a symbol, precomputed.
• find_callers — which functions call a given function.

Maintenance tools keep the index in sync:

• get_repository_summary — token-budgeted overview of the repo, drillable by module.
• index_repository — manual re-index trigger (auto-watcher normally handles this).

Context-control tools keep large content and durable facts out of the resident window:

• remember — persist a fact once instead of repeating it inline.
• stash_context — park a large blob out of context behind a tiny handle.
• recall — pull back only the slice that matches a query, within a budget.

---

---

Contributors

Thanks to everyone who has contributed to CostWise:

---

License

MIT

---