Why Rune Exists

Git stores history. Rune stores understanding.

---

The Problem

Large codebases are difficult to understand.

Humans solve this problem naturally.

When joining a new project, developers usually:

1. Read the README.
2. Learn the architecture.
3. Understand coding conventions.
4. Identify important modules.
5. Navigate only the files relevant to the task.

Very few engineers read an entire repository from top to bottom.

---

Code LLMs Work Differently

Most coding agents lack persistent understanding.

Every time a user says:

Add Google OAuth

or:

Refactor billing

or:

Implement password reset

the agent often receives thousands of lines of source code again and again.

This creates several problems:

• excessive token usage
• slow responses
• unnecessary context duplication
• poor understanding of architecture
• inconsistent modifications

The issue is not intelligence.

The issue is memory.

---

Git Solved History

Before Git, source code history was difficult to manage.

Git provided a standard way to answer:

What changed?

Today almost every repository contains:

.git/

Git became infrastructure.

Most developers no longer think about it.

---

But Repositories Still Lack Understanding

Git tracks:

• commits
• branches
• merges
• diffs

Git does not explain:

• architecture
• conventions
• dependencies
• feature ownership
• module relationships

Git stores history.

Not meaning.

---

README Files Are Not Enough

README files are written for humans.

They are usually:

• too general
• outdated
• incomplete

Typical README files explain:

How to install
How to run tests
Environment variables

They rarely explain:

Which files implement login?

What depends on billing?

Which modules should never be modified?

How does a feature flow through the system?

---

Humans Build Mental Models

Experienced developers carry a mental map of the repository.

They know:

Login
 ↓
auth.py
 ↓
user.py
 ↓
jwt.py

They know:

• architectural rules
• dangerous areas
• dependencies
• ownership

This understanding exists mostly inside people's heads.

Rune aims to externalize that understanding.

---

Introducing Rune

Rune adds a second layer to repositories:

.git/
.rune/

Git answers:

What happened?

Rune answers:

What does this codebase mean?

---

What Rune Stores

Rune stores:

Architecture

Backend:
FastAPI

Frontend:
Next.js

Database:
PostgreSQL

---

Conventions

- Use repository pattern.
- Never use raw SQL.
- APIs return Pydantic models.

---

Dependency Graphs

auth.py
 ├── user.py
 └── jwt.py

---

File Summaries

Purpose:
Authentication service.

Exports:
- login()
- logout()

Dependencies:
- user.py
- jwt.py

---

Feature Maps

login.tsx
 ↓
auth.py
 ↓
user.py
 ↓
jwt.py

---

Session Context

Recently touched files:

auth.py
user.py

---

Source Code Becomes On-Demand

Instead of sending:

50 files

100,000 tokens

Rune allows agents to start with:

spec.md
graph.json
feature summaries
file summaries

and load source code only when necessary.

This dramatically reduces context consumption.

---

Rune Is Not an IDE

Rune is not:

• Cursor
• Copilot
• Claude Code
• LangChain
• MCP
• a vector database

Rune provides context.

Agents provide intelligence.

---

The Long-Term Vision

One day repositories may routinely contain:

.git/
.rune/

.git/

explains:

What changed?

.rune/

explains:

What the codebase means.

---

Philosophy

Git stores history.

Rune stores understanding.