bones

Install install

$ brew install danmestas/tap/bones
$ bones --help

Or via Go: go install github.com/danmestas/bones/cmd/bones@latest. Tarballs for darwin/linux × amd64/arm64 are also published on every release: see releases.

What it is overview

bones is the CLI for orchestrating multiple AI coding agents against a shared codebase without merge conflicts, race conditions, or lost work. It bundles three command surfaces — Fossil repository operations, NATS sync and bridging, and workspace/orchestrator/task management native to bones — into a single binary.

The substrate underneath is purpose-built for parallel agent work: NATS JetStream KV holds tasks with CAS-gated claims, an embedded libfossil stores code artifacts and chat history with content-addressed commits, and a slot-partitioned plan format keeps agents on disjoint files by construction. Agents come and go; durable state outlasts them.

• Three surfaces, one binary. bones repo (Fossil ops, from libfossil), bones sync/bridge/notify (from EdgeSync), bones tasks/orchestrator/validate-plan (native).
• Augments your VCS — never replaces it. bones opens a Fossil sandbox alongside your git working tree (Fossil metadata is gitignored). Agents commit into the sandbox, race-resolve safely, then the merged result materializes in git as ordinary file changes. Your git stays the source of truth.
• Leaves memory to you. No remember/recall primitive baked in. Per-agent memory is the harness's concern (Claude Code's auto-memory); cross-agent facts go through chat threads or task context maps. Your memory tool stays your memory tool.
• Conflict-free by construction. Slot annotations on plan tasks are validated for directory disjointness before dispatch; runtime forks become impossible by design, not by lock contention.
• Pre-built Claude Code skills. bones orchestrator scaffolds three skills into .claude/skills/: orchestrator, subagent, and uninstall-bones. The substrate stays policy-neutral; the skills encode the orchestration policy.

Why you might want it why

Six things bones does that the obvious alternatives don't.

Trunk-based, by construction. Every leaf pulls from the hub before it commits, so commits parent off the latest tip — not whatever the agent saw at clone time. Ten agents in parallel produce one linear chain. No fan-in to untangle, no merge conflicts to resolve.

A worktree your filesystem doesn't see. Agents don't write to your working directory. They commit into the fossil repo first; the diff lands in your tree only when you sign off. Your editor never opens half-finished work it didn't ask for.

Two embedded dependencies. That's it. SQLite and NATS — both embedded in the binary. No Postgres to run, no Redis to babysit, no k8s. The hub starts when your shell does and goes away when you're done.

Built on Fossil's heritage. Fossil — Dr. Hipp's all-in-one SCM, tickets, and chat, born alongside SQLite — pioneered autosync for close-knit teams. bones inherits the discipline: one trunk, one truth, full history. bones peek opens straight into Fossil's UI.

Boring timelines are good timelines. A linear chain is dull to look at. That's the point. When every commit advances the same trunk, your timeline is a story you read top-to-bottom — not a graph you decode.

Observability without the vendor tax. OpenTelemetry exporters wired in if you have a stack. Skip it entirely and bones peek shows every commit, claim, and slot event in Fossil's native UI. Two paths, no required SaaS.

Trunk-based by construction architecture

Each agent owns a leaf — a per-slot Fossil clone that pulls the hub's latest tip before every commit. Concurrent agents land their commits in the order autosync resolves; the trunk advances as a single linear chain, never as parallel forks. bones apply lands the result in your git tree only when you sign off — agents never write to your working directory.

Compared to neighbors comparison

Different shapes for different bets. beads goes deep on a single managed substrate (Dolt-versioned task graph plus integrated memory) and ships the most mature plugin and MCP today. bones takes the opposite stance: it doesn't take over your VCS or your memory tool, and it splits state across NATS (live) and Fossil (durable) so real-time agent chat and slot-validated parallelism are first-class. Pick beads if you want one tool that owns task state, memory, and code-tracking. Pick bones if you want agent coordination without giving up git or your existing memory tooling.

What it is not limits

Not a hosted service. bones is a CLI; you run it locally or in CI. The orchestrator skill assumes a Claude Code session; the substrate is usable from any client that speaks NATS + Fossil.

Not a VCS replacement. This is deliberate. Your git history stays your git history. bones opens a Fossil checkout alongside the working tree (per ADR 0023, the Fossil metadata is gitignored) and uses it only as the agent sandbox where parallel commits race-resolve safely. After the swarm finishes, the merged result materializes in git as ordinary file changes. git stays the source of truth.

Not a memory system. Also deliberate. Per-agent memory is the harness's job (Claude Code's auto-memory writes to ~/.claude/projects/<project>/memory/). Cross-agent shared facts go through chat threads or task context maps. bones does not provide a remember/recall primitive — your memory tool stays your memory tool.

Not a Linear or Jira replacement. No roadmap views, no SLA tracking, no dashboards. Tasks here are agent-runtime artifacts, not product-management artifacts.

Not a single-agent tool. bones works for a single-agent workflow but the substrate cost (NATS server, Fossil hub) outweighs the benefit. If you have one agent, use libfossil directly — or just stick with git.

Get going start

$ brew install danmestas/tap/bones
$ cd my-project
$ bones up                                    # workspace + scaffold + leaf + hub
$ bones tasks create "first task" --files src/foo.go
$ bones tasks list

Walkthrough: /docs/quickstart · Concepts: /docs/concepts · CLI reference: /docs/reference/cli · Skills reference: /docs/reference/skills · Architecture: /docs/architecture · Source: github.com/danmestas/bones.