RubySage is a Rails engine that builds a structured, file-level index of your codebase — kept fresh by git fingerprints — and hands it to Claude Code, Cursor, or Codex in a 3K-token retrieval call instead of a 200K-token orientation. Same answers, a fraction of the bill.
Every Claude Code or Cursor session on a Rails app burns 50–200K input tokens just orienting itself. Reading models. Grepping routes. Re-deriving conventions. Across a team of five, that’s millions of tokens a day spent re-learning the same codebase before anyone writes a line.
The codebase has not changed that much. Most files are byte-identical to yesterday. What changed is knowable — git already fingerprints every file in the repo. The expensive work of mapping the app should happen once, not on every new chat.
CLAUDE.md / .cursorrules / AGENTS.md are useful for taste and conventions. They are also static prose someone wrote on a Tuesday — and they drift the moment you rename a service, split a controller, or swap a gem.
RubySage indexes the actual code. Every public class. Every route. Every service object. Per-file summaries that come from reading the file, not from a human guessing six months ago.
A rake task walks your codebase and produces per-file artifacts — summaries, public symbols, route mappings. Stored in your app's database. Secret values redacted. Files unchanged since the last scan are skipped via digest cache, so incremental runs are cheap.
When someone asks a question, RubySage retrieves the most relevant artifacts using keyword + symbol matching, boosted by the current page context. Not vector-only — Rails apps have strong lexical signals (model names, route paths) that BM25 nails.
Relevant artifacts go into a prompt with the question. The LLM answers, citing the specific files and classes it used. Anthropic prompt caching is on by day 1 — subsequent questions within ~5 minutes cost roughly 10× less.
Same Claude Code or Cursor session you use every day, plugged into RubySage. Instead of grepping its way around your repo on every new chat, the agent pulls the 5–15 files the question actually needs — with summaries, symbols, and routes prebaked. Same answers, fewer tokens, faster pickup.
And the scan itself — the part most tools quietly bill you for — runs on your existing Claude Code subscription, not on a new API key. RubySage hands the scan work to the agent you’re already paying for. Out-of-pocket cost: zero.
For the headline use case — RubySage as a knowledge layer for your AI coding agent — your existing Claude Code or Cursor subscription does everything. Out-of-pocket: zero.
The numbers below are for the otherthing the gem includes: a drop-in chat widget your team can ask the codebase questions through. That one needs an Anthropic API key, and here’s what it actually costs. All figures USD, Sonnet pricing, your mileage will vary.
| Operation | Frequency | Cost |
|---|---|---|
| Initial full scan (200-file Rails app) | Once | $0.10 – $0.50 |
| Daily incremental scan (50 changed files) | Per day | $0.05 – $0.20 |
| Widget question, with prompt-cache hit | Per question | $0.01 – $0.05 |
| Widget question, cache miss | First of session | $0.10 – $0.30 |
And if even those numbers bother you: pre-bake the scans in CI and ship the artifacts to prod. Production runs zero LLM calls. The expensive part lives in your CI runner where caching is free and you’re probably already paying for the machine.
The headline is the MCP / scan path. But the gem ships with a handful of other things you might want.
One helper in your layout — ruby_sage_widget — and your team can ask the codebase questions through a floating chat. Auth-gated, citation-grounded. The widget is what the cost table above is about.
Auto-generated ONBOARDING.md for new humans and AGENT_PRIMER.md for AI agents joining your repo. V1 ships a rough version of this; the polished release is on the roadmap.
Built because we got tired of paying for our AI to re-read our own Rails apps every session. If you’ve had the same headache, take it, use it, send a PR. That’s the whole point.