Spore is a small, local harness for LLM coding agents. It plants rules, task files, hooks, validation gates, and tmux worker sessions into an existing repo so agents can work on explicit tasks without turning the project into a SaaS workflow.

Status: beta, dogfooded on live projects.

• each task is a markdown file under tasks/;
• each active task gets its own git worktree and tmux session;
• a coordinator starts workers, watches progress, and kills stale sessions;
• hooks and lints run before a task can close;
• closing a task requires evidence: commits, changed files, tests, or a written reason none apply.

Everything runs in your repo through git and tmux. Attach to a session, read the task file, inspect the branch, or kill the fleet.

Spore installs with Nix. On a flake-based system, add it as an input and reference the package:

# flake.nix
inputs.spore.url = "github:versality/spore";

# NixOS
environment.systemPackages = [ inputs.spore.packages.${pkgs.system}.default ];

# home-manager
home.packages = [ inputs.spore.packages.${pkgs.system}.default ];

Or run it without installing:

nix run github:versality/spore -- <args>   # one-shot
nix shell github:versality/spore           # ephemeral shell on PATH
nix profile install github:versality/spore # imperative install

Adopt an existing project:

cd /path/to/project
spore bootstrap

Run spore bootstrap as many times as you like. Each run advances the setup as far as it can, then stops and tells you the one thing it needs from you next. The steps it walks through: scan the repo, find the test command, set up credentials, check the README, run the tests, and turn on the worker fleet.

When the project is worker-ready, create work and start the fleet:

spore task new "first task"
spore fleet enable
spore fleet reconcile

Each worker and the coordinator run in their own tmux session. Run spore fleet list-sessions to see them all.

spore infect installs NixOS over SSH onto a fresh, root-reachable VM, copies your repo over, and starts an Opus coordinator:

spore infect 203.0.113.7 --ssh-key ~/.ssh/id_ed25519 --repo . --coordinator-model opus
ssh -t spore@203.0.113.7

It wipes the target host, so point it only at a throwaway VM. See docs/infect.md for all flags, the Codex coordinator, and custom flakes.

Run spore init to scaffold a documented spore.toml. The main sections:

• docs/worker-mix.md - pick worker agents (Claude, Codex, any binary) per task by ratio or complexity rule.
• docs/matter.md - pull work from external sources (Linear, GitHub Issues) and mirror task transitions back.
• docs/fleet-module.md - autostart the fleet on NixOS hosts, horizontal scale, and graceful deployment drains.

Main extension points:

• internal/bootstrap/ detects bootstrap stages and pairs with runbooks in bootstrap/stages/.
• internal/task/ owns task frontmatter, lifecycle, worktree creation, inbox handling, and merge close paths.
• internal/fleet/ reconciles active tasks with tmux worker sessions and drives the matter sync prelude.
• internal/matter/ is the plugin layer for external work sources (e.g. linear).
• internal/hooks/ emits and runs Claude Code and Codex hook bindings through .claude/settings.json and .codex/hooks.json.
• internal/lints/ holds portable repo lints.
• internal/composer/ renders instruction files from rule fragments in rules/.
• nixosModules/spore-fleet.nix autostarts fleet reconciliation on NixOS hosts.

• docs/design.md - origin, design rationale, and unresolved tradeoffs.
• docs/worker-dispatch.md - why workers are spawned through tmux and how the merge close path works.
• docs/evidence.md - the evidence contract for task close gates.
• docs/budget.md - rolling Anthropic spend tracking and budget advice.
• docs/development.md - dev shell, just check, and the release recipe.
• bootstrap/README.md - bootstrap layout, skills, stage runbooks, and smoke test.

Spore is licensed under the Apache License, Version 2.0. See LICENSE for the full text.