Root Use Cases

Safer alternative to Homebrew

Install CLI tools with a lockfile and an undo button. When a tool update breaks your workflow, roll back instead of debugging your global PATH.

root install jq
root verify jq
# something broke?
root rollback --last

Reproducible dev machines

Share root.lock across your team so everyone runs the same tool versions:

# On machine A
root install ripgrep fd bat
git add root.lock Rootfile

# On machine B
root restore --lock ./root.lock

AI coding agent tooling

Agents can install and verify tools without polluting global PATH. Use --json output for structured automation:

root plan install terraform --json
root install terraform --json
root verify terraform --json

Agent config portability

Transfer Codex, OpenCode, or Claude Code working configuration between machines — same agent, credential-free:

root agent-bundle export codex
root agent-bundle plan ./bundle.tar.gz
root agent-bundle apply ./bundle.tar.gz

Isolated task execution

Run tasks in Docker sandboxes without affecting your host environment:

root sandbox create my-task
root sandbox run my-task -- npm test
root sandbox destroy my-task

Local model management

Declared Ollama models are pull-and-verify records, not a bit-pin:

root plan models
root models pull

Resume in another harness

root resume --with codex (or claude / opencode) assembles a continuation package from recorded work. It does not copy a transcript.

root resume --with codex

Hand a route to a harness

root event pull --harness returns deliveries already handed to that harness. It does not start an agent.

root event pull --harness codex

Pair devices over a folder

root device pair and root checkpoint-sync exchange encrypted checkpoint references only. Git still carries source.

root device pair
root checkpoint-sync

Record a payment intent

root finance intent records a payment intent. Approve marks the record approved. It does not move money.

root finance intent