agent-backbone 0.1.0__tar.gz → 0.2.0__tar.gz

{agent_backbone-0.1.0 → agent_backbone-0.2.0}/.gitignore

@@ -18,6 +18,10 @@ coverage_html/
 *.db
 *.db-journal
 
+# Backbone-local, never shared: swarm worktrees and the agents' shared memory
+# (.backbone/memory — see AGENTS.md)
+.backbone/
+
 # Editors / OS
 .idea/
 .vscode/

{agent_backbone-0.1.0 → agent_backbone-0.2.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: agent-backbone
-Version: 0.1.0
+Version: 0.2.0
 Summary: Local control plane for terminal AI agents: run them, message them, coordinate them through GitHub Issues, reach them from Telegram.
 Project-URL: Homepage, https://github.com/eandualem/agent-backbone
-Project-URL: Documentation, https://github.com/eandualem/agent-backbone/blob/main/docs/README.md
+Project-URL: Documentation, https://github.com/eandualem/agent-backbone/blob/main/docs/INDEX.md
 Project-URL: Source, https://github.com/eandualem/agent-backbone
 Project-URL: Issues, https://github.com/eandualem/agent-backbone/issues
 License: MIT
@@ -29,6 +29,7 @@ Requires-Dist: pydantic>=2.0
 Requires-Dist: python-dotenv>=1.0
 Requires-Dist: python-socketio>=5.11
 Requires-Dist: python-telegram-bot>=21.0
+Requires-Dist: rich>=14.1
 Requires-Dist: sqlalchemy[asyncio]>=2.0
 Requires-Dist: uvicorn[standard]>=0.32
 Provides-Extra: github-app
@@ -48,20 +49,38 @@ A lightweight control plane for the terminal coding agents you already use.
 
 agent-backbone runs Claude Code, Codex, OpenCode, Deep Code and other command-line agents as persistent sessions on your machine, and gives them what a single terminal cannot: a way to communicate with each other, a manager that knows what each of them is doing, a channel for delegating work, and a way to form teams around a task. The agents stay the tools you already run, with their own logins, configuration and model access. The backbone adds no model, no subscription and no files to your repositories.
 
-**What it enables**
+![An agent installs agent-backbone from PyPI, sets it up, starts a Claude Code agent and an OpenCode agent, splits the terminal to show them, and has them review each other's work](docs/media/demo.gif)
+
+*Unedited, at 3× speed. A Claude Code session on a clean Linux machine is asked to install agent-backbone and set it up, then to start a Claude agent and an OpenCode agent and have them work together. It installs from PyPI, follows `backbone help setup`, starts both agents, splits the terminal itself so you can watch them, and the two agents review each other's work — four messages across two runtimes, no human input after the two prompts.*
+
+**Contents** · [What it enables](#what-it-enables) · [Getting started](#getting-started) · [How it works](#how-it-works) · [Runtimes](#runtimes) · [Going further](#going-further) · [How it relates to other tools](#how-it-relates-to-other-tools) · [Security model](#security-model) · [Background](#background) · [Documentation](#documentation) · [Development](#development)
+
+## What it enables
+
+Four things, each of which the agents can do among themselves once the backbone is running.
 
 - **Communication.** Any agent can message any other — across CLIs, models and repositories — with a single command. A message is delivered only when the recipient is ready to receive it and stored until then, so an agent in the middle of a task is never interrupted by another.
 - **Management.** The backbone knows whether each agent is idle, working or waiting for a person, and shows the evidence behind that reading. Start, stop, inspect and attach to any agent from one place; hear about the ones that need you on Telegram.
 - **Delegation.** GitHub Issues are the task list. An issue opened in an agent's repository is that agent's work; a `for:<agent>` label routes an issue to a specific agent; comments return to whoever opened it; closing an issue hands the agent its next one. An orchestrator is simply an agent that watches several repositories.
 - **Teams.** When a task benefits from parallel work, an agent creates a swarm: a coordinator plus members on the runtimes and models it chooses, sharing one worktree and branch, finishing in a pull request. When the issue closes, the swarm is torn down and the branch remains.
 
-Every agent the backbone starts is told at launch who it is and how to use all of this, so agents can start other agents, subscribe to repositories, message each other and form teams without a person in the loop. You can watch any session at any time, or step in.
+By default, each new agent session the backbone starts is briefed at launch on who it is and how to use all of this, so agents can start other agents, subscribe to repositories, message each other and form teams without a person in the loop. (A resumed session keeps its earlier conversation and is not briefed again; a plain `shell` agent gets no brief; `agents.inject_brief` turns the brief off.) You can watch any session at any time, or step in.
+
+> **Status:** early release. The core — state detection, safe delivery, GitHub routing, swarms, Telegram, the API — is tested and has been exercised against live Claude Code, Codex, OpenCode and Deep Code sessions. [Status and roadmap](https://github.com/eandualem/agent-backbone/blob/main/docs/status-and-roadmap.md) records what is verified and what is not.
+
+## Getting started
+
+Run `backbone usage` for [quick usage](USAGE.md): start, resume, attach, rename
+and read agent progress with `backbone updates`.
+[Documentation index](docs/INDEX.md) gives a suggested reading order.
+
+Three commands install and run it; the fourth starts your first agent. Or hand the whole thing to an agent.
 
-> **Status:** pre-release. The core — state detection, safe delivery, GitHub routing, swarms, Telegram, the API — is tested and has been exercised against live Claude Code, Codex, OpenCode and Deep Code sessions. [Status and roadmap](https://github.com/eandualem/agent-backbone/blob/main/docs/status-and-roadmap.md) records what is verified and what is not.
+### Requirements
 
-## Install
+macOS or Linux, Python 3.11+, `tmux`, [uv](https://docs.astral.sh/uv/) (or pipx), and at least one agent CLI on your PATH.
 
-Requirements: macOS or Linux, Python 3.11+, `tmux`, [uv](https://docs.astral.sh/uv/) (or pipx), and at least one agent CLI on your PATH.
+### Install and run
 
 ```bash
 uv tool install "agent-backbone[github-app]"   # https://pypi.org/project/agent-backbone/
@@ -69,21 +88,21 @@ backbone init                                  # data directory, .env with an AP
 backbone service install                       # runs now and at every login (launchd / systemd --user)
 ```
 
-`pipx install "agent-backbone[github-app]"` works the same. If `backbone` is not found afterwards, run `uv tool update-shell` once and open a new terminal. `ab` is the same command under a short name (on macOS `/usr/sbin/ab`, Apache Bench, may shadow it — put `~/.local/bin` first in your PATH or use `backbone`).
+`pipx install "agent-backbone[github-app]"` works the same. If `backbone` is not found afterwards, run `uv tool update-shell` once and open a new terminal. `ab` is the same command under a short name (on macOS `/usr/sbin/ab`, Apache Bench, may shadow it — put `~/.local/bin` first in your PATH or use `backbone`). Where there is no launchd or systemd (a container), `backbone up --detach` runs it instead.
 
 There is no configuration file, no database server and no tunnel. Everything the backbone knows lives in `~/.local/share/agent-backbone/` (a SQLite file, hook state, `.env`); settings are changed with `backbone config set`.
 
-### Setting up with an agent
+### Or let an agent do it
 
-The setup can be delegated to any agent that has a shell — a Claude Code, Codex or OpenCode session in one of your repositories:
+Paste this into any agent that has a shell — a Claude Code, Codex or OpenCode session in one of your repositories:
 
 > Install agent-backbone from PyPI (`uv tool install "agent-backbone[github-app]"`), then run `backbone help setup` and follow it: get the backbone running, start an agent in this repository, and tell me what still needs me.
 
-Everything the agent needs ships with the package: `backbone help` (the playbooks — `setup`, `agents`, `messaging`, `github`, `swarms`) and `backbone docs` (this documentation, page by page).
+Everything the agent needs ships with the package: `backbone help` (the playbooks — `setup`, `agents`, `messaging`, `github`, `swarms`) and `backbone docs` (this documentation, page by page). The recording above starts with exactly this prompt.
 
-## First run
+### First agent
 
-An agent is started from the directory of the repository it will work in. The agent takes the directory's name, and that repository becomes its responsibility.
+An agent is started from the directory of the repository it will work in. It takes the directory's name, and that repository becomes its responsibility.
 
 ```bash
 cd ~/code/app
@@ -96,50 +115,62 @@ The second `tell` returns `"outcome": "agent_working"`: the message was not type
 
 ## How it works
 
+Six decisions the backbone makes for you; the full flows are in [How it works](https://github.com/eandualem/agent-backbone/blob/main/docs/how-it-works.md).
+
 - **Agents are discovered, not declared.** `backbone agent start` in a directory records the agent: its name, its runtime and model, and the repository read from `git remote origin`. The command returns when the agent is at its prompt; folder-trust dialogs are answered for you.
-- **State comes from the runtime first, the terminal second.** Claude Code reports its state through hooks the backbone installs for the session; every other runtime is read from its terminal. Every reading carries its evidence, visible in `backbone agent inspect`.
-- **Delivery is gated on state.** Text is pasted into an agent only when it is idle — not while it is working, waiting for a person, or while you are typing in that terminal. What cannot land now is queued in SQLite and delivered when the agent is free. The few deliberate exceptions are documented in [How it works](https://github.com/eandualem/agent-backbone/blob/main/docs/how-it-works.md).
+- **State comes from the runtime first, the terminal second.** Claude Code, Codex, Gemini CLI and OpenCode report their state through hooks the backbone wires into the session at launch, without touching the CLI's own configuration; the rest are read from their terminal. Every reading carries its evidence, visible in `backbone agent inspect`.
+- **Delivery is gated on state.** Text is pasted into an agent only when it is idle — not while it is working, waiting for a person, or while you are typing in that terminal. What cannot land now is queued in SQLite and delivered when the agent is free. The few deliberate exceptions are documented.
 - **Agents can unblock each other.** `backbone agent approve <name>` answers a runtime's permission dialog — only while it is on screen, only with its affirmative key, every approval audited — so a coordinator can keep a team moving without a person watching.
 - **Coordination goes through GitHub, per repository.** Nothing is configured per repository: GitHub credentials are set once, and every repository an agent owns or watches is tracked on its own, by polling or by webhook.
 - **You reach it from anywhere.** The CLI, Telegram (a forum topic per agent), and a REST + Socket.IO API for your own dashboard or automation. The backbone ships no UI.
 
 ## Runtimes
 
-Any CLI that runs in a terminal can be an agent; how much the backbone can do for it depends on the runtime:
+Any CLI that runs in a terminal can be an agent; how much the backbone can do for it depends on the runtime.
 
 | Runtime | Unattended start | Brief at launch | State detection | Delivery | Approve |
 |---|---|---|---|---|---|
 | `claude` (Claude Code) | ✅ | ✅ system prompt | ✅ hooks + terminal | ✅ verified | ✅ |
-| `codex` | ✅ | ✅ first prompt | ✅ terminal | ✅ verified | ✅ |
-| `opencode` | ✅ (no trust dialog) | ✅ first prompt | ✅ terminal | ✅ verified | ✅ |
+| `codex` | ✅ | ✅ first prompt | ✅ hooks + terminal | ✅ verified | ✅ |
+| `opencode` | ✅ (no trust dialog) | ✅ first prompt | ✅ hooks + terminal | ✅ verified | ✅ |
 | `deepcode` (Deep Code, DeepSeek) | ✅ (no trust dialog) | ✅ `-p` | ✅ terminal | ✅ verified | pending |
-| `gemini` | ✅ `--skip-trust` | ✅ first prompt | ✅ terminal | unverified¹ | — |
-| `aider`, `shell` | — | first message | terminal, best effort | untested | — |
+| `gemini` | ✅ `--skip-trust` | ✅ first prompt | ✅ hooks + terminal | unverified¹ | — |
+| `aider` | — | first message | terminal, best effort | untested | — |
+| `shell` | — | none | terminal, best effort | — | — |
 
 ¹ Gemini CLI 0.46 completes Google OAuth and then refuses personal accounts ("no longer supported for Gemini Code Assist for individuals"); the backbone reports such a session as `waiting_for_human`. Delivery to a signed-in Gemini session (e.g. `GEMINI_API_KEY`) has not been tested yet. Deep Code is `@vegamo/deepcode-cli`, the community CLI DeepSeek's docs point to; its permission dialog has not been captured yet, so `agent approve` refuses it until then.
 
 `backbone runtimes` lists every runtime, whether its binary is installed, and example model ids. The backbone does not manage per-repository runtime configuration (`CLAUDE.md`, `AGENTS.md`, MCP servers, …) — how a repository configures its tools is the repository's business.
 
-## Beyond the first run
+## Going further
+
+Each of these is one command or one short setup, and each has its own page.
 
-**GitHub in two commands.** Issues become the agents' task list in every repository they own or watch:
+### GitHub Issues as the task list
 
 ```bash
 gh auth token | backbone secrets set GITHUB_TOKEN   # the backbone's own .env, never a repo's
 backbone service install                            # restart to pick it up
 ```
 
-That is poll intake (every 60 s, nothing exposed). For instant delivery and automatic coverage of every repository you create, do the one-time GitHub App + webhook setup: [GitHub App setup](https://github.com/eandualem/agent-backbone/blob/main/docs/github-app-setup.md).
+That is poll intake (every 60 s, nothing exposed) in every repository an agent owns or watches. For instant delivery and automatic coverage of every repository you create, do the one-time GitHub App + webhook setup: [GitHub App setup](https://github.com/eandualem/agent-backbone/blob/main/docs/github-app-setup.md).
 
-**An orchestrator** watches the repositories it coordinates — `backbone agent start --watch acme/app --watch acme/web` — and opens issues for the others with `for:` and `from:` labels. **A swarm** puts parallel workers on one issue ([Swarms](https://github.com/eandualem/agent-backbone/blob/main/docs/swarms.md)). **Telegram** gives every agent a topic you can talk to from your phone ([Telegram](https://github.com/eandualem/agent-backbone/blob/main/docs/telegram.md)). **Your own view** builds on the [API](https://github.com/eandualem/agent-backbone/blob/main/docs/api.md).
+### Orchestrators, swarms, Telegram, your own view
+
+- **An orchestrator** watches the repositories it coordinates — `backbone agent start --watch acme/app --watch acme/web` — and opens issues for the others with `for:` and `from:` labels.
+- **A swarm** puts parallel workers on one issue: [Swarms](https://github.com/eandualem/agent-backbone/blob/main/docs/swarms.md).
+- **Telegram** gives every agent a topic you can talk to from your phone: [Telegram](https://github.com/eandualem/agent-backbone/blob/main/docs/telegram.md).
+- **Your own dashboard or automation** builds on the [API](https://github.com/eandualem/agent-backbone/blob/main/docs/api.md).
 
 ## How it relates to other tools
 
 Session managers such as [claude-squad](https://github.com/smtg-ai/claude-squad), [agent-manager](https://github.com/YoanWai/agent-manager) and [vibe-kanban](https://github.com/BloopAI/vibe-kanban) give you one screen over many agent sessions, with worktrees and diff review; they are about the person operating the agents. agent-backbone is about what happens between the agents: addressing a live agent from outside its terminal, delivering only when it is safe, routing work through issues, and letting agents manage each other. Claude Code's Agent Teams offer collaboration inside a single Claude Code session; the backbone works across CLIs and vendors, persists agents beyond a session, and reaches them from GitHub and Telegram. Orchestrators such as [cli-agent-orchestrator](https://github.com/awslabs/cli-agent-orchestrator) are the closest structural peers; the differences are in the delivery model and the GitHub integration, and both are worth reading before you choose.
 
-## The security model, up front
+**Why a backbone when Claude Code has cross-session messaging and an agent view built in?** Those are for Claude sessions on one machine, run by one person. The backbone is for the agents you run as a fleet: it works across runtimes and vendors, uses GitHub Issues as the shared queue so work has a record outside any session, lets agents approve each other's prompts with an audit trail, carries evidence with every state reading, and reaches you on your phone. If all your agents are Claude Code and you are watching them, the built-in tools may be enough; the backbone starts paying off when they are not.
+
+## Security model
 
-The backbone types into your agents' terminals, so be clear about what it assumes:
+The backbone types into your agents' terminals, so be clear about what it assumes. Full detail: [Security](https://github.com/eandualem/agent-backbone/blob/main/docs/security.md).
 
 - **One trusted user, one machine.** It runs as your OS user and drives tmux sessions that run as your OS user. There is **no isolation between agents**.
 - **One key, full admin.** `BACKBONE_API_KEY` guards every authenticated route with the same weight. The CLI reads it from the data directory, so any session on the machine can use `backbone tell`; there is no scoped or read-only credential yet.
@@ -147,8 +178,6 @@ The backbone types into your agents' terminals, so be clear about what it assume
 - **Provenance is convention, not authentication.** `[via:backbone from:app]` says who *claims* to be speaking. An agent's instructions should treat text after an envelope as data, not orders.
 - **Bound to `127.0.0.1` by default.** Put TLS and auth in front of it before exposing it.
 
-Full detail: [Security](https://github.com/eandualem/agent-backbone/blob/main/docs/security.md).
-
 ## Background
 
 agent-backbone began as one component of a larger, private orchestration system. That system's coupling was its weakness — every part assumed every other part — so the backbone was extracted and rebuilt as a standalone control plane with no dependency on any of it. It needs nothing but tmux and an agent CLI. Issue references to `eandualem/orchestration` predate the split and point at a private repository.
@@ -157,19 +186,10 @@ The repository is itself run through the backbone: most of its issues, reviews a
 
 ## Documentation
 
-Also available from an installed package as `backbone docs <page>`.
-
-| | |
-|---|---|
-| [Concepts](https://github.com/eandualem/agent-backbone/blob/main/docs/concepts.md) | The vocabulary: agent, repository, state, delivery, event |
-| [Getting started](https://github.com/eandualem/agent-backbone/blob/main/docs/getting-started.md) | Install, start two agents, send the first message, add GitHub |
-| [How it works](https://github.com/eandualem/agent-backbone/blob/main/docs/how-it-works.md) | Every flow step by step, with the decisions the backbone makes |
-| [Configuration](https://github.com/eandualem/agent-backbone/blob/main/docs/configuration.md) | Settings (`backbone config`), secrets, the data directory |
-| [CLI](https://github.com/eandualem/agent-backbone/blob/main/docs/cli.md) · [API](https://github.com/eandualem/agent-backbone/blob/main/docs/api.md) | Reference |
-| [GitHub](https://github.com/eandualem/agent-backbone/blob/main/docs/github.md) · [App setup walkthrough](https://github.com/eandualem/agent-backbone/blob/main/docs/github-app-setup.md) · [Integrations](https://github.com/eandualem/agent-backbone/blob/main/docs/integrations.md) · [Telegram](https://github.com/eandualem/agent-backbone/blob/main/docs/telegram.md) | Integrations |
-| [Swarms](https://github.com/eandualem/agent-backbone/blob/main/docs/swarms.md) | A coordinator plus members on one issue |
-| [Security](https://github.com/eandualem/agent-backbone/blob/main/docs/security.md) | Defaults and what you opt into |
-| [Status and roadmap](https://github.com/eandualem/agent-backbone/blob/main/docs/status-and-roadmap.md) | What works, what is missing, what is next |
+Start with [Quick usage](USAGE.md) or the [documentation index](docs/INDEX.md).
+Every page ships with the package: `backbone docs index` gives the reading guide;
+`backbone docs <page>` opens a reference. Agent playbooks live in [help/](help/),
+and injected instructions live in [templates/](templates/).
 
 ## Development
 
@@ -186,3 +206,5 @@ make dev         # backbone up --reload
 ## License
 
 MIT — see [LICENSE](https://github.com/eandualem/agent-backbone/blob/main/LICENSE).
+
+Injected instructions are separate from help: see [templates/](templates/) and [the templates guide](docs/templates.md). Use `backbone templates list` to inspect an installed Backbone.

{agent_backbone-0.1.0 → agent_backbone-0.2.0}/README.md

@@ -9,20 +9,38 @@ A lightweight control plane for the terminal coding agents you already use.
 
 agent-backbone runs Claude Code, Codex, OpenCode, Deep Code and other command-line agents as persistent sessions on your machine, and gives them what a single terminal cannot: a way to communicate with each other, a manager that knows what each of them is doing, a channel for delegating work, and a way to form teams around a task. The agents stay the tools you already run, with their own logins, configuration and model access. The backbone adds no model, no subscription and no files to your repositories.
 
-**What it enables**
+![An agent installs agent-backbone from PyPI, sets it up, starts a Claude Code agent and an OpenCode agent, splits the terminal to show them, and has them review each other's work](docs/media/demo.gif)
+
+*Unedited, at 3× speed. A Claude Code session on a clean Linux machine is asked to install agent-backbone and set it up, then to start a Claude agent and an OpenCode agent and have them work together. It installs from PyPI, follows `backbone help setup`, starts both agents, splits the terminal itself so you can watch them, and the two agents review each other's work — four messages across two runtimes, no human input after the two prompts.*
+
+**Contents** · [What it enables](#what-it-enables) · [Getting started](#getting-started) · [How it works](#how-it-works) · [Runtimes](#runtimes) · [Going further](#going-further) · [How it relates to other tools](#how-it-relates-to-other-tools) · [Security model](#security-model) · [Background](#background) · [Documentation](#documentation) · [Development](#development)
+
+## What it enables
+
+Four things, each of which the agents can do among themselves once the backbone is running.
 
 - **Communication.** Any agent can message any other — across CLIs, models and repositories — with a single command. A message is delivered only when the recipient is ready to receive it and stored until then, so an agent in the middle of a task is never interrupted by another.
 - **Management.** The backbone knows whether each agent is idle, working or waiting for a person, and shows the evidence behind that reading. Start, stop, inspect and attach to any agent from one place; hear about the ones that need you on Telegram.
 - **Delegation.** GitHub Issues are the task list. An issue opened in an agent's repository is that agent's work; a `for:<agent>` label routes an issue to a specific agent; comments return to whoever opened it; closing an issue hands the agent its next one. An orchestrator is simply an agent that watches several repositories.
 - **Teams.** When a task benefits from parallel work, an agent creates a swarm: a coordinator plus members on the runtimes and models it chooses, sharing one worktree and branch, finishing in a pull request. When the issue closes, the swarm is torn down and the branch remains.
 
-Every agent the backbone starts is told at launch who it is and how to use all of this, so agents can start other agents, subscribe to repositories, message each other and form teams without a person in the loop. You can watch any session at any time, or step in.
+By default, each new agent session the backbone starts is briefed at launch on who it is and how to use all of this, so agents can start other agents, subscribe to repositories, message each other and form teams without a person in the loop. (A resumed session keeps its earlier conversation and is not briefed again; a plain `shell` agent gets no brief; `agents.inject_brief` turns the brief off.) You can watch any session at any time, or step in.
+
+> **Status:** early release. The core — state detection, safe delivery, GitHub routing, swarms, Telegram, the API — is tested and has been exercised against live Claude Code, Codex, OpenCode and Deep Code sessions. [Status and roadmap](https://github.com/eandualem/agent-backbone/blob/main/docs/status-and-roadmap.md) records what is verified and what is not.
+
+## Getting started
+
+Run `backbone usage` for [quick usage](USAGE.md): start, resume, attach, rename
+and read agent progress with `backbone updates`.
+[Documentation index](docs/INDEX.md) gives a suggested reading order.
+
+Three commands install and run it; the fourth starts your first agent. Or hand the whole thing to an agent.
 
-> **Status:** pre-release. The core — state detection, safe delivery, GitHub routing, swarms, Telegram, the API — is tested and has been exercised against live Claude Code, Codex, OpenCode and Deep Code sessions. [Status and roadmap](https://github.com/eandualem/agent-backbone/blob/main/docs/status-and-roadmap.md) records what is verified and what is not.
+### Requirements
 
-## Install
+macOS or Linux, Python 3.11+, `tmux`, [uv](https://docs.astral.sh/uv/) (or pipx), and at least one agent CLI on your PATH.
 
-Requirements: macOS or Linux, Python 3.11+, `tmux`, [uv](https://docs.astral.sh/uv/) (or pipx), and at least one agent CLI on your PATH.
+### Install and run
 
 ```bash
 uv tool install "agent-backbone[github-app]"   # https://pypi.org/project/agent-backbone/
@@ -30,21 +48,21 @@ backbone init                                  # data directory, .env with an AP
 backbone service install                       # runs now and at every login (launchd / systemd --user)
 ```
 
-`pipx install "agent-backbone[github-app]"` works the same. If `backbone` is not found afterwards, run `uv tool update-shell` once and open a new terminal. `ab` is the same command under a short name (on macOS `/usr/sbin/ab`, Apache Bench, may shadow it — put `~/.local/bin` first in your PATH or use `backbone`).
+`pipx install "agent-backbone[github-app]"` works the same. If `backbone` is not found afterwards, run `uv tool update-shell` once and open a new terminal. `ab` is the same command under a short name (on macOS `/usr/sbin/ab`, Apache Bench, may shadow it — put `~/.local/bin` first in your PATH or use `backbone`). Where there is no launchd or systemd (a container), `backbone up --detach` runs it instead.
 
 There is no configuration file, no database server and no tunnel. Everything the backbone knows lives in `~/.local/share/agent-backbone/` (a SQLite file, hook state, `.env`); settings are changed with `backbone config set`.
 
-### Setting up with an agent
+### Or let an agent do it
 
-The setup can be delegated to any agent that has a shell — a Claude Code, Codex or OpenCode session in one of your repositories:
+Paste this into any agent that has a shell — a Claude Code, Codex or OpenCode session in one of your repositories:
 
 > Install agent-backbone from PyPI (`uv tool install "agent-backbone[github-app]"`), then run `backbone help setup` and follow it: get the backbone running, start an agent in this repository, and tell me what still needs me.
 
-Everything the agent needs ships with the package: `backbone help` (the playbooks — `setup`, `agents`, `messaging`, `github`, `swarms`) and `backbone docs` (this documentation, page by page).
+Everything the agent needs ships with the package: `backbone help` (the playbooks — `setup`, `agents`, `messaging`, `github`, `swarms`) and `backbone docs` (this documentation, page by page). The recording above starts with exactly this prompt.
 
-## First run
+### First agent
 
-An agent is started from the directory of the repository it will work in. The agent takes the directory's name, and that repository becomes its responsibility.
+An agent is started from the directory of the repository it will work in. It takes the directory's name, and that repository becomes its responsibility.
 
 ```bash
 cd ~/code/app
@@ -57,50 +75,62 @@ The second `tell` returns `"outcome": "agent_working"`: the message was not type
 
 ## How it works
 
+Six decisions the backbone makes for you; the full flows are in [How it works](https://github.com/eandualem/agent-backbone/blob/main/docs/how-it-works.md).
+
 - **Agents are discovered, not declared.** `backbone agent start` in a directory records the agent: its name, its runtime and model, and the repository read from `git remote origin`. The command returns when the agent is at its prompt; folder-trust dialogs are answered for you.
-- **State comes from the runtime first, the terminal second.** Claude Code reports its state through hooks the backbone installs for the session; every other runtime is read from its terminal. Every reading carries its evidence, visible in `backbone agent inspect`.
-- **Delivery is gated on state.** Text is pasted into an agent only when it is idle — not while it is working, waiting for a person, or while you are typing in that terminal. What cannot land now is queued in SQLite and delivered when the agent is free. The few deliberate exceptions are documented in [How it works](https://github.com/eandualem/agent-backbone/blob/main/docs/how-it-works.md).
+- **State comes from the runtime first, the terminal second.** Claude Code, Codex, Gemini CLI and OpenCode report their state through hooks the backbone wires into the session at launch, without touching the CLI's own configuration; the rest are read from their terminal. Every reading carries its evidence, visible in `backbone agent inspect`.
+- **Delivery is gated on state.** Text is pasted into an agent only when it is idle — not while it is working, waiting for a person, or while you are typing in that terminal. What cannot land now is queued in SQLite and delivered when the agent is free. The few deliberate exceptions are documented.
 - **Agents can unblock each other.** `backbone agent approve <name>` answers a runtime's permission dialog — only while it is on screen, only with its affirmative key, every approval audited — so a coordinator can keep a team moving without a person watching.
 - **Coordination goes through GitHub, per repository.** Nothing is configured per repository: GitHub credentials are set once, and every repository an agent owns or watches is tracked on its own, by polling or by webhook.
 - **You reach it from anywhere.** The CLI, Telegram (a forum topic per agent), and a REST + Socket.IO API for your own dashboard or automation. The backbone ships no UI.
 
 ## Runtimes
 
-Any CLI that runs in a terminal can be an agent; how much the backbone can do for it depends on the runtime:
+Any CLI that runs in a terminal can be an agent; how much the backbone can do for it depends on the runtime.
 
 | Runtime | Unattended start | Brief at launch | State detection | Delivery | Approve |
 |---|---|---|---|---|---|
 | `claude` (Claude Code) | ✅ | ✅ system prompt | ✅ hooks + terminal | ✅ verified | ✅ |
-| `codex` | ✅ | ✅ first prompt | ✅ terminal | ✅ verified | ✅ |
-| `opencode` | ✅ (no trust dialog) | ✅ first prompt | ✅ terminal | ✅ verified | ✅ |
+| `codex` | ✅ | ✅ first prompt | ✅ hooks + terminal | ✅ verified | ✅ |
+| `opencode` | ✅ (no trust dialog) | ✅ first prompt | ✅ hooks + terminal | ✅ verified | ✅ |
 | `deepcode` (Deep Code, DeepSeek) | ✅ (no trust dialog) | ✅ `-p` | ✅ terminal | ✅ verified | pending |
-| `gemini` | ✅ `--skip-trust` | ✅ first prompt | ✅ terminal | unverified¹ | — |
-| `aider`, `shell` | — | first message | terminal, best effort | untested | — |
+| `gemini` | ✅ `--skip-trust` | ✅ first prompt | ✅ hooks + terminal | unverified¹ | — |
+| `aider` | — | first message | terminal, best effort | untested | — |
+| `shell` | — | none | terminal, best effort | — | — |
 
 ¹ Gemini CLI 0.46 completes Google OAuth and then refuses personal accounts ("no longer supported for Gemini Code Assist for individuals"); the backbone reports such a session as `waiting_for_human`. Delivery to a signed-in Gemini session (e.g. `GEMINI_API_KEY`) has not been tested yet. Deep Code is `@vegamo/deepcode-cli`, the community CLI DeepSeek's docs point to; its permission dialog has not been captured yet, so `agent approve` refuses it until then.
 
 `backbone runtimes` lists every runtime, whether its binary is installed, and example model ids. The backbone does not manage per-repository runtime configuration (`CLAUDE.md`, `AGENTS.md`, MCP servers, …) — how a repository configures its tools is the repository's business.
 
-## Beyond the first run
+## Going further
+
+Each of these is one command or one short setup, and each has its own page.
 
-**GitHub in two commands.** Issues become the agents' task list in every repository they own or watch:
+### GitHub Issues as the task list
 
 ```bash
 gh auth token | backbone secrets set GITHUB_TOKEN   # the backbone's own .env, never a repo's
 backbone service install                            # restart to pick it up
 ```
 
-That is poll intake (every 60 s, nothing exposed). For instant delivery and automatic coverage of every repository you create, do the one-time GitHub App + webhook setup: [GitHub App setup](https://github.com/eandualem/agent-backbone/blob/main/docs/github-app-setup.md).
+That is poll intake (every 60 s, nothing exposed) in every repository an agent owns or watches. For instant delivery and automatic coverage of every repository you create, do the one-time GitHub App + webhook setup: [GitHub App setup](https://github.com/eandualem/agent-backbone/blob/main/docs/github-app-setup.md).
 
-**An orchestrator** watches the repositories it coordinates — `backbone agent start --watch acme/app --watch acme/web` — and opens issues for the others with `for:` and `from:` labels. **A swarm** puts parallel workers on one issue ([Swarms](https://github.com/eandualem/agent-backbone/blob/main/docs/swarms.md)). **Telegram** gives every agent a topic you can talk to from your phone ([Telegram](https://github.com/eandualem/agent-backbone/blob/main/docs/telegram.md)). **Your own view** builds on the [API](https://github.com/eandualem/agent-backbone/blob/main/docs/api.md).
+### Orchestrators, swarms, Telegram, your own view
+
+- **An orchestrator** watches the repositories it coordinates — `backbone agent start --watch acme/app --watch acme/web` — and opens issues for the others with `for:` and `from:` labels.
+- **A swarm** puts parallel workers on one issue: [Swarms](https://github.com/eandualem/agent-backbone/blob/main/docs/swarms.md).
+- **Telegram** gives every agent a topic you can talk to from your phone: [Telegram](https://github.com/eandualem/agent-backbone/blob/main/docs/telegram.md).
+- **Your own dashboard or automation** builds on the [API](https://github.com/eandualem/agent-backbone/blob/main/docs/api.md).
 
 ## How it relates to other tools
 
 Session managers such as [claude-squad](https://github.com/smtg-ai/claude-squad), [agent-manager](https://github.com/YoanWai/agent-manager) and [vibe-kanban](https://github.com/BloopAI/vibe-kanban) give you one screen over many agent sessions, with worktrees and diff review; they are about the person operating the agents. agent-backbone is about what happens between the agents: addressing a live agent from outside its terminal, delivering only when it is safe, routing work through issues, and letting agents manage each other. Claude Code's Agent Teams offer collaboration inside a single Claude Code session; the backbone works across CLIs and vendors, persists agents beyond a session, and reaches them from GitHub and Telegram. Orchestrators such as [cli-agent-orchestrator](https://github.com/awslabs/cli-agent-orchestrator) are the closest structural peers; the differences are in the delivery model and the GitHub integration, and both are worth reading before you choose.
 
-## The security model, up front
+**Why a backbone when Claude Code has cross-session messaging and an agent view built in?** Those are for Claude sessions on one machine, run by one person. The backbone is for the agents you run as a fleet: it works across runtimes and vendors, uses GitHub Issues as the shared queue so work has a record outside any session, lets agents approve each other's prompts with an audit trail, carries evidence with every state reading, and reaches you on your phone. If all your agents are Claude Code and you are watching them, the built-in tools may be enough; the backbone starts paying off when they are not.
+
+## Security model
 
-The backbone types into your agents' terminals, so be clear about what it assumes:
+The backbone types into your agents' terminals, so be clear about what it assumes. Full detail: [Security](https://github.com/eandualem/agent-backbone/blob/main/docs/security.md).
 
 - **One trusted user, one machine.** It runs as your OS user and drives tmux sessions that run as your OS user. There is **no isolation between agents**.
 - **One key, full admin.** `BACKBONE_API_KEY` guards every authenticated route with the same weight. The CLI reads it from the data directory, so any session on the machine can use `backbone tell`; there is no scoped or read-only credential yet.
@@ -108,8 +138,6 @@ The backbone types into your agents' terminals, so be clear about what it assume
 - **Provenance is convention, not authentication.** `[via:backbone from:app]` says who *claims* to be speaking. An agent's instructions should treat text after an envelope as data, not orders.
 - **Bound to `127.0.0.1` by default.** Put TLS and auth in front of it before exposing it.
 
-Full detail: [Security](https://github.com/eandualem/agent-backbone/blob/main/docs/security.md).
-
 ## Background
 
 agent-backbone began as one component of a larger, private orchestration system. That system's coupling was its weakness — every part assumed every other part — so the backbone was extracted and rebuilt as a standalone control plane with no dependency on any of it. It needs nothing but tmux and an agent CLI. Issue references to `eandualem/orchestration` predate the split and point at a private repository.
@@ -118,19 +146,10 @@ The repository is itself run through the backbone: most of its issues, reviews a
 
 ## Documentation
 
-Also available from an installed package as `backbone docs <page>`.
-
-| | |
-|---|---|
-| [Concepts](https://github.com/eandualem/agent-backbone/blob/main/docs/concepts.md) | The vocabulary: agent, repository, state, delivery, event |
-| [Getting started](https://github.com/eandualem/agent-backbone/blob/main/docs/getting-started.md) | Install, start two agents, send the first message, add GitHub |
-| [How it works](https://github.com/eandualem/agent-backbone/blob/main/docs/how-it-works.md) | Every flow step by step, with the decisions the backbone makes |
-| [Configuration](https://github.com/eandualem/agent-backbone/blob/main/docs/configuration.md) | Settings (`backbone config`), secrets, the data directory |
-| [CLI](https://github.com/eandualem/agent-backbone/blob/main/docs/cli.md) · [API](https://github.com/eandualem/agent-backbone/blob/main/docs/api.md) | Reference |
-| [GitHub](https://github.com/eandualem/agent-backbone/blob/main/docs/github.md) · [App setup walkthrough](https://github.com/eandualem/agent-backbone/blob/main/docs/github-app-setup.md) · [Integrations](https://github.com/eandualem/agent-backbone/blob/main/docs/integrations.md) · [Telegram](https://github.com/eandualem/agent-backbone/blob/main/docs/telegram.md) | Integrations |
-| [Swarms](https://github.com/eandualem/agent-backbone/blob/main/docs/swarms.md) | A coordinator plus members on one issue |
-| [Security](https://github.com/eandualem/agent-backbone/blob/main/docs/security.md) | Defaults and what you opt into |
-| [Status and roadmap](https://github.com/eandualem/agent-backbone/blob/main/docs/status-and-roadmap.md) | What works, what is missing, what is next |
+Start with [Quick usage](USAGE.md) or the [documentation index](docs/INDEX.md).
+Every page ships with the package: `backbone docs index` gives the reading guide;
+`backbone docs <page>` opens a reference. Agent playbooks live in [help/](help/),
+and injected instructions live in [templates/](templates/).
 
 ## Development
 
@@ -147,3 +166,5 @@ make dev         # backbone up --reload
 ## License
 
 MIT — see [LICENSE](https://github.com/eandualem/agent-backbone/blob/main/LICENSE).
+
+Injected instructions are separate from help: see [templates/](templates/) and [the templates guide](docs/templates.md). Use `backbone templates list` to inspect an installed Backbone.

agent_backbone-0.2.0/USAGE.md

@@ -0,0 +1,105 @@
+# Quick usage
+
+**Open this guide in your terminal: `backbone usage`** (`ab usage` works too).
+`backbone docs usage` opens the same page. Use `backbone --help` for all commands.
+
+Prefer an agent to handle setup? Point it to [README.md](README.md) and ask it
+to follow `backbone help setup`.
+
+## Start Backbone manually
+
+```bash
+uv tool install "agent-backbone[github-app]"
+backbone init
+backbone service install          # start now and at login
+backbone status
+```
+
+Without a login service (for example, in a container), use `backbone up --detach`.
+Run `backbone doctor` if setup needs attention.
+
+## Work with an agent
+
+```bash
+cd ~/code/app
+backbone agent start --runtime codex --model gpt-6-astra:high
+backbone agent attach app         # open its terminal; Ctrl-b d detaches
+backbone agent start app          # continue its saved conversation if stopped
+backbone agent start app --fresh  # new conversation, same CLI and model
+backbone updates                  # latest progress from the team
+```
+
+An already running agent stays running. Starting from its directory also finds
+its registered name. Choose `--runtime` and `--model` explicitly to change them;
+changing CLI without a model clears the old CLI's model setting.
+
+## Read agent progress
+
+```bash
+backbone updates                              # latest reports from the team
+backbone updates --agent Feynman               # one agent's latest report
+backbone updates --agent Feynman --history     # its earlier reports
+backbone updates show 12                       # full report and links (use an ID shown above)
+backbone updates --limit 20                    # a larger page
+```
+
+When a page has more results, it prints the command for the next page. Reports
+show goals, progress, blockers and next steps. “No report yet” means that agent
+has not published one. Reading reports does not interrupt agents or ask them to
+produce one. `backbone status` shows whether agents are working; `backbone updates`
+shows what they say they have accomplished.
+
+In Telegram, use `/updates`, `/updates Feynman`, `/updates history Feynman`, or
+`/updates show 12`. Each new report is also posted automatically to the configured
+agents group and, for ordinary agents, the agent’s own topic, with buttons for the full report and team feed. Delivery retries
+when Telegram is unavailable; older reports from before this feature are not sent.
+
+## Publish your progress (for agents)
+
+```bash
+backbone report --example > progress.json
+# Replace the example with your goal, progress, blockers and next steps.
+backbone report --file progress.json --validate
+backbone report --file progress.json
+```
+
+The author defaults to the current agent; use `--agent NAME` outside an agent
+session. Reports must be short; oversized reports are rejected. See
+`backbone help reports` for the section limits and when to publish.
+
+## Rename an agent
+
+Wait until the agent finishes its work, then:
+
+```bash
+backbone agent stop planner
+backbone agent rename planner Feynman
+backbone agent start Feynman --attach
+```
+
+The directory, settings, watches and saved conversation ID stay with the agent.
+Use the new name in messages, scripts and external `for:` labels. Renaming requires
+a stopped agent; active swarm members cannot be renamed.
+
+## Find more
+
+- `backbone agent start --help` — command options.
+- `backbone templates list` — injected instructions you can inspect and edit.
+- `backbone docs index` — the [documentation reading guide](docs/INDEX.md).
+- `backbone docs usage` — this page from an installed package.
+
+Ordinary agent reports appear in General and the agent's topic, with separate
+delivery receipts. Swarm participants, including coordinators, cannot publish human-facing reports.
+Only their repository agent reports consolidated progress to the owner. Optional full-report voice messages can be enabled with
+`backbone config set telegram.report_audio true` after local speech setup.
+See `backbone docs report-audio` for the model, service, voice and FFmpeg setup.
+
+
+During long work, agents can read corrections themselves without waiting for
+terminal delivery: `backbone inbox` (or `--agent NAME`). After applying or
+superseding messages, use `backbone inbox --ack TOKEN ...`. Check between meaningful
+steps and before a commit or handoff. Details: `backbone help messaging`.
+
+For `--ack`, copy each complete `ack_token` from the inbox response. Numeric row
+IDs alone cannot acknowledge work; tokens prevent stale acknowledgements from
+consuming a different message after queue cleanup.

agent_backbone-0.2.0/docs/INDEX.md

@@ -0,0 +1,42 @@
+# Documentation index
+
+Start with [Quick usage](../USAGE.md) for everyday commands. Each page is also
+available as `backbone docs PAGE` after installation (for example,
+`backbone docs getting-started`). Filenames stay stable so saved links keep working.
+
+## 1. Get started
+
+1. [Getting started](getting-started.md) — install, start agents and send a message.
+2. [Concepts](concepts.md) — names, runtimes, states and delivery conditions.
+3. [CLI reference](cli.md) — start, resume, attach, rename and configure agents.
+
+## 2. Run your team
+
+- [Report audio](report-audio.md) — optional local read-aloud in Telegram.
+- [Progress reports](reports.md) — goals, progress, blockers and next steps.
+- [Instruction templates](templates.md) — edit base, role and tag instructions.
+- [Deep reviews](deep-reviews.md) — run reviews in the background and retrieve findings.
+- [Swarms](swarms.md) — coordinate several agents on one task.
+- [Configuration](configuration.md) — settings, secrets and data locations.
+- [Diagnostics](diagnostics.md) — investigate failures, retries and startup problems.
+
+## 3. Connect other tools
+
+- [GitHub](github.md) — issue routing and review notifications.
+- [GitHub App setup](github-app-setup.md) — configure webhook intake.
+- [Telegram](telegram.md) — talk to agents and read updates from your phone.
+- [API reference](api.md) — build scripts and dashboards.
+- [Integrations](integrations.md) — add another communication channel.
+
+## 4. Understand and contribute
+
+- [How it works](how-it-works.md) — follow requests through the system.
+- [Security](security.md) — trust boundaries and defaults.
+- [Status and roadmap](status-and-roadmap.md) — verified capabilities and remaining work.
+- [Contributing](../CONTRIBUTING.md) — development and checks.
+
+## Help, templates and media
+
+[Help](../help/) contains short playbooks agents request with `backbone help`.
+[Templates](../templates/) contains instructions injected at launch.
+[Media](media/) contains documentation illustrations and recordings.

agent_backbone-0.2.0/docs/README.md

@@ -0,0 +1,7 @@
+# Documentation
+
+Open [INDEX.md](INDEX.md) for the reading order and grouped reference pages.
+For everyday commands, start with [Quick usage](../USAGE.md).
+
+Installed package: `backbone docs index` or `backbone docs usage`.
+Agent playbooks: `backbone help`. Injected instructions: `backbone templates list`.