{
  "markdown": "# Rune\n\n**Persistent codebase intelligence for AI coding agents**\n\nRune 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.\n\nClaude Code · Cursor · Codex · Claude Desktop · MCP\n\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\n\n---\n\n## Why Rune?\n\nAI coding agents are powerful.\n\nBut every new session has the same problem:\n\n**They have to rediscover your codebase.**\n\nThey read files, reconstruct context, infer relationships, and build a mental model of your project before they can reliably answer questions.\n\nRune gives AI agents a persistent, queryable understanding of your codebase.\n\n| Without Rune | With Rune |\n|---|---|\n| AI rereads the repository | AI queries an existing understanding |\n| Context is rebuilt every session | Understanding persists |\n| Each agent builds its own mental model | Agents can query the same project model |\n| Answers can be difficult to verify | Answers can point to source evidence |\n| Manual rescanning | `rune watch` keeps the model current |\n\n**One codebase. One persistent understanding. Many AI agents.**\n\n---\n\n## See It in Action\n\nAsk your AI agent:\n\n**\"Where is the `UserCard` component defined?\"**\n\nRune can provide:\n\n```\nUserCard\n├── type: react_component\n├── file: components/UserCard.jsx\n├── line: 3\n└── evidence:\n    export function UserCard({ user }) {\n```\n\nThe value isn't only the answer. It's the evidence behind the answer.\n\nRune is designed to make code intelligence inspectable rather than blindly trusted.\n\n---\n\n## Get Started\n\n### Installation\n\n**Node.js**\n```bash\nnpm install -g @moosl/rune\n```\n\n**Python**\n```bash\npip install north-rune\n```\n\nBoth distributions provide the `rune` CLI.\n\n> **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.\n\n---\n\n## Quickstart\n\n```bash\ncd your-project\nrune init      # sets up Rune in your project\nrune watch &    # keeps the understanding current in the background\nrune serve      # starts the MCP server\n```\n\nRune will now maintain an understanding of your project and expose it to compatible AI clients through MCP.\n\n**One-time scan** (no continuous monitoring needed):\n```bash\nrune scan .\n```\n\n---\n\n## How Rune Works\n\n```\n                    YOUR CODEBASE\n                         |\n                         v\n                   +-----------+\n                   |   Rune    |\n                   |  Scanner  |\n                   +-----+-----+\n                         |\n                         v\n                UNDERSTANDING GRAPH\n                         |\n         +---------------+---------------+\n         |               |               |\n       FACTS         DERIVED         SECURITY\n                   UNDERSTANDING      FINDINGS\n         |               |               |\n         +---------------+---------------+\n                         |\n                         v\n                    MCP SERVER\n                         |\n          +--------------+--------------+\n          v              v              v\n      Claude Code      Cursor         Codex\n```\n\n### Facts -> Understanding -> Evidence\n\nRune separates facts from derived understanding.\n\nA fact might look like:\n```\ncomponents/UserCard.jsx\nline 3\ndefines UserCard\n```\n\nA derived conclusion is constructed from multiple facts. The result is an inspectable chain:\n\n```\nSource -> Fact -> Understanding -> AI answer -> Evidence\n```\n\nCall `rune explain <id>` (or the `rune_explain` MCP tool) on anything and get that chain back.\n\n---\n\n## Security Detectors\n\nBeyond 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.\n\n| Detector | Catches | Severity range |\n|---|---|---|\n| Secret exposure | Hardcoded AWS/GitHub/Stripe/Slack keys, private key blocks | medium - critical |\n| Dangerous shell exec | Dynamic command construction reaching `exec`/`execSync`/`spawn` -- not just any use of these functions | high |\n| CI/CD workflow risk | Dangerous GitHub Actions permissions, the \"pwn request\" pattern | medium - critical |\n| Dependency typosquat | Package names closely resembling popular packages (e.g. `expres` vs `express`) | medium (static-only) |\n\nAll 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.\n\n---\n\n## Project Memory\n\nRune can record durable, project-specific knowledge that survives across sessions, separate from the code-understanding graph:\n\n- **Project memory** -- conventions, required commands, known pitfalls\n- **Experience log** -- a history of what was tried on a task and whether it worked\n\nNothing 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.\n\n```bash\nrune memory add \"Tests live in test/, not __tests__/\"\nrune memory approve <id>\nrune experience add \"Added a field to the user form\" --outcome=success\n```\n\n---\n\n## AI Agent Integration\n\nRune is designed for workflows where multiple AI agents need to understand the same codebase.\n\n**Supported MCP Clients:** Claude Code · Cursor · Codex · Claude Desktop · Custom MCP clients\n\nInstead of requiring every agent to reconstruct the repository independently, Rune provides a shared project understanding through MCP.\n\n### Connect Rune Through MCP\n\n```json\n{\n  \"mcpServers\": {\n    \"rune\": {\n      \"command\": \"npx\",\n      \"args\": [\"-p\", \"@moosl/rune\", \"rune\", \"serve\", \"/absolute/path/to/your-project\"]\n    }\n  }\n}\n```\n\n---\n\n## What Rune Understands\n\nRune currently focuses on common JavaScript and TypeScript application structures.\n\n**Frameworks:** React · Next.js · Express\n\n**Code Intelligence:**\n- React components, hooks, and imports -- extracted via a real AST parser (Babel), not regex\n- Express routes and Next.js page/App Router routes -- currently regex/pattern-based; AST extraction for routes is next on the roadmap\n- File and import relationships\n- Security findings (secrets, shell exec, CI/CD risk, dependency typosquats)\n- Derived conclusions and source evidence for all of the above\n\nSupport is intentionally focused while the project continues to evolve.\n\n---\n\n## Evidence-Backed Answers\n\nMost AI systems provide an answer. Rune aims to provide:\n\n**The answer + the evidence supporting it.**\n\n```\nConclusion\n----------\nUser authentication is handled by the auth middleware.\n\nEvidence\n--------\nmiddleware/auth.js:7\nmiddleware/auth.js:18\n\nMatched source\n--------------\nexport function authenticate(req, res, next) {\n```\n\n**Don't just give the AI an answer. Give it the evidence behind the answer.**\n\n---\n\n## MCP Tools\n\n| Tool | Purpose |\n|---|---|\n| `rune_get_overview` | Architecture summary |\n| `rune_list_components` | All detected React components |\n| `rune_list_routes` | Express and Next.js routes |\n| `rune_search` | Search facts and derived nodes |\n| `rune_explain` | Full evidence trail for any id |\n| `rune_get_file_dependencies` | Internal import graph for a file |\n| `rune_get_memory` | Project conventions and rules (with approval status) |\n| `rune_get_experience` | History of past task attempts and outcomes |\n| `rune_get_security_findings` | All security findings, filterable by severity/category -- the single call for \"any security risks here?\" |\n| `rune_rescan` | Re-scan on demand after code changes |\n\n---\n\n## CLI Reference\n\n| Command | Description |\n|---|---|\n| `rune init [dir]` | Initialize Rune in a project |\n| `rune scan [dir]` | One-time scan (`--timeout=<seconds>` to bound scan time on very large repos) |\n| `rune watch [dir]` | Watch for changes and rebuild |\n| `rune serve [dir]` | Start the MCP server |\n| `rune explain <id>` | Show evidence for a fact or finding |\n| `rune memory add/list/approve/reject` | Manage project memory |\n| `rune experience add/list` | Log and review past task outcomes |\n| `rune --version` | Show the installed version |\n\n---\n\n## Trust & Safety\n\n### Read-Only by Design\n\nRune does not modify your source code. It maintains its own project data under `.rune/`. Your source remains yours.\n\nRune's role is simple: **Read. Understand. Explain. Suggest -- never silently modify.**\n\nIf 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.\n\n### Coverage & Reliability\n\nA 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.\"\n\n---\n\n## Who Is Rune For?\n\nRune is built for developers who:\n- Use AI coding agents regularly\n- Work on large or unfamiliar codebases\n- Switch between multiple AI coding tools\n- Build MCP-based developer workflows\n- Want AI answers that can be traced back to source\n\n---\n\n## What Rune Is Not\n\nRune is not:\n- An autonomous coding agent\n- An IDE replacement\n- A general-purpose static analyzer or compiler\n- A comprehensive security scanner with a live CVE database (today's dependency check is static-only, by design)\n- A system that silently modifies your source or auto-trusts what it learns\n\nRune 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.\n\n---\n\n## Current Status & Limitations\n\nRune is early-stage software, under active, test-driven development.\n\n- **Extraction:** component/import/hook detection uses a real AST parser (Babel). Route detection (Express, Next.js) is still regex/pattern-based -- the next piece moving to AST.\n- **Security detectors are static-analysis only** -- no live CVE feed, no runtime observation.\n- **No cross-file Express route-prefix resolution** yet.\n- **Memory is recorded manually** via CLI/MCP calls today; automatic pattern proposal from accumulated experience is designed but not yet built.\n- **Single-process, stdio MCP transport** -- no multi-client daemon yet.\n- **`rune watch`** performs a full rebuild on every change, not a true incremental diff.\n\nIf Rune produces an incorrect result, please open an issue -- real-world codebases are what improve the extractor and detectors.\n\n---\n\n## Roadmap\n\n- AST-based extraction for route detection (Express, Next.js)\n- Cross-file route resolution\n- Frontend -> backend data-flow tracing\n- True incremental re-scan\n- Additional security detectors: authN/authZ weakening, disabled security checks, dangerous config values, live CVE/registry-backed dependency checks\n- Automatic memory pattern detection -- proposing new rules from accumulated experience, always requiring human approval\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/thecolourfoundation/rune.git\ncd rune\nnpm install\nnpm test\nnpm run verify:mcp\n# or against a real project:\nnpm run verify:mcp -- /path/to/your-project\n```\n\n---\n\n## Contributing\n\nRune is early-stage software. If you're building with AI coding agents, MCP, developer tooling, or code intelligence, real-world feedback is valuable.\n\n**Useful contributions:** report extraction/detection bugs, add tests and fixtures, improve framework detection, test Rune against real-world repositories, improve documentation.\n\nFound something Rune gets wrong? Show us the code -- that's how the understanding layer improves.\n\n---\n\n## Philosophy\n\nAI doesn't need another tool that pretends to know everything. It needs better access to the software it's working on.\n\nRune is built around a simple idea:\n\nUnderstand the codebase. Keep that understanding current. Make the reasoning inspectable. Give the evidence to the agent.\n\nRune is the context layer between your codebase and your AI agents.\n\n---\n\n## License\n\nMIT\n\n---\n\nIf you want to support the circus: ETH `0xbc0979dde621c353737d21f6d7b4eb361f7bc11f`\n",
  "bytes": 12398,
  "sha": "0de9aa10a62f58df2a9423ee150812763bc1ac53feb10aec3e1ce14590551be3",
  "repo_slug": "thecolourfoundation/rune",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_thecolourfoundation_rune_04da3c41/readme"
}