Rune

Persistent codebase intelligence for AI coding agents

Rune continuously maps your codebase and exposes an evidence-backed understanding through MCP, enabling AI agents to work with your software without rebuilding context from scratch.

Claude Code · Cursor · Codex · Claude Desktop · MCP

Why Rune?

AI coding agents are powerful.

But every new session has the same problem:

They have to rediscover your codebase.

They read files, reconstruct context, infer relationships, and build a mental model of your project before they can reliably answer questions.

Rune gives AI agents a persistent, queryable understanding of your codebase.

One codebase. One persistent understanding. Many AI agents.

See It in Action

Ask your AI agent:

"Where is the UserCard component defined?"

Rune can provide:

UserCard
├── type: react_component
├── file: components/UserCard.jsx
├── line: 3
└── evidence:
    export function UserCard({ user }) {

The value isn't only the answer. It's the evidence behind the answer.

Rune is designed to make code intelligence inspectable rather than blindly trusted.

Get Started

Installation

Node.js

npm install -g @moosl/rune

Python

pip install north-rune

Both distributions provide the rune CLI.

Note: If both distributions are installed globally, your shell will use whichever rune executable appears first on your PATH. Run which -a rune to see which executable is being used.

Quickstart

cd your-project
rune init      # sets up Rune in your project
rune watch &    # keeps the understanding current in the background
rune serve      # starts the MCP server

Rune will now maintain an understanding of your project and expose it to compatible AI clients through MCP.

One-time scan (no continuous monitoring needed):

rune scan .

How Rune Works

                    YOUR CODEBASE
                         |
                         v
                   +-----------+
                   |   Rune    |
                   |  Scanner  |
                   +-----+-----+
                         |
                         v
                UNDERSTANDING GRAPH
                         |
         +---------------+---------------+
         |               |               |
       FACTS         DERIVED         SECURITY
                   UNDERSTANDING      FINDINGS
         |               |               |
         +---------------+---------------+
                         |
                         v
                    MCP SERVER
                         |
          +--------------+--------------+
          v              v              v
      Claude Code      Cursor         Codex

Facts -> Understanding -> Evidence

Rune separates facts from derived understanding.

A fact might look like:

components/UserCard.jsx
line 3
defines UserCard

A derived conclusion is constructed from multiple facts. The result is an inspectable chain:

Source -> Fact -> Understanding -> AI answer -> Evidence

Call rune explain <id> (or the rune_explain MCP tool) on anything and get that chain back.

Security Detectors

Beyond structural understanding, Rune does a static-analysis pass for common security regressions -- same evidence-traced model as everything else: every finding cites file, line, and matched text.

All four are deliberately conservative and context-aware: findings inside test/fixture files or a detector's own pattern-definition code are automatically downgraded, never silently hidden. Each detector has its own test suite covering both true- and false-positive cases.

Project Memory

Rune can record durable, project-specific knowledge that survives across sessions, separate from the code-understanding graph:

• Project memory -- conventions, required commands, known pitfalls
• Experience log -- a history of what was tried on a task and whether it worked

Nothing is trusted automatically. Every new entry starts as proposed; a human must explicitly approve it before it's surfaced to an AI client as reliable -- enforced in code, not just policy.

rune memory add "Tests live in test/, not __tests__/"
rune memory approve <id>
rune experience add "Added a field to the user form" --outcome=success

AI Agent Integration

Rune is designed for workflows where multiple AI agents need to understand the same codebase.

Supported MCP Clients: Claude Code · Cursor · Codex · Claude Desktop · Custom MCP clients

Instead of requiring every agent to reconstruct the repository independently, Rune provides a shared project understanding through MCP.

Connect Rune Through MCP

{
  "mcpServers": {
    "rune": {
      "command": "npx",
      "args": ["-p", "@moosl/rune", "rune", "serve", "/absolute/path/to/your-project"]
    }
  }
}

What Rune Understands

Rune currently focuses on common JavaScript and TypeScript application structures.

Frameworks: React · Next.js · Express

Code Intelligence:

• React components, hooks, and imports -- extracted via a real AST parser (Babel), not regex
• Express routes and Next.js page/App Router routes -- currently regex/pattern-based; AST extraction for routes is next on the roadmap
• File and import relationships
• Security findings (secrets, shell exec, CI/CD risk, dependency typosquats)
• Derived conclusions and source evidence for all of the above

Support is intentionally focused while the project continues to evolve.

Evidence-Backed Answers

Most AI systems provide an answer. Rune aims to provide:

The answer + the evidence supporting it.

Conclusion
----------
User authentication is handled by the auth middleware.

Evidence
--------
middleware/auth.js:7
middleware/auth.js:18

Matched source
--------------
export function authenticate(req, res, next) {

Don't just give the AI an answer. Give it the evidence behind the answer.

MCP Tools

CLI Reference

Trust & Safety

Read-Only by Design

Rune does not modify your source code. It maintains its own project data under .rune/. Your source remains yours.

Rune's role is simple: Read. Understand. Explain. Suggest -- never silently modify.

If you share Rune's generated graph or memory files with an AI client, remember they may contain information from your codebase -- treat them like any other file that quotes snippets of your source.

Coverage & Reliability

A single malformed or unusual file can't take down an entire scan -- parsing failures are caught per-file, logged, and the scan continues. Scan results report real coverage (files discovered vs. supported vs. scanned vs. failed), and a repository with no supported source files is reported honestly as such rather than as a clean "no findings."

Who Is Rune For?

Rune is built for developers who:

• Use AI coding agents regularly
• Work on large or unfamiliar codebases
• Switch between multiple AI coding tools
• Build MCP-based developer workflows
• Want AI answers that can be traced back to source

What Rune Is Not

Rune is not:

• An autonomous coding agent
• An IDE replacement
• A general-purpose static analyzer or compiler
• A comprehensive security scanner with a live CVE database (today's dependency check is static-only, by design)
• A system that silently modifies your source or auto-trusts what it learns

Rune focuses on one problem: helping AI agents understand an existing codebase through persistent, inspectable context -- with a security layer built on the same evidence-first principle.

Current Status & Limitations