0.3.0

Watch

https://github.com/user-attachments/assets/695a6096-4196-4115-911c-a0043d632088

_{The overview, 1:23, captioned. Unmute for the narration.}

Up next  ›

Why Backbone

You already run coding agents in your terminal. Each one works alone, and you carry every message between them. Backbone turns them into a team.

New sessions are briefed on these tools, so you can ask any agent to set up the team you need: an agent per repository, skills and rules shared by tag, specialists on request.

Quick start

Let your agent do it. Open the coding agent you already use and say:

Install agent-backbone with uv tool install agent-backbone,
then run backbone help setup and follow it.

The setup playbook is written for agents: each step ends with a check and says when it needs you, for your accounts and secrets.

Or by hand. You need macOS or Linux, Python 3.11+, tmux, uv (or pipx), and an agent CLI installed and signed in.

uv tool install agent-backbone
backbone init
backbone service install           # start now and at login
backbone doctor                    # check dependencies and API access

Then, from a repository you want an agent to work in:

cd ~/code/app
backbone agent start --runtime claude   # or --runtime codex, --runtime opencode
backbone tell app "Summarise what this repository does in three sentences."
backbone agent attach app               # read its reply; Ctrl-b d detaches

The folder supplies the agent name. If startup reports a prompt or a timeout, backbone agent inspect app shows what needs attention. tell reports whether the message was delivered or queued; delivery does not mean the agent has finished answering. A queued message waits until the agent is ready, up to 30 minutes by default, so do not resend a message the queue accepted. If backbone is not on your PATH, run uv tool update-shell and open a new terminal. In a container without a login service, use backbone up --detach. ab is a short alias; on macOS, use backbone if Apache Bench shadows it.

Getting started walks through a second agent, GitHub and Telegram. Quick usage is the everyday command guide.

Built to be relied on

• One delivery gate. Everything typed into an agent's terminal passes the same readiness check. Busy agents are never interrupted, and every message carries where it came from.
• The same result on every required CLI. A capability ships only when it works the same in Claude Code, Codex and OpenCode, checked by the same behaviour test on each. The runtime capability table and backbone doctor read one contract, and gaps are listed, not hidden.
• More than 3,500 tests, run on every change with no network, models or services.
• Built with itself. Backbone is developed by agents running inside a Backbone in daily use. The films in this README were made the same way.
• An honest security model. One trusted user on one machine, an API on localhost, and a clear account of what agents can reach. Read Security before granting access.

Backbone is not an agent framework: it calls no models and needs no model API keys. It is not a workflow engine or a dashboard either. It gives your agents names, safe messages and evidence, and leaves the work to them.

Works with

Going further

• GitHub: route issues and review notifications, starting with token-based polling. GitHub App setup adds webhooks.
• Swarms: put several specialists on one task.
• Skills: keep one copy of each skill, tag it, and every agent with that tag finds it in its own CLI.
• Telegram: send messages and read reports from your phone.
• Token usage: tokens by agent, conversation and model.
• API: build a dashboard or automation; Backbone ships no UI.
• Runtime support and limits: checked capabilities, unsupported environments and known limitations.
• How it works: state detection, delivery and routing.

The documentation index covers configuration, diagnostics and the remaining references. Installed copies are available through backbone docs; backbone help contains short agent playbooks.

Security model

Backbone runs as one trusted OS user on one machine. Agents are not isolated from each other. The API binds to localhost by default and uses one full-admin key; local sessions can read that key through the CLI. Backbone keeps its control-plane secrets out of launched environments, but this is not a filesystem security boundary. Read Security before granting access or exposing the API.

Development

git clone https://github.com/eandualem/agent-backbone
cd agent-backbone
make install
make check
BACKBONE_DATA_DIR=/tmp/backbone-dev make dev

make dev runs on its own tmux server, so its agents stay apart from your own tmux sessions and from a real backbone's agents. Run CLI commands for it from a terminal outside tmux with the same settings, for example TMUX_TMPDIR=/tmp/backbone-dev-tmux-$(id -u) BACKBONE_DATA_DIR=/tmp/backbone-dev uv run backbone agent attach NAME. agent attach, and agent commands run while make dev is stopped, use tmux directly.

See Contributing for branches, checks and releases.

License

MIT.