Coding agents should behave like experienced engineers.
An experienced engineer does not re-read the same files every turn, rediscover the same symbols, or carry a 5,000-line log in memory. CostWise gives your AI coding agent the same instincts — from a local index, not from file dumps.
curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costwise-mcp/main/install.sh | bashWithout CostWise vs with
Same task. Same model. The left side reads files. The right side uses the index.
Why long sessions get expensive
The expensive part is not the model's output. It is everything around it.
Repositories get re-explored
Ask your coding agent "where is X defined" and it reads the file. Ask again five minutes later — it reads the same file again. Each read puts thousands of tokens into the context window.
Context grows without being useful
A typical session starts small. Then the model dumps a file to answer a question. Then a test output. Then a build log. None of these leave — they accumulate in the resident context window.
The prompt cache makes it worse
Every turn pays to read the entire resident context. Any change or idle gap forces a full rewrite. In one measured call, $2.84 of a $2.95 charge was the cache write — the output was under 4K tokens.
One lever: shrink the context window
A server cannot control how the client caches. It can only control how many tokens ever enter the window.
Answer from a local index
Navigation questions — "where is this defined", "who calls this" — are answered from a Tree-sitter SQLite index in a few tokens instead of by dumping source files.
Remember facts instead of repeating
The remember tool persists a durable fact per repository. The recall tool retrieves it later. Facts are written down once instead of re-derived every turn.
Stash large output instead of pasting
Stash_context parks a large blob out of context behind a ~20 token handle. Recall pulls back only the matching slice, within a token budget. Lossless.
Session-awareness skill
A 275-token guidance delivered to every MCP client teaches the model the lean workflow automatically. Also installable as a native Claude Code skill.
Built for cost, speed, and privacy
Four properties that hold no matter how large the repository gets.
100% Local-First
All indexing, SQLite queries, and AST parsing run locally. No telemetry, no code egress.
MCP Compatible
Plugs into Claude Code, Cursor, Codex, OpenCode, Antigravity, and any stdio MCP client.
Incremental Sync
A file watchdog re-indexes only changed files on save, so the index stays fresh without full rebuilds.
Context Control
Returns compressed scopes, budgeted summaries, and out-of-context stashes instead of bloated files.
Stash the monster, recall the slice
Three tools form one loop that keeps the window small without ever losing information.
stash_context
A 5,000-line log goes to disk and returns a ~20 token handle instead of flooding the window.
recall
Pull back only the lines that match your query, trimmed to a token budget.
remember
Keep the durable conclusion as a fact so it is never re-derived next turn.
The costwise-session skill teaches your editor to do this automatically, delivered to every MCP client through the protocol's instructions field.
Eleven tools, one goal
Retrieval answers questions in a few tokens. Context-control keeps large content and durable facts out of the window entirely.
Semantic AST search that returns relevant scopes, not whole files.
Resolve a definition to a location in a single index lookup.
Return a symbol's implementation body by name, from the indexed line range.
Every usage of a symbol, precomputed for impact analysis.
Who calls this function, from stored call edges.
Token-budgeted repo map with drill-down. Stays small on any repo.
Manual re-index. Usually unnecessary; the watchdog handles it.
Persist a durable fact per repository so it is never repeated inline.
Park a large blob out of context; get back a tiny handle. Lossless.
Pull back only the slice a query needs, from a stash or from facts.
Compact summary of past sessions — facts, stashes, reindex events.
Architecture
Hover or click components in the flow diagram to inspect each module.
MCP Server Transport
Handles Model Context Protocol messages over local stdio, registers the ten tools, and advertises the costwise-session guidance through the protocol instructions field so every client receives it automatically.
Relevant repository paths
- internal/mcpserver/server.go
- internal/mcpserver/tools.go
- internal/skill/
How retrieval works
CostWise indexes code structurally with Tree-sitter. Explore it live in the AST simulator.
import * as fs from 'fs';import * as path from 'path'; interface ServerSetting { command: string; args: string[];} export function loadConfig(configPath: string): ServerSetting { const raw = fs.readFileSync(path.resolve(configPath), 'utf-8'); return JSON.parse(raw) as ServerSetting;}Extracted AST nodes
Codebase inspector
Browse the actual CostWise codebase to verify its structure.
internal/retriever
Semantic Search EnginesImplements the core 9 indexing algorithms (treesitter, grep, fts, auto, naive) for semantic code retrieval.
Compiled AST Symbols
Editor configurator
Select your IDE to generate a setup profile.
{
"mcpServers": {
"costwise": {
"command": "costwise",
"args": ["serve"]
}
}
}CostWise vs alternatives
How it compares to dependency graphs and plain text search.
CodeGraph
Scoped AST lookups instead of heavy code-graph pointer files.
Serena
Restores offline parsing without cloud data egress.
Graphify
Optimized symbol arrays instead of complex spatial coordinates.
ripgrep
Retrieves logical scopes rather than noisy text lines.
Frequently asked
Indexing, token optimization, and IDE integration.
How does it save prompt tokens?
It returns structural declarations and scopes from a local index instead of whole files, and lets the model park large output out of context, trimming input significantly.
Does my code leave my machine?
No. All parsing and SQLite index writes happen locally. There are no API keys and no cloud indexing.
How is this different from grep or ripgrep?
grep returns lines. CostWise understands structure — it knows where a function body starts and ends, who calls it, and what it references. From a pre-built index, in microseconds.
Does it work with any LLM provider?
It works with any editor that supports MCP tools — Claude Code, Cursor, OpenCode, Codex CLI, and any stdio-based MCP client.
Save context. Write code.
Install the local-first repository intelligence server and keep your AI coding sessions fast, private, and token-efficient.
curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costwise-mcp/main/install.sh | bash