Architecture

Simple systems scale better.

---

Overview

Rune is designed around a simple principle:

Store understanding, not intelligence.

Rune does not attempt to become:

• an IDE
• an agent framework
• a vector database
• a cloud platform

Rune provides context.

Agents provide intelligence.

---

High-Level Architecture

                +--------------+
                | Claude Code  |
                +--------------+
                       |
                +--------------+
                | Cursor        |
                +--------------+
                       |
                +--------------+
                | Gemini CLI    |
                +--------------+
                       |
                +--------------+
                | Codex         |
                +--------------+
                       |
                +--------------+
                | Rune Context  |
                +--------------+
                       |
        --------------------------------
        .rune/
        spec.md
        graph.json
        files/
        features/
        --------------------------------

Rune sits below coding agents.

Multiple agents can consume the same repository understanding.

---

Core Components

Rune consists of five major components:

CLI
↓
Indexer
↓
Graph Builder
↓
Context Engine
↓
Repository Format

---

CLI

The command-line interface is intentionally small.

Commands:

rune init
rune index
rune update
rune context
rune doctor

Responsibilities:

• initialize repositories
• trigger indexing
• expose context
• validate integrity

The CLI should remain simple.

---

Indexer

Purpose:

Analyze source code and produce semantic summaries.

Input:

src/
tests/

Output:

.rune/files/
.rune/features/

The indexer should:

• scan files
• detect imports
• extract symbols
• identify dependencies
• generate summaries

---

Graph Builder

Purpose:

Construct dependency relationships.

Output:

.rune/graph.json

Example:

{
  "auth.py": [
    "user.py",
    "jwt.py"
  ]
}

The graph enables selective loading.

Instead of loading:

100 files

agents can load:

3 files

---

Context Engine

Purpose:

Answer questions like:

What files are relevant to this task?

Example:

rune context "Add Google OAuth"

Returns:

{
  "related_files": [
    "auth.py",
    "user.py",
    "settings.py"
  ]
}

The context engine should:

• read summaries
• traverse dependency graphs
• identify affected features
• minimize token usage

---

Repository Format

Persistent understanding lives in:

.rune/

Artifacts include:

spec.md
architecture.md
conventions.md
graph.json
files/
features/
ownership/
sessions/
cache/

Everything should be:

• deterministic
• human-readable
• versionable

---

Plugin System

Core Rune is language-agnostic.

Language-specific logic lives outside the core.

Examples:

rune-python
rune-typescript
rune-go
rune-rust
rune-java

Plugins are responsible for:

• parsing files
• extracting symbols
• dependency analysis
• summary generation

This keeps the core small.

---

Internal Flow

User
 ↓
rune context
 ↓
Context Engine
 ↓
graph.json
 ↓
feature summaries
 ↓
file summaries
 ↓
load source code only if needed

Source code should be the final step, not the first.

---

Incremental Updates

Initial indexing:

rune index

Processes the entire repository.

Subsequent updates:

rune update

Only refresh changed files.

Benefits:

• faster execution
• reduced CPU usage
• lower memory consumption

---

Sessions

Session memory tracks recent activity.

Example:

{
  "files": [
    "auth.py",
    "user.py"
  ]
}

Purpose:

Improve locality and reduce unnecessary loading.

Sessions are temporary.

---

Cache Layer

Cache stores:

• hashes
• timestamps
• intermediate metadata

Location:

.rune/cache/

The cache should never contain critical information.

Deleting the cache must always be safe.

---

External Integrations

Rune should work with:

• Cursor
• Claude Code
• Codex
• Gemini CLI
• Aider
• Roo Code

No special APIs should be required.

The .rune/ directory itself is the interface.

---

Technology Choices

Implementation language:

Go

Reasons:

• single binary
• fast compilation
• cross-platform support
• low operational complexity

---

Non-Goals

Rune will never become:

IDE
Cloud service
MCP server
Vector database
LangChain framework
Code editor

Complexity should be pushed outward.

Core Rune should remain boring.

---

Scalability Philosophy

A repository with:

10 files

and one with:

100,000 files

should expose understanding in the same way.

The amount of source code may grow.

The mental model should not.

---

Design Principles

Prefer:

• plain files
• deterministic outputs
• explicit metadata
• incremental computation

Avoid:

• hidden state
• databases
• background daemons
• network dependencies

---

Philosophy

Git stores what happened.

Rune stores what the repository means.

Humans and AI should be able to understand a codebase without reading every file.