README
¶
Rune
A shared task runner for humans and AI agents.
Rune runs your project's commands — lint, test, build, deploy — from one readable
file, the Runefile. Humans run tasks from the CLI; AI agents and IDEs run the same
tasks through the Model Context Protocol (MCP). It ships as a single static binary with no
runtime dependencies.
# Build the project.
build target="release": fetch
go build -tags {{target}} ./...
# Fetch dependencies.
fetch:
@go mod download
# Run tests.
test: build
go test ./...
rune # show the version + available tasks (runs nothing)
rune build # run the `build` task
rune test # runs `build` (a dependency), then `test`
rune --list # shows documented tasks
Why Rune?
If you've used make or just, Rune will feel familiar — with a few deliberate choices:
- Command runner, not a build system. Tasks always run when asked. No
.PHONYtraps, no timestamp-based "up-to-date" skipping. Content-hash caching exists, but only as an explicit per-task[cache(...)]opt-in. - Errors are a feature. Undefined variables, unknown dependencies, dependency cycles,
and arity mismatches are caught before anything runs, with precise
file:line:col+ caret-underlined diagnostics. - Boringly portable. One static binary. The default shell executor is a pure-Go,
cross-platform shell (
mvdan.cc/sh) — your(sh)tasks behave the same on Linux, macOS, and Windows, with no WSL or Git-Bash required. - AI-native and secure by default. Tasks are first-class MCP tools. Agent access is read-only by default, destructive tasks are gated, and secrets come from the environment only — never the Runefile.
- Multi-language bodies. Write task bodies in shell, Python, Node, or drive an AI agent.
- First-class editor support.
rune lspis a built-in language server (LSP 3.17): live diagnostics, completion, go-to-definition, hover, outline, and formatting in VS Code, Neovim, Helix, and Zed — reusing the same parser and analyzer, running nothing. For VS Code, install the Rune extension from the Marketplace.rune analyzereports the same diagnostics for CI. See editor setup.
Install
# Install script (Linux/macOS) — verifies the checksum:
curl -sSfL https://raw.githubusercontent.com/rune-task-runner/rune/main/scripts/install.sh | sh
# Homebrew (macOS/Linux):
brew install rune-task-runner/tap/rune
# Scoop (Windows):
scoop bucket add rune https://github.com/rune-task-runner/scoop-bucket && scoop install rune
# From source:
go install github.com/rune-task-runner/rune/cmd/rune@latest
Or grab a prebuilt binary from Releases, or run it in a container:
docker run --rm -v "$PWD":/work ghcr.io/rune-task-runner/rune --list
Full instructions: Installation guide.
Documentation
Start at the documentation index — it routes you to the right page by goal ("I want to…"). Highlights:
| Guide | What's inside |
|---|---|
| Docs index | Find any page by what you want to do |
| What is Rune? | The idea, the mental model, and when to use it |
| Getting started | Zero → your first task in minutes |
| User guide | A guided tour of every capability, in order |
| How-to guides | Task-oriented guides, one per capability |
| Use cases | Full walkthroughs: Python, Node, AI agents (MCP) |
| Examples | Runnable starting points for real project shapes |
| Installation | Binary, source, and container install per OS |
| CLI reference | Every command, flag, and exit code |
| Runefile language | Tasks, deps, params, caching, executors, dotenv |
| AI agents (MCP) | Expose tasks to agents; the security model |
| Docker | Run Rune install-free in a container |
| Troubleshooting | Errors, diagnostics, and exit codes |
| Grammar | The formal Runefile grammar |
Contributing
See CONTRIBUTING.md. In short: tests run inside Docker
(docker-compose run --rm test go test ./...), and every change must pass the CI gates
(format, lint, cross-platform race tests, fuzz smoke, golden consistency, build). Rune
dogfoods itself — run rune --list in the repo to see the development tasks.
Security
Found a vulnerability? Please follow the process in SECURITY.md.
License
MIT © The Rune Authors.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
rune
command
Command rune is a shared task runner for humans and AI agents.
|
Command rune is a shared task runner for humans and AI agents. |
|
internal
|
|
|
analysis
Package analysis is the reusable analysis service that wraps Rune's parse → compose → analyze pipeline behind a source-overlay abstraction.
|
Package analysis is the reusable analysis service that wraps Rune's parse → compose → analyze pipeline behind a source-overlay abstraction. |
|
analyzer
Package analyzer is the whole-file semantic analyzer.
|
Package analyzer is the whole-file semantic analyzer. |
|
ast
Package ast defines the Runefile abstract syntax tree produced by the parser and consumed by the analyzer, evaluator, scheduler, cache, and MCP server.
|
Package ast defines the Runefile abstract syntax tree produced by the parser and consumed by the analyzer, evaluator, scheduler, cache, and MCP server. |
|
cache
Package cache implements opt-in, per-task content-hash caching for tasks carrying [cache(inputs=[...], outputs=[...])].
|
Package cache implements opt-in, per-task content-hash caching for tasks carrying [cache(inputs=[...], outputs=[...])]. |
|
cli
Package cli wires the command-line surface: Runefile resolution, the parse → analyze → run pipeline, task dispatch, and exit-code mapping.
|
Package cli wires the command-line surface: Runefile resolution, the parse → analyze → run pipeline, task dispatch, and exit-code mapping. |
|
config
Package config handles Runefile discovery and settings resolution.
|
Package config handles Runefile discovery and settings resolution. |
|
diag
Package diag is the diagnostic model and renderer.
|
Package diag is the diagnostic model and renderer. |
|
dotenv
Package dotenv loads .env files into KEY=VALUE environment pairs for tasks (set dotenv).
|
Package dotenv loads .env files into KEY=VALUE environment pairs for tasks (set dotenv). |
|
eval
Package eval is the total tree-walking evaluator for the Runefile expression sublanguage: it turns an ast.Expr into a string Value.
|
Package eval is the total tree-walking evaluator for the Runefile expression sublanguage: it turns an ast.Expr into a string Value. |
|
formatter
Package formatter renders a parsed Runefile back into its canonical source form.
|
Package formatter renders a parsed Runefile back into its canonical source form. |
|
language
Package language provides language intelligence over an analysis Snapshot: the symbol index (by name, qualified name, and document), scope lookup, context-aware completion, definition resolution, hover content, and the single structured registry of Rune built-ins, settings, and attributes (spec FR-026, FR-027).
|
Package language provides language intelligence over an analysis Snapshot: the symbol index (by name, qualified name, and document), scope lookup, context-aware completion, definition resolution, hover content, and the single structured registry of Rune built-ins, settings, and attributes (spec FR-026, FR-027). |
|
lexer
Package lexer is a hand-written, state-function lexer (Pike style) for the Runefile language.
|
Package lexer is a hand-written, state-function lexer (Pike style) for the Runefile language. |
|
lsp
Package lsp is the protocol glue for `rune lsp`: a JSON-RPC 2.0 server over stdio speaking a minimal typed subset of LSP 3.17.
|
Package lsp is the protocol glue for `rune lsp`: a JSON-RPC 2.0 server over stdio speaking a minimal typed subset of LSP 3.17. |
|
mask
Package mask provides emission-time masking of secret values in Rune's output streams, so credentials never reach a terminal transcript or an agent's chat history (spec 013-secret-masking).
|
Package mask provides emission-time masking of secret values in Rune's output streams, so credentials never reach a terminal transcript or an agent's chat history (spec 013-secret-masking). |
|
parser
Package parser is a hand-written recursive-descent parser for the Runefile declarative grammar, with a Pratt sub-parser (expr.go) for the expression sublanguage.
|
Package parser is a hand-written recursive-descent parser for the Runefile declarative grammar, with a Pratt sub-parser (expr.go) for the expression sublanguage. |
|
runtime
Package runtime selects and drives the executor for a task body: the default pure-Go shell (internal/runtime/shell), a temp-file interpreter for python/node/custom or a `set shell` override (internal/runtime/interp), or the AI-agent driver (internal/runtime/agent).
|
Package runtime selects and drives the executor for a task body: the default pure-Go shell (internal/runtime/shell), a temp-file interpreter for python/node/custom or a `set shell` override (internal/runtime/interp), or the AI-agent driver (internal/runtime/agent). |
|
runtime/agent
Package agent runs (agent) task bodies by driving an installed agent CLI (claude/codex/copilot/…) behind a vendor-neutral Provider interface (Principle VII / FR-030).
|
Package agent runs (agent) task bodies by driving an installed agent CLI (claude/codex/copilot/…) behind a vendor-neutral Provider interface (Principle VII / FR-030). |
|
runtime/interp
Package interp runs python/node/custom (and `set shell`-override) task bodies by writing the interpolated body to a temp file and exec-ing the configured interpreter against it (the just shebang/[script] model).
|
Package interp runs python/node/custom (and `set shell`-override) task bodies by writing the interpolated body to a temp file and exec-ing the configured interpreter against it (the just shebang/[script] model). |
|
runtime/scheduler
Package scheduler builds and runs the task dependency DAG.
|
Package scheduler builds and runs the task dependency DAG. |
|
runtime/shell
Package shell runs (sh) task bodies through the pure-Go mvdan/sh interpreter.
|
Package shell runs (sh) task bodies through the pure-Go mvdan/sh interpreter. |
|
semver
Package semver is a small, dependency-free Semantic Versioning 2.0.0 parser and comparator, sufficient for Rune's `minimum_version` requirement gate.
|
Package semver is a small, dependency-free Semantic Versioning 2.0.0 parser and comparator, sufficient for Rune's `minimum_version` requirement gate. |
|
style
Package style is the single source of truth for Rune's non-interactive terminal styling.
|
Package style is the single source of truth for Rune's non-interactive terminal styling. |
|
styletest
Package styletest provides shared test helpers for asserting terminal styling.
|
Package styletest provides shared test helpers for asserting terminal styling. |
|
token
Package token defines the lexical tokens of the Runefile language and the source-position types that every token and AST node carries.
|
Package token defines the lexical tokens of the Runefile language and the source-position types that every token and AST node carries. |
|
tui
Package tui implements Rune's interactive task picker (the `--choose` experience) as a Bubble Tea program.
|
Package tui implements Rune's interactive task picker (the `--choose` experience) as a Bubble Tea program. |
|
Package mcpserver exposes a Runefile's non-private tasks to AI agents and IDEs as Model Context Protocol tools.
|
Package mcpserver exposes a Runefile's non-private tasks to AI agents and IDEs as Model Context Protocol tools. |
|
test
|
|
|
docs
Package docs holds the documentation verification harness.
|
Package docs holds the documentation verification harness. |
Click to show internal directories.
Click to hide internal directories.