⚡ Quick Start

Install uv, clone, deploy.

git clone https://github.com/kvasir-ai/rune.git && cd rune && make use-profile PROFILE=default

Verify the installation:

make verify          # check deployed state
make list-agents     # browse the team
make list-rules      # browse the knowledge
make list-skills     # browse the workflows

Try it: say "run rune example 1" to dispatch a showcase DAG.

👥 Bring Your Agents

rune orchestrates agents — it does not prescribe them. Bring your own specialists or start from a community collection:

rune ships with four orchestration agents (Planner, Judge, Technical Writer, Knowledge Manager) that coordinate the three-phase workflow. Domain specialists — developer, tester, security, architect — are yours to choose.

What rune adds

Any agent becomes a rune agent when it participates in a DAG. rune handles the coordination: wave computation, parallel dispatch, context injection between tasks, token tracking. The agent just does its job — rune handles the choreography.

Agents auto-discover from src/agents/ — no registration needed. Drop a markdown file, deploy the profile, and the agent is available.

💬 Talk to Your Team

rune is LLM-native. You talk to agents in natural language, or invoke skills as slash commands. The three-phase workflow maps to a natural conversation:

Phase 1: Explore

Phase 2: Plan

Phase 3: Execute

Maintain

No CLI commands, no API calls. You talk. The agents act. The make targets are for setup only — once deployed, rune lives inside your coding session.

🤖 Agents

An agent is a markdown file with YAML frontmatter (name, description, model, tools, emoji) and a system prompt body. When dispatched as a sub-agent, the full prompt loads into its own context window.

At session start, only the frontmatter descriptions load — lightweight summaries that tell the orchestrator when to invoke each agent. The full prompt loads on demand.

Frontmatter fields

📖 Rules

Rules are plain markdown files in src/rules/ that agents load as context. They encode conventions, standards, patterns, and domain knowledge. A rule about SQL formatting shapes how every agent writes SQL. A rule about git conventions shapes how every agent commits.

Rules are not code. They are structured knowledge — tables, checklists, code blocks — that agents read and follow.

Quality criteria

🔄 Profiles

A profile controls which rules load into context. All agents and skills deploy to every profile — only the knowledge set changes.

A platform engineer and a financial analyst need different rules. Profiles enforce this separation. Switch with one command.

make use-profile PROFILE=my-profile    # deploy
make context-budget                    # measure footprint

⌨ Skills

Skills are slash commands that trigger structured workflows. Each skill belongs to one of the four core agents — or to /rune (the dispatch engine the user operates directly).

Skills load on demand — they consume zero tokens until invoked.

Skill catalog

SSDLC cycle

🚧 Hooks

Hooks are Python scripts that fire on Claude Code/OpenCode lifecycle events. They run automatically — no opt-in required.

Both safety-check and auto-lint are configurable via YAML — add patterns or lint rules without touching Python.

📥 Knowledge Inbox

src/knowledge/ is the staging area. Raw material goes in — PDFs, research summaries, extracted docs. The Knowledge Manager distills it into structured rules in src/rules/.

Never skip the inbox by writing directly to rules. Raw material stays in the inbox after distillation — it serves as the source reference.

🔀 DAG Dispatch

Define tasks with dependencies. /rune computes waves via topological sort and dispatches each wave in parallel. Independent tasks run simultaneously. Dependent tasks wait.

───────────────────────────────────────────
  DAG DISPATCH PLAN
  Tasks: 7  |  Waves: 3  |  Benefit: 1.8x
───────────────────────────────────────────

  Wave 0  ─── 4 parallel ──────────────────
  🏗  t1  architect         Design API contract
  🎨  t2  designer          Design UI components
  🔧  t3  developer         Set up database schema
  ✍  t4  writer            Draft documentation

  Wave 1  ─── 2 parallel ──────────────────
  🔧  t5  developer         Implement API and UI
                              ↳ depends on: t1, t2, t3
  🧪  t6  tester            Write tests
                              ↳ depends on: t1, t3

  Wave 2  ────────────────────────────────
  🔍  t7  reviewer          Final review
                              ↳ depends on: t4, t5, t6
───────────────────────────────────────────

Say /rune to dispatch. "Test this DAG" for a zero-cost dry run. Dispatch history is saved to .rune/ for audit and session recovery.

Token economics

Every dispatch ends with a cost report — actual token counts per agent, estimated USD cost, wall time vs sequential time, and parallelism savings. Costs are tracked per task and persisted in the history file.

Deep dive: DAG Dispatch covers the full execution cycle including context injection and cost tracking.

⚖ The Judge

The Judge is a read-only validation agent that evaluates any other agent's output before you act on it. Plans, code, architecture decisions, compliance assessments — a second opinion before the consequence.

Six-phase protocol

The Judge never implements — it describes what needs to change and who should do it.

💰 Token Economics

Every /rune dispatch tracks token usage per agent. After execution, the final report shows actual metered values — not estimates.

───────────────────────────────────────────
  💰 Token Economics
───────────────────────────────────────────
  t1  [ DEVELOPER ]   322K tok   $6.76
  t2  [ DEVELOPER ]   394K tok   $8.28
  t3  [ REVIEWER ]    304K tok   $6.38
───────────────────────────────────────────
  Total tokens:  1,020K
  Est. cost:     $21.42
  Wall time:     6m 12s  (parallel)
  CPU time:      14m 30s (sequential sum)
  Time saved:    57% via parallelism
───────────────────────────────────────────

Cost model

Since the Agent tool returns total_tokens (not split input/output), rune uses a blended rate per model tier:

The 80/20 input/output ratio is a practical approximation. Costs are displayed as "Est. cost" — directional, not exact.

Up-front cost estimation

Before dispatching, rune estimates cost and assigns a tier badge:

The tier appears in the dispatch header before execution begins — giving you a cost signal before committing.

History

Token usage, cost estimates, and timing are persisted in .rune/ history files alongside the plan and results. Use these for cost tracking across sessions.

📊 Context Budget

Every token loaded into context displaces space for reasoning. rune treats context as a budget — every token must earn its place.

make context-budget

What loads when

The default profile ships lean. Run make context-budget to measure your footprint.

🛡 Safety

The safety-check hook blocks destructive commands before the shell sees them. Configurable via src/hooks/safety-patterns.yaml.

The hook is a seatbelt — it catches accidental destructive commands from LLM agents. OS permissions, sandboxing, and CI/CD handle the deeper layers.

Full analysis: The Safety Architecture covers test evidence, known bypasses, and industry comparison.

🔍 Phase 1: Explore

🗺 Phase 2: Plan

⚡ Phase 3: Execute

📋 Safety Patterns

Configurable in src/hooks/safety-patterns.yaml.

# Add a new pattern:
- name: kubectl-delete
  match: '\bkubectl\s+delete\b'
  message: "Kubernetes resource deletion blocked"
  severity: block

🧹 Auto-Lint Rules

Configurable in src/hooks/auto-lint-rules.yaml. Runs after every file write.

# Add TypeScript formatting:
- extension: ts
  commands:
    - "prettier --write {file}"
  timeout: 10

🔊 Peon-Ping

Audio notifications with themed sound packs. Maps model tiers to sound profiles. Configurable in tools/peon-ping/profiles.yaml.

make install-tool-peon-ping              # install
make configure-peon PEON_PROFILES=warcraft,starcraft   # configure
make list-peon-profiles                  # see available profiles

Model-to-tier mapping

Models are matched to tiers (low/mid/high) via substring. haiku → low, sonnet → mid, opus → high. Works with any provider — add model patterns to profiles.yaml.

⚙ Make Targets