Agent Backbone

Agents across different AI CLIs and projects, working as one personal team.
Communication, coordination and continuity for Claude Code, Codex and OpenCode.
Develop specialists whose experience carries into your next project.

Website · Watch · Quick start · Why Backbone · Docs · Security

Watch

agent-backbone-overview.mp4

why-agent-backbone.mp4

Overview (1:23) · Why Backbone (2:23) · YouTube playlist

Both films have English captions. Read the film guide.

Why Backbone

Agent Backbone brings agents across different AI CLIs and projects into one personal team. It provides the communication, coordination and continuity they need to work together, with working practices you can shape. Through that collaboration, retained lessons and feedback, specialists can develop expertise, share discoveries and refine their judgment, so each new project can benefit from the experience they have built.

Your agents use the logins you already have. Core use needs no setup in your repositories. Starter practices help the team collaborate, preserve useful reasoning and learn from feedback; you can edit or remove them.

Never typed into a busy agent Agents reach each other by name. When the recipient is working or waiting for you, the message is queued and delivered when the agent is ready, marked with who sent it. Ordinary messages expire after 30 minutes by default, and the sender is told.	No setup in your repositories An agent is a folder and the CLI you choose, and the folder is its name. Core use adds no configuration files, task schemas or commits to your projects.
GitHub Issues are the task list In a repository worker owns or watches, label an issue for:worker and it lands in worker's queue, one at a time. To hand work on, an agent opens an issue for another. The issue stays as the record.	Mix CLIs in one team Claude Code, Codex and OpenCode agents work side by side, and a swarm puts a coordinator and helpers on different CLIs on one branch. A second model can review the change.
In the loop from anywhere Watch any agent, step into its terminal, or answer from your phone. With Telegram set up in a group with topics, every agent outside a swarm gets its own topic, with Allow and Deny on permission prompts.	State you can check Backbone tracks whether each agent is idle, working or waiting for a person, and shows the evidence behind every reading. Your agents decide the work.

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.

For example, a README specialist can retain why an explanation worked, consult with another repository's agent and adapt that lesson to its readers. The team must record, test and revise its understanding; a role name or stored conversation alone does not make it more capable. Try that collaboration.

Use a desktop workspace

Agent Interface provides a native desktop for Backbone: terminals alongside team, activity, usage, skills and policy views. Its Reports & updates view brings together progress reports, saved answers and Documents. Rich HTML Documents currently render on macOS. Connect it to a running Backbone.

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. If your agent's CLI refuses a step on its own (Claude Code's auto mode can refuse backbone init), switch it to asking before each step (Shift+Tab in Claude Code) and approve them.

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

For a new installation, read backbone docs team and select its starter practices before launching agents:

backbone templates use starter-collaboration starter-swarms starter-continuity \
  starter-learning starter-artifacts starter-authority

On an existing installation, first inspect assignments with backbone templates use. Selection replaces the global list, so keep existing choices or use a tag. You can customize or remove any starter.

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. Develop your team follows a specialist's experience into another project. 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

CLI	Support
Claude Code, Codex, OpenCode	Required set: a capability ships only when it works on all three, and any open gap is tracked as a defect
Gemini CLI, Antigravity CLI, Deep Code, Aider	Supported on demand; each gap is listed in the capability table

Going further

• Develop your team: choose starting practices, collaborate with a specialist and carry useful lessons into another project.
• 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.
• Saved answers: return to a question, its answer and next action.
• Documents: keep detailed explanations and interactive HTML reports available beyond the conversation, with retained correction history.
• 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 coordinates user-owned agents on one machine. Their CLI harnesses enforce execution permissions and sandboxing; Backbone enforces the identity, access and delivery rules of its own capabilities. The API binds to localhost by default and requires a key. Agents receive scoped credentials, and launchers exclude Backbone's service secrets. An unrestricted same-user process can still read local files; Backbone adds no OS isolation boundary. Read Security for what is protected, what is not and how it is tested. Report vulnerabilities privately as described in SECURITY.md.

Development

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

To try a change, give a scratch install its own private home, tmux directory and port. From a terminal outside tmux:

scratch=$(mktemp -d /tmp/backbone-dev.XXXXXX)
unset $(env | grep -o '^BACKBONE_[A-Z_]*') CLAUDE_CONFIG_DIR CODEX_HOME
export HOME=$scratch TMUX_TMPDIR=$scratch BACKBONE_PORT=7199
.venv/bin/backbone init
.venv/bin/backbone up

Its profile, agents and tmux sessions stay apart from your own. Run other CLI commands for it with the same three settings. Restart up to pick up code changes.

See Contributing for branches, checks and releases.

License

MIT.