io.github.thecolourfoundation/rune MCP Server

Rune

Ask questions about your code. Get answers you can check.

Rune scans a project into a graph of facts, and every fact points at the exact file and line it came from. Ask a question and you get ranked findings with citations. Your own AI model can then explain them, and Rune throws away any statement the evidence doesn't back.

Real output on the Express repo, with a small local model writing the explanation:

$ cd express
$ rune "how does routing work"

2 insight(s):

1. lib/application.js
   Why it matters: Loads the external package `router` (var Router = require('router');)
   - logic tied to this name likely lives there, not in this repo.
   Evidence: lib/application.js:26
...
Explanation (written by local / qwen2.5:1.5b; every statement checked against cited evidence)

  - Router is the external package used for routing logic in this project.  [lib/application.js:26, lib/express.js:19]

The answer is short because it's true: Express hands routing to a separate package, and Rune says so and shows the line.

Why Rune

• Every claim has a source. Facts carry a file, a line, the exact snippet and a confidence level. rune explain <id> shows the evidence trail behind any fact.
• Your model, your call. Use Anthropic, OpenAI, any OpenAI-compatible API, or a local model. Rune has no model of its own.
• Read-only. Rune observes and reports. It never modifies your project.
• Works where you work. It's an MCP server, so AI clients can use it directly.

Install

Linux (x64) and macOS (Apple Silicon):

curl -fsSL https://raw.githubusercontent.com/thecolourfoundation/rune/main/install.sh | sh

Windows: download rune-windows-x64.exe from the latest release and run it from a terminal.

The installer verifies a SHA-256 checksum and puts rune in ~/.local/bin.

Use

cd your-project
rune "how does routing work"
rune "give me 5 architectural insights"

The first run scans the project, which takes a few seconds. After that, Rune prints ranked findings with file:line evidence, then your model writes a short explanation from that evidence.

Run rune --help for everything, and see Docs.md for detail.

Bring your own model

# Anthropic (early support)
export ANTHROPIC_API_KEY=your-key

# OpenAI or any OpenAI-compatible API
export OPENAI_API_KEY=your-key
export RUNE_LLM_MODEL=model-name

# Local model with Ollama (no key, nothing leaves your machine)
export RUNE_LLM_BASE_URL=http://localhost:11434/v1
export RUNE_LLM_MODEL=model-name

Every statement the model writes must cite evidence Rune retrieved. Rune drops any statement that cites something it didn't retrieve, cites nothing, or quotes text that isn't in the cited evidence, and it tells you how many it dropped.

That checks grounding, not truth: a model can still misread real evidence. Explanation quality depends on the model you choose.

If no model is configured, Rune prints the evidence, then setup help, and exits with code 2. Add --evidence-only to skip the model. Set RUNE_LLM_DEBUG=1 to see the model's raw reply and why any statement was dropped.

What leaves your machine

Only the evidence for your question goes to the model provider you configured: up to 40 short code snippets, never the whole project. Rune prints how many it is sending before it sends them. Use --evidence-only, or a local model, to send nothing.

Use it from AI tools (MCP)

Rune is an MCP server. Point any MCP client at it:

{"command": "rune", "args": ["serve", "/absolute/path/to/your-project"]}

The client gets 13 tools, including rune_agent, rune_search, rune_explain, rune_verify_fact, rune_check_drift, rune_list_routes and rune_get_security_findings. Answers come back with file, line and snippet citations. No key is needed here, because the client's own model is the model.

rune_agent always reports a fast, no-model triage verdict on whether shallow evidence was enough. Pass deep: true to let it run a deeper, LLM-driven investigation pass when triage decides the question needs it (or force: true to always run it) -- this is the one case where the tool may call a model you've configured, and its cost is counted against the response's token budget like everything else.

Rune is listed in the official MCP Registry as io.github.thecolourfoundation/rune. Each release also includes .mcpb bundles for one-click install in Claude Desktop. They are new and haven't been tested inside Claude Desktop yet.

What Rune understands

• JavaScript and TypeScript: imports, function calls, React components and hooks, Express routes, Next.js routes, Vue components.
• Shell, Lua, config files (TOML, YAML, JSON) and markdown.
• Security findings: hardcoded secrets, risky shell execution, GitHub Actions workflow issues and dependency issues.

How it works

1. Scan. Rune parses your files into facts, each with a file, line, snippet and confidence.
2. Derive. It builds conclusions from those facts, and each conclusion lists the fact ids it rests on.
3. Investigate. For a question, it retrieves the relevant facts, forms hypotheses, checks them against the current files, and ranks them.
4. Triage, then escalate if needed. A fast, no-model check looks at the ranked hypotheses -- their confidence, whether they're too close to call, whether the question's own terms matched anything -- and decides if that's a good enough answer or if the question needs deeper reasoning. This step costs nothing and calls no model.
5. Explain, then verify. Your model writes the explanation, and Rune checks each statement against the evidence. If triage flagged the question as needing it, an optional deeper investigation pass reasons across every hypothesis's evidence at once (still model-written, still fully cited, still verified the same way).

rune verify re-reads the source and tells you which stored facts have drifted since the last scan.

Good to know

• Best on JavaScript/TypeScript, shell, Lua and config files. Other languages get thinner results for now.
• Rune saves its scan in .rune/ inside your project. Add .rune/ to your .gitignore.
• The binaries are unsigned, so macOS or Windows may show a security warning. There is no prebuilt binary yet for Intel Macs or Linux on ARM.

Where it's going

Rune's scanners plug in through an extractor registry, and the graph, evidence and verification layers aren't specific to code. Support for other kinds of sources is planned. Today, Rune understands software projects.

Contributing

Issues and pull requests are welcome.

License

MIT. Built by the Colour Foundation.