Design Principles

Simplicity is a feature.

This document defines the principles that guide Rune.

Every feature, API, and architectural decision should align with these principles.

---

Philosophy

Git stores history.

Rune stores understanding.

Rune exists to make repository understanding portable, deterministic, and human-readable.

---

Simplicity Over Features

The question is not:

Can we add this?

The question is:

Should we add this?

Complexity accumulates.

Simplicity compounds.

Prefer:

• fewer commands
• fewer abstractions
• fewer dependencies

---

Local First

Rune should work entirely offline.

Rune must never require:

• accounts
• cloud services
• internet access
• API keys

Repository understanding belongs to the repository.

---

Human Readable

Everything important should be stored as plain text.

Preferred formats:

• Markdown
• JSON

Avoid:

• binary files
• databases
• proprietary formats

A developer should be able to inspect .rune/ using:

• vim
• VSCode
• nano
• Notepad

---

Deterministic

Given the same repository:

rune index

should produce identical results.

Avoid:

• timestamps
• random identifiers
• machine-specific paths

Determinism improves:

• reproducibility
• version control
• debugging

---

Incremental By Default

Full reindexing should be rare.

Prefer:

rune update

over:

rune index

Benefits:

• faster execution
• lower memory usage
• better scalability

---

Source Code Is the Truth

Rune never replaces source code.

Source code remains authoritative.

Rune stores:

• summaries
• relationships
• architecture

Not implementation.

---

Explicit Over Implicit

Good:

graph.json

Bad:

hidden internal state

Good:

conventions.md

Bad:

assumptions inside code

Understanding should be visible.

---

Small Core

Core Rune should remain boring.

Responsibilities:

• CLI
• repository format
• graph engine
• context engine
• caching

Nothing more.

---

Complexity Belongs Outside

Language knowledge belongs in plugins.

Examples:

rune-python
rune-typescript
rune-go

AI intelligence belongs to coding agents.

Examples:

• Claude Code
• Cursor
• Codex
• Gemini CLI

Rune provides context.

Others provide intelligence.

---

No Hidden Infrastructure

Avoid:

• databases
• daemons
• background services
• telemetry
• cloud synchronization

The repository should remain self-contained.

---

One Binary

Installation should be:

curl -fsSL ... | sh

Users should not need:

• Python
• Node.js
• Docker
• Java

Rune should feel like installing Git.

---

Language Agnostic

Rune core should know nothing about:

• Python
• TypeScript
• Rust
• Go

Language-specific behavior belongs in plugins.

This enables independent evolution.

---

Versioned Understanding

Repository understanding should live alongside code.

Example:

.git/
.rune/
src/
tests/

Both history and understanding should be version-controlled.

---

Optimize For Longevity

Prefer:

• boring solutions
• stable APIs
• plain files

Avoid fashionable complexity.

Rune should still be understandable ten years from now.

---

Avoid Premature Intelligence

Rune should not:

• call LLMs
• generate code
• edit files

Those capabilities change rapidly.

Context is more durable than intelligence.

---

Deletion Is Progress

Removing complexity is a feature.

Good contributions often:

• simplify code
• reduce dependencies
• remove abstractions

More code does not necessarily mean more value.

---

Scale Without Changing Mental Models

Whether a repository contains:

10 files

or:

100,000 files

the way humans and agents understand it should remain similar.

Complexity in size should not require complexity in concepts.

---

Non-Goals

Rune will never become:

• an IDE
• a code editor
• a vector database
• a cloud platform
• an agent framework
• an LLM provider

Those are different problems.

---

Inspiration

Rune borrows ideas from systems that became infrastructure because they remained simple:

• Git
• SQLite
• Go
• Redis
• Caddy
• ripgrep

These tools prioritize:

• clarity
• portability
• maintainability

over feature accumulation.

---

The Long-Term Vision

One day, repositories may naturally contain:

.git/
.rune/

without developers thinking about it.

Just as Git became invisible infrastructure, repository understanding should become ordinary.

---

Final Principle

If a feature makes Rune more complicated, it carries the burden of proof.

Simplicity wins by default.

---

Git stores history.

Rune stores understanding.