rune

April 5, 2026~3 minArchived

Why I built this

Signal

Running Claude Code across many projects at once, each project's skills, subagents and rules lived as markdown under its own .claude directory. Each project held its own copy of every prompt, so a fix made in one copy had no path to the others, and nothing recorded which copy was current. That is the problem a package manager solves, with prompts in place of packages.

Build

rune was our approach to a skill package manager: one canonical copy in a git repository, every project a synced install of it, and a record exact enough that drift was a fact to read off.

Novel

Little of the design was new to package managers. The two choices worth keeping were where the check ran and where authority sat. A Claude Code hook ran the check on every write under .claude, so drift came back to the agent in the same turn as the edit. The registry was the only authoritative copy and rune push the only way an edit reached it; a plain commit inside a project shipped nothing. The lockfile made the drift states exact, down to which side had moved.

rune was a Rust command-line tool that managed three kinds of markdown under a project’s .claude/ directory: skills (workflow instructions an agent reads to perform a task), subagent definitions, and rules (conditional instructions scoped to a context). It worked the way a package manager works: a git repository, a registry in rune’s vocabulary, held the canonical copy; each project’s .claude/skills/, .claude/agents/ and .claude/rules/ was a synced working copy; a lockfile recorded what was installed and from where. The packages were prompts an agent read mid-session, so the tool also had to tell the agent when its copy had drifted.

Registry, synced copies and drift hook

One git registry held the skills, subagents and rules.
Every project carried a synced copy under .claude.
A hook named the drift in the same turn as the write.
Push was the only way back to the registry.

The lockfile is what made the check exact.

Sync, lockfile, drift states, push

sync wrote the items into .claude and .claude/rune.lock: per item, the source registry, a content hash and the registry-side commit.
rune setup installed a Claude Code PostToolUse hook on Edit and Write; a write under .claude ran rune check on that file and handed the result to the agent as context.
check compared the local and registry hashes against the locked one: CURRENT, DRIFTED with a direction (local newer, registry newer, diverged), MISSING, or REGISTRY MISSING.
push copied the edited file into the registry’s working tree, committed there and pushed.

Push is authoritativeA plain git commit inside a project never shipped a skill edit anywhere; it orphaned the change on one machine. The edit left only when rune push <name> ran, and the hook put that nudge in the turn the edit landed.

A git-sourced registry supported push and @version pins, resolved to a commit and enforced on every later sync, so a moved tag was a hard error; an archive-sourced one (a read-only tarball) could do neither and said so. Skills imported from third-party registries carried pedigree metadata: origin, upstream commit, whether the local copy had changed. The command surface was measured with jig, the agent-shape harness, from an agent-shape.toml in the repository.

rune managed the .claude layout and nothing else: no other runtime’s directory, no sync across runtimes.

Created Apr 2026 · Archived Jun 2026

Retrospective →