README
¶
____ ___ _ _ _____ ____
| __ ) / _ \| \ | | ____/ ___|
| _ \| | | | \| | _| \___ \
| |_) | |_| | |\ | |___ ___) |
|____/ \___/|_| \_|_____|____/
multi-agent orchestration
bones
Containerized isolation for your source tree, with trunk-based development built in for parallel AI agents. Drop ten Claude subagents on a repo and bones gives each one its own checkout, syncs commits through a single hub before parenting (so the trunk advances linearly under any concurrency), and lands changes in your filesystem only when you sign off. Two embedded dependencies — SQLite and NATS — in a single static binary. No Postgres, no Redis, no Docker required. Doesn't replace git. Doesn't have opinions about your memory tool.
If you've been running 3+ sessions in parallel and watching them stomp on each other through a shared working tree, this is what fixes it.
Install
# Recommended (Homebrew):
brew install danmestas/tap/bones
# Alternative (Go modules):
go install github.com/danmestas/bones/cmd/bones@latest
# Direct download:
# https://github.com/danmestas/bones/releases/latest
The bones binary is self-contained — embedded NATS, embedded libfossil, and the orchestrator/subagent/uninstall-bones Claude Code skills are baked into the binary and scaffolded by bones up.
Quick Start
cd ~/your-repo
bones up
That's it — scaffolds .bones/, .orchestrator/, and .claude/skills/ into your project, brings up an embedded fossil hub on 127.0.0.1:8765, and installs Claude Code SessionStart/Stop hooks that auto-start the hub when you open the project.
Then in Claude Code, write a plan with [slot: name] annotations on tasks and ask it to "run this plan in parallel." The orchestrator skill validates slot disjointness, dispatches one subagent per slot, and each leaf commits through the hub. Or use bones tasks create / list / claim / close for a personal backlog you work serially.
Full docs: bones.daniel-mestas.workers.dev.
Why bones
- Trunk-based, by construction. Every leaf pulls from the hub before each commit, so commits parent off the latest tip. Parallel sessions produce one linear chain — no fan-in to untangle.
- Worktree your filesystem doesn't see. Agents commit into the fossil repo first; the diff lands in your tree only when you sign off.
- Two embedded dependencies. SQLite and NATS, statically linked. No external services, no Docker.
- Doesn't replace git. The fossil sandbox sits alongside your git working tree (its files are gitignored). Your git stays the source of truth.
What bones up creates
your-repo/
├── .bones/ # workspace marker, per-process state
│ ├── config.json # agent_id, NATS URL, leaf HTTP URL
│ ├── repo.fossil # per-agent fossil clone (syncs from the hub)
│ ├── leaf.pid # pid of the long-running leaf daemon
│ └── swarm/<slot>/wt/ # per-slot worktrees, created on `swarm join`
├── .orchestrator/
│ ├── hub.fossil # shared trunk: code, tasks, chat, presence
│ ├── nats-store/ # JetStream persistence
│ ├── pids/{fossil,nats}.pid
│ └── scripts/ # SessionStart + Stop hooks
└── .claude/
├── settings.json # hub-bootstrap / hub-shutdown hooks merged in
└── skills/ # orchestrator · subagent · uninstall-bones
The hub fossil holds durable state (commits, tasks, presence, chat). Each leaf is a standalone fossil clone that syncs with the hub via NATS-bridged HTTP xfer. Tasks live in NATS JetStream KV with CAS-gated claims; commits, chat, and presence land in fossil tables.
Commands
bones --help lists everything. Top-level groups:
| group | what it does |
|---|---|
bones tasks |
backlog: create / list / show / update / claim / close / watch / status / link |
bones swarm |
slot lifecycle: join / commit / close / status / cwd / fan-in |
bones repo |
fossil ops via libfossil: ci / co / timeline / diff / cat / config / merge / ... |
bones sync / bridge / notify |
NATS-side coordination (from EdgeSync) |
bones up / init / orchestrator / hub / peek / doctor / validate-plan |
lifecycle + tooling |
Add -v to any command for DEBUG-level slog output. Default is silent.
Uninstall
bones down # confirms before removing anything
bones down reverses bones up: stops the hub, removes .bones/ and .orchestrator/, removes the scaffolded skills under .claude/skills/, and prunes only the bones-installed hooks from .claude/settings.json (leaving unrelated hooks intact). Flags: --yes skips the prompt, --dry-run prints the plan, --keep-hub / --keep-skills / --keep-hooks for partial uninstalls.
From inside Claude Code: ask it to "uninstall bones" — the bundled uninstall-bones skill walks through the same steps interactively.
Remove the binary: brew uninstall bones (or delete $(go env GOPATH)/bin/bones if you go installed).
License
Apache-2.0. See [LICENSE](LICENSE).
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cli holds embeddable Kong commands for the bones binary.
|
Package cli holds embeddable Kong commands for the bones binary. |
|
cmd
|
|
|
bones
command
Command bones is the unified bones CLI.
|
Command bones is the unified bones CLI. |
|
examples
|
|
|
herd-hub-leaf
command
Package herdhubleaf is a thundering-herd trial harness for the hub-and-leaf architecture (ADR 0023).
|
Package herdhubleaf is a thundering-herd trial harness for the hub-and-leaf architecture (ADR 0023). |
|
hub-leaf-e2e
Package hubleafe2e is an E2E sanity harness for the hub-leaf architecture (ADR 0023).
|
Package hubleafe2e is an E2E sanity harness for the hub-leaf architecture (ADR 0023). |
|
two-agents
command
Command two-agents is a smoke harness that spawns two child processes, each opening its own coord.Coord against a shared leaf, and asserts six Phase 3+4 coord primitives work across real process boundaries.
|
Command two-agents is a smoke harness that spawns two child processes, each opening its own coord.Coord against a shared leaf, and asserts six Phase 3+4 coord primitives work across real process boundaries. |
|
internal
|
|
|
assert
Package assert provides runtime invariant checks for coord internals.
|
Package assert provides runtime invariant checks for coord internals. |
|
banner
Package banner emits the bones ASCII banner on stdout.
|
Package banner emits the bones ASCII banner on stdout. |
|
chat
Package chat is the substrate layer that backs coord's Post, Ask, and Subscribe on top of EdgeSync's notify service.
|
Package chat is the substrate layer that backs coord's Post, Ask, and Subscribe on top of EdgeSync's notify service. |
|
coord
Package coord is the single public entry point for bones.
|
Package coord is the single public entry point for bones. |
|
githook
Package githook installs and removes the bones pre-commit hook in the host repository's .git/hooks directory.
|
Package githook installs and removes the bones pre-commit hook in the host repository's .git/hooks directory. |
|
holds
Package holds is the substrate layer that stores file-level holds in a NATS JetStream KV bucket.
|
Package holds is the substrate layer that stores file-level holds in a NATS JetStream KV bucket. |
|
hub
Package hub starts and stops the embedded Fossil hub repo and the embedded NATS JetStream server that together form the orchestrator substrate documented in ADR 0023.
|
Package hub starts and stops the embedded Fossil hub repo and the embedded NATS JetStream server that together form the orchestrator substrate documented in ADR 0023. |
|
jskv
Package jskv holds JetStream KV primitives shared across the CAS-backed substrate packages (internal/holds, internal/tasks, and any future Phase 4 consumer — presence, subscriber registry).
|
Package jskv holds JetStream KV primitives shared across the CAS-backed substrate packages (internal/holds, internal/tasks, and any future Phase 4 consumer — presence, subscriber registry). |
|
presence
Package presence is the substrate layer that backs coord's Who and WatchPresence.
|
Package presence is the substrate layer that backs coord's Who and WatchPresence. |
|
scaffoldver
Package scaffoldver tracks which bones binary version scaffolded the current workspace's .bones/, .orchestrator/, and .claude/skills trees.
|
Package scaffoldver tracks which bones binary version scaffolded the current workspace's .bones/, .orchestrator/, and .claude/skills trees. |
|
swarm
Package swarm holds the per-slot session record schema and the JetStream-KV-backed Manager that bones swarm verbs use to track active swarm sessions in a workspace.
|
Package swarm holds the per-slot session record schema and the JetStream-KV-backed Manager that bones swarm verbs use to track active swarm sessions in a workspace. |
|
tasks
Package tasks is the substrate layer that stores task records in a NATS JetStream KV bucket.
|
Package tasks is the substrate layer that stores task records in a NATS JetStream KV bucket. |
|
telemetry
Package telemetry is the single seam between bones command code and any OpenTelemetry tracer.
|
Package telemetry is the single seam between bones command code and any OpenTelemetry tracer. |
|
testutil/natstest
Package natstest provides an embedded NATS server fixture for tests.
|
Package natstest provides an embedded NATS server fixture for tests. |
|
updatecheck
Package updatecheck queries GitHub for the latest bones release tag and emits a one-line stderr notice when the running binary is behind.
|
Package updatecheck queries GitHub for the latest bones release tag and emits a one-line stderr notice when the running binary is behind. |
|
version
Package version exposes the running binary's semver to other packages without dragging in a dependency on cmd/bones.
|
Package version exposes the running binary's semver to other packages without dragging in a dependency on cmd/bones. |
|
workspace
Package workspace manages a bones workspace: the .bones/ directory, its on-disk config, and the associated leaf daemon process.
|
Package workspace manages a bones workspace: the .bones/ directory, its on-disk config, and the associated leaf daemon process. |
|
wspath
Package wspath defines the typed coordination key for a workspace file.
|
Package wspath defines the typed coordination key for a workspace file. |