@axelgar/opentree 1.0.2 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Àxel García Roigé
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,54 @@
+opentree — third-party notices
+==============================
+
+opentree itself is distributed under the MIT Licence; see LICENSE. This file
+records the third-party names, marks and code that opentree touches, and the
+rights it does not claim in them.
+
+
+Trade marks
+-----------
+
+opentree drives coding agents it did not write. It draws each one under that
+agent's own name, wordmark and brand colour so that the agent you are talking
+to is identifiable at a glance, and those wordmarks are reproduced as terminal
+text in pkg/config/agents.go, transcribed from each tool's own splash screen.
+
+  opencode         "opencode", its wordmark and the colour #CFCECD are marks of
+                   the opencode project.
+
+  Claude Code      "Anthropic", "Claude", "Claude Code", the Claude mark and
+                   the colour #D97757 are marks of Anthropic PBC.
+
+  GitHub Copilot   "GitHub", "Copilot", "GitHub Copilot", the Copilot mark and
+                   the colour #A371F7 are marks of GitHub, Inc.
+
+  Gemini CLI       "Google", "Gemini", "Gemini CLI", the Gemini sparkle and the
+                   colour #4285F4 are marks of Google LLC.
+
+All trade marks, service marks, trade names and logos are the property of their
+respective owners. They appear here only to identify the tools opentree can
+drive, descriptively and accurately, and no claim of any right in them is made
+or implied.
+
+opentree is an independent project. It is not affiliated with, sponsored by,
+endorsed by or otherwise connected to any of the owners named above; none of
+them has reviewed or approved it, and its MIT licence grants no rights in
+anyone's marks.
+
+If you own one of these marks and would prefer opentree did not reproduce it,
+open an issue at https://github.com/axelgar/opentree/issues and it will be
+changed.
+
+
+Third-party code
+----------------
+
+opentree redistributes no code belonging to the projects above. The one adapter
+it needs — @agentclientprotocol/claude-agent-acp, which bridges Claude Code onto
+the Agent Client Protocol — is fetched from npm when the user asks for it and
+installed under ~/.opentree/tools, under its own licence. `opentree uninstall`
+removes that directory again.
+
+The Go modules opentree links against are listed in go.mod and carry their own
+licences.

package/README.md

@@ -17,10 +17,15 @@ opentree is a cross-platform CLI tool that manages multiple AI coding agent sess
 - **🔀 Parallel Development**: Work on multiple branches simultaneously without checkout overhead
 - **📝 Diff Viewer**: Review changes before committing
 - **🚀 PR Creation**: Create GitHub PRs directly from the TUI with auto-generated title and body
+- **✈️ Autopilot**: After each agent turn, run your check command, feed failures back, and publish the PR when it passes — per workspace, opt-in
+- **📦 Dispatch**: `opentree dispatch 42 --headless` turns an issue into a PR with nobody watching, exiting with a code a script can branch on
+- **⑂ Fan-out**: `opentree new feat/x --agents claude,opencode,gemini` races the same task across agents — grouped in the dashboard, compared side by side, the winner promoted and the rest deleted
 - **🐛 Issue Workflow**: Create a workspace directly from a GitHub issue number
 - **✅ CI Status**: Live CI check status displayed per workspace
 - **🔍 Filter & Sort**: Filter workspaces by name, sort by name/age/activity/PR status
-- **🧹 Clean Lifecycle**: Archive workspaces after merge, keeping your repo tidy
+- **🔌 Agent Plugins**: Install a plugin from the open [Agent Plugins](https://agent-plugins.org) standard once, and every agent in every worktree can use the skills it bundles
+- **🗂 ACP Registry**: `opentree agents add <id>`, or `a` on the dashboard's Agents tab, installs any agent the [ACP Registry](https://agentclientprotocol.com/get-started/registry) lists, and it becomes first-class everywhere the built-in four are — chats, fan-outs, per-workspace overrides
+- **🧹 Clean Lifecycle**: A merged PR marks its row `merged · ready to delete`, and `opentree delete --merged` clears them all at once
 - **⌨️ Shell Completion**: Tab completion for workspace names in bash, zsh, and fish
 
 ## Requirements
@@ -60,6 +65,16 @@ sudo mv opentree /usr/local/bin/
 go install github.com/axelgar/opentree/cmd/opentree@latest
 ```
 
+### Uninstalling
+
+```bash
+opentree uninstall
+```
+
+Removes what opentree wrote into your home directory: the agent adapters under `~/.opentree/tools` (a few hundred megabytes each), the agents installed from the ACP Registry under `~/.opentree/registry` along with its cached index, the plugins installed under `~/.opentree/plugins`, the record of approved setup and run commands, the shell completion script and the global config file. It lists all of it with sizes and asks before removing anything — `--dry-run` lists and stops, `--yes` answers the question from a script.
+
+It never touches a repository, and it never touches a worktree. The worktrees under `~/.opentree/worktrees` (or wherever `base_dir` points) are your own work in progress, and `opentree delete <branch>` is what removes those. The binary belongs to whichever of brew, npm or `go install` put it there, so the command that removes it is printed at the end.
+
 ## Quick Start
 
 ```bash
@@ -72,13 +87,16 @@ opentree
 # Or use CLI commands directly
 opentree new feat/add-auth       # Create workspace
 opentree issue 42                # Create workspace from GitHub issue #42
-opentree list                    # List all workspaces
+opentree dispatch 42 --headless  # Issue #42 → agent → checks → PR, unattended
+opentree list                    # List all workspaces, with their paths
 opentree attach feat/add-auth    # Attach to tmux window
+opentree shell feat/add-auth     # A shell in the worktree, beside the chat
 opentree diff feat/add-auth      # Review changes
 opentree pr feat/add-auth        # Create GitHub PR
 opentree delete feat/add-auth    # Clean up workspace
 opentree skills list             # See every agent skill on this machine
 opentree skills sync             # Give every agent and workspace the repo's skills
+opentree plugins add <git-url>   # Install an Agent Plugin once, for every agent
 ```
 
 ## Usage
@@ -101,31 +119,59 @@ opentree
 - `n` - Create new workspace (prompts for branch name, then base branch)
 - `i` - Create workspace from a GitHub issue number
 - `Enter` - Attach to selected workspace
-- `d` - Show diff for selected workspace
+- `d` - Show diff for selected workspace (`pgup`/`pgdn` page it, `g`/`G` jump to the ends)
+- `D` - Compare a fan-out group: every sibling's diff in one scroll
+- `W` - Promote a fan-out's winner: keep this sibling, delete the rest
 - `p` - Create PR for selected workspace (auto-generates title and body from commits)
 - `o` - Open PR in browser
 - `x` - Delete selected workspace (shows diff confirmation if uncommitted changes)
 - `R` - Send the workspace's open PR review comments to its agent
+- `P` - Switch the workspace's autopilot on or off
 - `w` - Start or stop the workspace's dev server
+- `u` - Merge the base branch in (fetched from origin first); conflicts are offered to the agent
+- `t` - Open a shell in the workspace's worktree, in a tmux window beside its chat
+- `y` - Copy the worktree's path to the clipboard
+- `e` - Open the worktree in `$VISUAL`/`$EDITOR`
 - `b` - Jump to the workspace that has been waiting longest on a permission (press again to cycle)
 - `space` - Toggle multi-select on current workspace
 - `/` - Filter workspaces by name
 - `s` - Cycle sort order (name → age → activity → PR)
 - `E` - Toggle error log
-- `tab` - Switch between Workspaces, Skills and Servers
+- `tab` - Switch between Workspaces, Agents, Skills, Plugins and Servers
 - `?` - Toggle full help
 - `q` - Quit
 
+The mouse works too: the wheel scrolls, a click selects a row, and a
+double-click attaches to it.
+
 Each row also carries what its agent is doing — working, waiting on a
 permission, stopped — plus cost and context use, read live from the chat's
 control socket. Open PRs show **CI check status** badges.
 
+### Agents
+
+Press `tab` once for every agent this machine knows — the built-in four and
+whatever was installed from the ACP Registry — with its readiness, where it
+came from, and which one this repository uses. It is `opentree agents` as a
+place rather than a set of commands:
+
+- `enter` - Use this agent for the repository (`g` for everywhere)
+- `a` - Browse the ACP Registry and install an agent (`/` filters the list)
+- `u` - Update the selected registry agent (`U` checks every one)
+- `i` - Fetch a built-in agent's ACP adapter
+- `x` - Remove a registry agent, or clear a broken install
+- `r` - Rescan the store, without touching the network
+
+Every install shows the same consent card the command line prints — what will
+run or what will be downloaded, and where — before anything is fetched. See
+[Agents from the ACP Registry](#agents-from-the-acp-registry).
+
 ### Skills
 
 Skills are a filesystem convention rather than anything an agent exposes over
 its API — a directory holding a `SKILL.md` — so opentree reads them directly.
-Press `tab` for the inventory: every skill on the machine, which agents can
-actually use each one, and what each agent will do with it.
+Press `tab` twice for the inventory: every skill on the machine, which agents
+can actually use each one, and what each agent will do with it.
 
 - `enter` - Open the SKILL.md in `$EDITOR`
 - `a` - Add a skill from a git URL
@@ -140,6 +186,30 @@ their skills untracked — so opentree links the repository's skills into each
 workspace it creates. `opentree skills sync` repairs workspaces that predate
 this, and `opentree skills list` prints the same inventory for a script.
 
+### Plugins
+
+opentree is a client of the open [Agent Plugins](https://agent-plugins.org)
+standard: a plugin is a directory with a `plugin.json` manifest, skills under
+`skills/`, and optionally an `mcp.json` naming MCP servers.
+
+```bash
+opentree plugins add https://github.com/someone/their-plugin
+opentree plugins list            # what each plugin declares, secrets masked
+opentree plugins remove <name>   # the store entry and every link into it
+```
+
+Install one and every agent in every worktree can use the skills it bundles:
+the clone lands once per machine in `~/.opentree/plugins`, is validated
+against the spec — a broken manifest refuses the whole plugin, a broken skill
+or server entry costs only itself and is reported — and its skills are linked
+into each agent's own user-scope tree. On the Skills tab they wear their
+provenance (`plugin:<name>` and `ro`); the Plugins tab shows each plugin as a
+unit, with `a` to install, `x` to remove, and every declared MCP server named.
+
+Declared is as far as it goes: opentree lists a plugin's MCP servers with
+their env and header values masked, and neither launches them nor writes them
+into any agent's own configuration. Nothing a plugin ships is executed.
+
 ### Talking to the agent
 
 opentree talks to agents over the [Agent Client Protocol](https://agentclientprotocol.com)
@@ -181,7 +251,7 @@ agent's own logo, in its own colours:
 ```
  ▐▛███▜▌    Claude Code
 ▝▜█████▛▘   fix-auth
-  ▘▘ ▝▝     ~/src/myrepo/.opentree/fix-auth
+  ▘▘ ▝▝     ~/.opentree/worktrees/myrepo/fix-auth
 ```
 
 | Key | |
@@ -189,15 +259,34 @@ agent's own logo, in its own colours:
 | `enter` | send |
 | `shift+enter` | newline — `ctrl+j` where the terminal cannot report modifiers |
 | `↑` / `↓` | walk back through the messages already sent, and forward again |
-| `/` | slash commands — the agent's own, plus `/resume`, `/login`, `/model` and the rest |
+| `/` | slash commands — the agent's own, plus `/resume`, `/login`, `/model`, `/shell`, `/export` and the rest |
 | `@` | attach a file from this worktree |
 | `ctrl+v` | paste — an image on the clipboard is attached, anything else is text |
-| `esc` | interrupt the current turn |
-| `shift+tab` | cycle the agent's mode (plan / build / …) |
+| `esc` | interrupt the current turn — or clear an unsent message (`↑` brings it back) |
+| `shift+tab` | cycle the agent's mode (plan / build / …) — Claude Code's plan mode and accept-edits included |
 | `ctrl+g` | settings — model, reasoning effort, anything else the agent declares |
 | `ctrl+o` | show or hide the agent's reasoning |
+| `ctrl+x` | expand what the last tool call held back, and fold it again |
+| `ctrl+r` | retry a failed turn — the same message, pasted images included |
+| `ctrl+y` | copy — the last reply, any code block in it, the last tool's output, or the whole conversation as markdown |
+| `ctrl+f` | find in the conversation — `ctrl+n` / `ctrl+p` step through the matches, `esc` leaves the log where it stands |
+| `drag` | select text — it goes to the clipboard when the button comes up; double-click takes a word, triple-click a row. `shift+drag` (`option+drag` in iTerm2) is the terminal's own selection, which still works |
+| `click` | a permission option answers it; a `… 42 more lines` row opens the way `ctrl+x` does |
 | `?` | every key |
 
+**Prose.** The agent's replies render as markdown while they stream: emphasis,
+headings, lists, quotes, and fenced code on its own background, syntax-coloured
+when the fence names a language — code is never rewrapped, so its indentation
+keeps meaning. A half-arrived fence already reads
+as code and never snaps back to prose; a lone `**` stays two asterisks until
+its closer arrives. Tables render as the text they are.
+
+**Tool output.** A tool row shows a few lines of what it did — the diff, or
+what it printed — and holds the rest back behind `… 42 more lines · ctrl+x`.
+`ctrl+x` opens the most recent held-back row where you are reading, up to 500
+lines; the same key folds it again. There is no cursor to place: the row you
+want open is the one that just said how much it was hiding.
+
 **Newlines.** `shift+enter` breaks the line instead of sending it, with nothing
 to configure. A terminal left to itself sends a bare carriage return for
 `shift+enter` — the same byte `enter` sends, and nothing downstream can tell the
@@ -226,6 +315,17 @@ forward again, and coming back past the newest returns whatever was half typed
 when you started looking — so a prompt worth repeating, or repeating with one
 word changed, is a keypress away rather than a retype. Inside a message the
 arrows still move the cursor: they only recall from its first and last row.
+They are kept per workspace, under `~/.opentree/history`, so a window closed
+and reopened — or a chat restarted after its agent died — still has the last
+two hundred.
+
+**Messages you have not sent yet.** Enter while the agent is still working
+queues the message instead of dropping it: it waits as a `⏳` line above the
+box, one fires after each finished turn — so each answer still gets read
+before the next question goes — and backspace on an empty box takes the
+newest one back to be edited, pasted images and all. A failed turn drops the
+queue by name rather than firing into a broken session; `↑` still has every
+message.
 
 **Earlier conversations.** `/resume` lists what this worktree has already
 talked about — newest first, by what each conversation was about — and picking
@@ -233,6 +333,10 @@ one reopens it in place, history and all. The list is the agent's own where it
 keeps one, merged with what opentree recorded itself, so the command works the
 same whichever agent is running.
 
+**Getting the conversation out.** `/export` writes it as markdown — what was
+said, what was run and what it printed — to `~/.opentree/exports`, never into
+the worktree, and says where. `ctrl+y` puts the same document on the clipboard.
+
 The agent's live model, mode and effort sit on the right of the input, next to
 the running context and cost. `ctrl+c` takes you back to the workspace list and
 leaves the chat running: the agent keeps working, its row keeps reporting, and
@@ -247,12 +351,132 @@ is queued rather than refused.
 **Which agents.** OpenCode, GitHub Copilot CLI and Gemini CLI serve ACP
 themselves, so having the binary is the whole setup. Claude Code is reached
 through the `claude-agent-acp` adapter, which opentree installs on request into
-`~/.opentree/tools` rather than your global npm root — press `A` in the
-dashboard, pick Claude Code, and it offers the download (303MB, needs `node`).
+`~/.opentree/tools` rather than your global npm root — open the dashboard's
+Agents tab, pick Claude Code, and it offers the download (340MB, needs `node`).
+
+Those four ship with opentree; the rest of the ecosystem comes from the
+[ACP Registry](https://agentclientprotocol.com/get-started/registry).
+`opentree agents add <id>` installs any agent it lists, and the install is
+first-class everywhere the four are — the picker, chats, fan-outs,
+per-workspace overrides. opentree drives agents over ACP and nothing else, so
+an agent without an ACP server has no way in — but shipping support and one
+registry entry is now the whole path in. See
+[Agents from the ACP Registry](#agents-from-the-acp-registry).
+
+### Autopilot
+
+The dashboard shows everything, but without autopilot you are still the event
+loop: watch the badge, forward the failure, press `p`. Autopilot closes the
+loop per workspace — when a turn ends, the project's check command decides
+whether the work is done:
+
+```toml
+[workspace]
+check = "make test"        # the same thing a contributor runs before pushing
+```
+
+- The check runs in the worktree, streaming into the chat log. A failure goes
+  back to the agent as the next prompt — the tail of the output, where the
+  test runner's summary is — and the loop repeats.
+- A pass publishes: push what origin is missing, then create the PR with a
+  generated title and body, or bring the existing one up to date. Never a
+  duplicate — if the agent already pushed or opened the PR itself, publishing
+  notices and stands down.
+- You get a `pr_ready` notification when the PR exists, through the same
+  surfaces as `blocked`.
+
+Switch it per workspace: `P` in the dashboard, `/autopilot` in the chat, or
+
+```bash
+opentree auto feat/add-dark-mode on    # off; bare reports where the loop stands
+```
+
+The row shows `auto` while the loop owns a workspace, and `checking…` /
+`publishing…` while it works.
+
+Autopilot knows when to stand down. A cancelled or refused turn never triggers
+the check. Your queued message always runs first, and any message from you
+resets the loop. Five autopilot-fed turns without a green check and it halts —
+the row says `auto · halted`, the error log says why, and your next message
+starts it again. `check` is executable code from a tracked file, so it sits
+behind the same trust gate as `setup` and `run`: the first run asks, once,
+showing the exact text.
+
+Without a `check` command autopilot still pushes and keeps the PR current
+after each turn — for projects whose CI is the check.
+
+**Once the PR exists, autopilot watches it.** Every two minutes the chat asks
+GitHub what is new: a failing check gets forwarded with the tail of its
+Actions log, new review comments get forwarded the way `R` sends them — each
+as its own turn, CI before reviews, the moment the agent is free. Nothing is
+sent twice: the watermarks live in `state.json`, keyed on the commit a failure
+was reported for and the fingerprint of the review set, so a new push re-arms
+CI forwarding by itself and a reopened window does not repeat its
+predecessor. `opentree ci <branch>` sends the same CI report by hand,
+autopilot or not.
+
+### Dispatch
+
+The whole pipeline in one command:
+
+```bash
+opentree dispatch 42                    # issue #42 → workspace → agent → checks → PR
+opentree dispatch "fix the login race"  # the prompt is the task
+opentree dispatch 42 --headless         # no attach: wait, print the PR URL, exit
+```
+
+Dispatch creates the workspace (branch `auto-<slug>` in prompt mode), starts
+the agent in its tmux window, switches autopilot on and sends the task. By
+default it attaches so you can watch; `--headless` waits on the chat's socket
+instead and exits with a code a script can branch on:
+
+| Code | Meaning |
+| --- | --- |
+| 0 | the PR was published; its URL is on stdout |
+| 1 | autopilot halted (the check kept failing) or reported an error |
+| 2 | the agent stopped, or the chat became unreachable |
+| 3 | blocked on a permission only a human can answer |
+| 4 | `--timeout` (default 30m) elapsed; the workspace is still working |
+
+Every failure leaves the workspace alive — `opentree attach` picks up exactly
+where it stopped. Headless can ask nothing, so the repository's `setup` and
+`check` commands must be approved ahead of time with `opentree trust`, and a
+tmux server must be running (`tmux new-session -d` in CI).
+
+### Fan-out
+
+Four agents through one protocol makes a comparison no single-agent tool can
+run: the same task, raced.
+
+```bash
+opentree new feat/x --agents claude,opencode,gemini --prompt "add dark mode"
+git log --oneline | opentree new fix/y --agents claude,gemini  # or pipe the task in
+```
+
+One sibling workspace per agent — `feat/x-claude`, `feat/x-opencode`,
+`feat/x-gemini` — all from the same base, each running its own agent, every
+one handed the same prompt (queued until its agent is ready). A name a
+sibling would have taken is stepped past with a numeric suffix rather than
+refused. Without `--prompt` or a pipe the siblings start idle, and `m` in the
+dashboard messages whichever you like.
+
+The dashboard shows the group as one thing: siblings sort together under
+every sort mode, each row wears a `⑂ feat/x` badge, and the cost, context
+and diff numbers already on every row become the scoreboard. `D` opens the
+comparison — every sibling's diff in one scroll, sectioned by agent.
+
+Then pick:
+
+```bash
+opentree promote feat/x-claude   # or W on the row in the dashboard
+```
 
-Those four are the whole list. opentree drives agents over ACP and nothing else,
-so an agent without an ACP server has no way in — if one ships support, it
-becomes a single registry entry and everything above applies to it unchanged.
+The winner stays, every other sibling is deleted — worktree, branch, window —
+and the group dissolves. Dirty losers show their diffs and ask first, the way
+delete does. **The winner keeps its suffixed branch name**: `feat/x-claude`
+does not become `feat/x`, because its worktree, chat and any open PR are all
+keyed on the name it has. Rename it on the PR page if the suffix bothers you,
+or not at all.
 
 ### Notifications
 
@@ -266,6 +490,7 @@ when it starts needing you:
 | `blocked` | the agent stopped to ask for a permission |
 | `done` | a turn finished |
 | `stopped` | the agent died, failed to start, or its setup commands failed |
+| `pr_ready` | autopilot opened or updated a pull request |
 
 Two surfaces. In tmux the window's own bell rings, which tmux renders as an
 inverted window name in the status bar until you select that window — no
@@ -288,13 +513,14 @@ until they have been allowed, which is otherwise a feature with no symptom.
 
 ```toml
 [notify]
-on      = ["blocked", "stopped"]   # add "done"; [] switches everything off
-desktop = true                     # false: tmux bell only
+on      = ["blocked", "stopped", "pr_ready"]   # add "done"; [] switches everything off
+desktop = true                                 # false: tmux bell only
 ```
 
-`blocked` and `stopped` are on by default and `done` is off, because four agents
-finishing turns is a banner every ninety seconds — and a notifier you mute is a
-notifier you deleted.
+`blocked`, `stopped` and `pr_ready` are on by default and `done` is off,
+because four agents finishing turns is a banner every ninety seconds — and a
+notifier you mute is a notifier you deleted. `pr_ready` cannot spam: it fires
+only from autopilot, which is opt-in, and only when a publish moved something.
 
 This section is read from `~/.config/opentree/opentree.toml` only. A repository's
 own `opentree.toml` may configure how the project is built; how you like to be
@@ -311,11 +537,20 @@ opentree new <branch-name> [flags]
 # Examples
 opentree new feat/user-auth           # Create workspace with branch
 opentree new fix/login-bug --base dev # Branch off 'dev' instead of 'main'
+opentree new feat/x --agent claude    # Run claude here, whatever the config says
+opentree new feat/x --agents claude,gemini --prompt "task"  # Fan out — see Fan-out
+opentree new feat/x --no-fetch        # Branch from the local base as it is
 ```
 
+The base is fetched from origin first, and the branch made from `origin/<base>`:
+a `main` last pulled yesterday would otherwise start the workspace a day behind,
+and its PR would carry or conflict with commits already merged. Offline, the
+command says so and branches from the local base; `--no-fetch` skips the fetch
+on purpose. `issue` and `dispatch` do the same.
+
 Creates:
 
-1. Git worktree at `.opentree/<branch-name>/`
+1. Git worktree at `~/.opentree/worktrees/<repo>/<branch-name>/` (see [Where worktrees live](#where-worktrees-live))
 2. New branch (or checks out existing)
 3. tmux window in `opentree-<repo>` session
 4. Launches the configured coding agent in the workspace
@@ -348,6 +583,22 @@ opentree attach <branch-name>
 
 Attaches to the workspace's tmux window. Detach with `Ctrl+b d`.
 
+#### Get Into the Worktree
+
+```bash
+opentree path <branch-name>          # print the worktree's directory
+cd "$(opentree path feat/x)"         # …which is what it is for
+opentree shell <branch-name>         # a shell there, in a tmux window beside the chat
+```
+
+The chat's window is opentree's, holding the conversation. When the agent asks
+for something only a person at a prompt can do — run the tests, check a URL,
+paste back what a command printed — `shell` opens a window of your own in the
+worktree (`<branch>:sh`, reused while it lives) and takes you to it; `/shell`
+in the chat and `t` in the dashboard do the same. `path` prints the directory
+and nothing else, because a branch's directory is not its name: `feat/x` lives
+at `feat-x`, under `~/.opentree/worktrees/<repo>` by default.
+
 #### Show Diff
 
 ```bash
@@ -377,7 +628,33 @@ opentree review <branch-name>
 Fetches the open PR's review comments and sends them to the workspace's agent as
 a prompt, over the chat's control socket. The chat has to be running, but it
 doesn't have to be the window you're looking at — and if the agent is mid-turn
-the command says so rather than reporting a send that went nowhere.
+the prompt is queued and runs when the turn ends, which the row's badge shows.
+
+#### Send CI Failures to the Agent
+
+```bash
+opentree ci <branch-name>
+```
+
+The dashboard's badge says CI is red; this is how the agent learns why: the
+failing checks by name, and the tail of each GitHub Actions log — where the
+test runner's summary is. Same delivery as `review`, over the control socket.
+With autopilot on, this happens by itself.
+
+#### Merge the Base In
+
+```bash
+opentree sync <branch-name>          # fetch origin's main and merge it into the branch
+opentree sync <branch-name> --ask    # …and on conflicts, hand the files to the agent
+```
+
+The dashboard's row says `PR open · conflicts`; this is what to do about it.
+The base is fetched from origin first — offline, the local one is merged and
+the command says so — and merged rather than rebased, because the branch may
+already be pushed and under review. Conflicts are not a failure: they are
+listed, the merge is left in progress in the worktree with its markers, and
+`--ask` (or `y` in the dashboard's dialog) sends the agent a prompt naming the
+files and asking it to finish the merge.
 
 #### Delete Workspace
 
@@ -386,9 +663,23 @@ opentree delete <branch-name>
 
 # Examples
 opentree delete feat/user-auth
+opentree delete --merged          # every workspace whose PR has merged
+```
+
+Removes the worktree, kills its tmux windows, and deletes the branch. If uncommitted changes are detected, a diff is shown and confirmation is required before proceeding. `--merged` does the same for every workspace the dashboard has seen merge — one question each for any that still hold something — which is how a week's worth of `merged · ready to delete` rows is cleared at once.
+
+#### Promote a Fan-out Winner
+
+```bash
+opentree promote <branch-name>
+
+# Example
+opentree promote feat/x-claude   # keep this sibling; delete feat/x-gemini, feat/x-opencode
 ```
 
-Removes the worktree, kills the tmux window, and deletes the branch. If uncommitted changes are detected, a diff is shown and confirmation is required before proceeding.
+Keeps the named sibling, deletes every other member of its fan-out group, and
+dissolves the group. Losers with uncommitted or unpushed work show their diffs
+and ask for confirmation first. The winner keeps its suffixed branch name.
 
 #### Install Shell Completion
 
@@ -404,7 +695,7 @@ Create `opentree.toml` in your repo root or `~/.config/opentree/opentree.toml`.
 
 ```toml
 [worktree]
-base_dir = ".opentree"        # Where to store worktrees (relative to repo root)
+base_dir = ".opentree"        # Where worktrees go — unset: ~/.opentree/worktrees/<repo>; relative: inside the repo
 default_base = "main"         # Default base branch
 
 [agent]
@@ -414,6 +705,7 @@ command = "opencode"          # Agent to run: "opencode", "claude", "copilot" or
 seed  = [".env", ".npmrc"]                  # Untracked files to link into each new worktree
 setup = ["pnpm install --frozen-lockfile"]  # Commands run before the agent starts
 run   = "pnpm dev"                          # Dev server, started on demand, PORT exported
+check = "pnpm test"                         # What autopilot runs after each agent turn
 
 [tmux]
 session_prefix = "opentree"   # Prefix for the tmux session name
@@ -426,6 +718,44 @@ on      = ["blocked", "stopped"]
 desktop = true
 ```
 
+### Where worktrees live
+
+Outside the repository, by default: `~/.opentree/worktrees/<repo>/<branch>`,
+where `<repo>` is the name of the repository's directory. Worktrees used to go
+under `<repo>/.opentree`, and every tool that walks a project found the extra
+checkouts — test runners collected their tests twice, `tsc` compiled them,
+linters and formatters walked them, watchers rebuilt on every save an agent
+made, and a worktree without its own `node_modules` quietly resolved the
+parent's. Git was the only tool told to look away. Out of the working tree,
+none of them can see a worktree at all.
+
+Two clones with the same directory name get separate directories: the first
+claims `<repo>` with a small `.repo` marker naming it, and the second gets
+`<repo>-<hash>`.
+
+To keep worktrees inside the repository — where a plain `find` will meet them —
+set `base_dir` to a relative path, in the repository's own `opentree.toml` or
+globally:
+
+```toml
+[worktree]
+base_dir = ".opentree"   # inside the repository, as before
+```
+
+An absolute path, or one under `~`, is accepted from the global config only: a
+cloned repository does not get to point opentree at the rest of your
+filesystem. Workspaces made before a change of `base_dir` stay where they were
+made — opentree finds them through git — and `opentree doctor` says where the
+worktrees of the current setting go, and whether that is inside the working
+tree.
+
+The state lives outside the repository too, at
+`~/.opentree/state/opentree-<hash>/state.json`. Nothing of opentree's is written
+into the working tree, and nothing in `.git` is touched, so pre-commit hooks
+that stage everything and automations that refuse a dirty checkout never meet
+opentree. A `state.json` an older release left under `<repo>/.opentree` is
+moved out the first time any command runs.
+
 ### Seeding a Worktree
 
 A git worktree carries only what git tracks, so a fresh one has no `.env` and no
@@ -458,7 +788,7 @@ opentree seed detach feat/add-dark-mode .env
 ```
 
 That can also happen by accident: tools that save by renaming over a file
-replace the link with an ordinary one. `opentree setup <branch> --check` reports
+replace the link with an ordinary one. `opentree setup <branch> --dry-run` reports
 which seeded files are still linked and which have quietly detached.
 
 ### Setting Up a Worktree
@@ -505,7 +835,7 @@ tearing down a live conversation:
 
 ```bash
 opentree setup feat/add-dark-mode           # re-seed, then run the commands here
-opentree setup feat/add-dark-mode --check   # report what is seeded and what has run
+opentree setup feat/add-dark-mode --dry-run # report what is seeded and what has run
 ```
 
 Both paths write the same marker, so a worktree prepared from the terminal is one
@@ -583,9 +913,9 @@ To use one of the others instead of OpenCode:
 command = "claude"            # or "copilot", or "gemini"
 ```
 
-Or press `A` in the dashboard to pick from the agents you have installed — it
-writes the same config, and offers to fetch the ACP adapter if the agent needs
-one. From the CLI:
+Or press `tab` in the dashboard for the Agents tab and pick one — it writes
+the same config, and offers to fetch the ACP adapter if the agent needs one.
+From the CLI:
 
 ```bash
 opentree agents list           # what's installed, and which is active
@@ -596,13 +926,56 @@ opentree agents setup claude   # fetch its ACP adapter, if it needs one
 An agent opentree has no ACP spec for is refused up front, when you create a
 workspace, rather than later inside a chat that cannot start.
 
+### Agents from the ACP Registry
+
+The four built-in agents are a curated list, not a boundary. The
+[ACP Registry](https://agentclientprotocol.com/get-started/registry) — the
+same index Zed and JetBrains install from — lists every agent that ships an
+ACP server, and opentree installs from it:
+
+```bash
+opentree agents search             # what the registry has (add a term to filter)
+opentree agents add devin          # install one, into ~/.opentree/registry
+opentree agents use devin          # it is a normal agent from here on
+opentree agents update             # re-resolve every install against a fresh index
+opentree agents remove devin       # delete the install
+```
+
+Installing executes code, so nothing is fetched before you have seen exactly
+what will happen: an npm-distributed agent shows the full install command —
+pinned version, opentree's own prefix, npm's install scripts disabled, the
+same posture as the Claude Code adapter — and a binary-distributed one shows
+the archive URL and the sha256 it will be held to. Each install lands in its
+own directory under `~/.opentree/registry`, wears a `registry` tag in
+`agents list` and the version the index pinned; `agents update` builds the
+new version beside the old and swaps it in only when complete, so a failed
+update leaves the old agent working.
+
+The dashboard's Agents tab is the same feature without leaving the
+terminal you are already in: `a` fetches the index and lists it, `enter` on
+an entry shows the same consent card `agents add` prints and installs on
+`y`, `u` and `U` are `agents update`, `x` is `agents remove`. An agent
+installed there is a row the moment the install finishes — no restart.
+
+Everything else is indistinguishable from the built-in four:
+`--agents claude,devin,goose` races them, a workspace remembers which one it
+runs, and `opentree doctor` reports them.
+Two honest gaps: a registry entry does not say where its agent keeps skills,
+so the Skills tab leaves registry agents out rather than guessing; and the
+few agents distributed only via PyPI's `uvx` are listed by `agents search`
+but not installable yet.
+
+Ordinary commands never touch the network — the loader reads installed
+agents from disk, and only `agents search`, `add` and `update` fetch the
+index. Offline, the last index this machine saw answers, with its age noted.
+
 ## How It Works
 
-1. **Worktrees**: Git worktrees allow multiple checkouts of the same repo in different directories. Each workspace lives in `.opentree/<branch-name>/`.
+1. **Worktrees**: Git worktrees allow multiple checkouts of the same repo in different directories. Each workspace lives in `~/.opentree/worktrees/<repo>/<branch-name>/` — outside the working tree, so the project's own tools never see it — unless `base_dir` says otherwise.
 
 2. **tmux Orchestration**: A single tmux session (`opentree-<repo>`) manages all workspaces. Each workspace = one tmux window. Attach to work, detach to switch.
 
-3. **State Persistence**: Workspace metadata (branch, created time, agent, issue number) stored in `.opentree/state.json`.
+3. **State Persistence**: Workspace metadata (branch, created time, agent, issue number) stored in `~/.opentree/state/<repo-key>/state.json`, outside the repository.
 
 4. **Agent Integration**: When creating a workspace, opentree launches your configured agent inside the tmux window, ready to code. With no agent configured, it uses the first supported agent found on your PATH.
 
@@ -627,6 +1000,11 @@ opentree new fix/header-overflow
 # (work on bugfix...)
 # (detach)
 
+# Not sure which agent will do a refactor best? Race them
+opentree new refactor/auth --agents claude,opencode,gemini --prompt "extract the auth middleware"
+# (press D in the dashboard to compare, then promote the winner)
+opentree promote refactor/auth-claude
+
 # Review changes for first feature
 opentree diff feat/add-dark-mode
 
@@ -639,6 +1017,30 @@ opentree delete feat/add-dark-mode
 
 ## Troubleshooting
 
+### Start here: `opentree doctor`
+
+```bash
+opentree doctor
+```
+
+Prints what opentree can see — its own version, the versions of git, tmux, gh
+and node, which config file it resolved and what it says, whether this
+repository's setup commands are approved, where state and sockets live, and
+what each workspace's chat is doing. Everything it does is a read, so it is
+safe to run and safe to paste into an issue.
+
+If a problem needs reproducing rather than describing, point opentree at a log
+first:
+
+```bash
+OPENTREE_LOG=/tmp/opentree.log opentree
+```
+
+An environment variable rather than a flag, because the interesting failures
+happen inside `opentree chat`, which a tmux window starts rather than you — and
+the variable is inherited by every process opentree launches. Off by default.
+The file holds branch names, paths and session ids, and is written `0600`.
+
 ### "Error: not a git repository"
 
 opentree must be run from inside a git repository. Navigate to your project root first.
@@ -661,8 +1063,8 @@ Install OpenCode from [github.com/anomalyco/opencode](https://github.com/anomaly
 
 ### The chat says the agent needs an adapter
 
-Claude Code speaks ACP through `claude-agent-acp`. Press `A` in the dashboard,
-select Claude Code, and accept the download — it installs to `~/.opentree/tools`
+Claude Code speaks ACP through `claude-agent-acp`. Open the dashboard's Agents
+tab, select Claude Code, and accept the download — it installs to `~/.opentree/tools`
 and needs `node` on your PATH. If you already have the package installed
 globally, opentree uses that instead of fetching a second copy.
 
@@ -693,7 +1095,7 @@ gh auth login
 
 ### Workspaces not appearing in TUI
 
-State file might be corrupted. Check `.opentree/state.json` or delete and recreate workspaces.
+State file might be corrupted. `opentree doctor` prints where it is (under `~/.opentree/state`); delete it and recreate workspaces.
 
 ## Contributing
 
@@ -711,12 +1113,33 @@ go build -o opentree ./cmd/opentree
 
 ### Architecture
 
-See [PLAN.md](PLAN.md) for detailed architecture documentation.
+`cmd/opentree` is the CLI surface; `pkg/` is where the work happens.
+
+| package | what it owns |
+| --- | --- |
+| `tui` | the dashboard: the workspace list, the Agents, Skills, Plugins and Servers tabs |
+| `chat` | the conversation view, and the control socket the dashboard reaches it through |
+| `acp` | the Agent Client Protocol client — the agent subprocess and its stdio |
+| `workspace` | a workspace's lifecycle, over the four below it |
+| `worktree` | git worktrees and branches |
+| `tmux` | sessions and windows |
+| `state` | `state.json`, shared between the dashboard and every chat |
+| `github` | `gh`, for PRs, issues and CI status |
+| `bootstrap` | seeding a worktree, running its setup, and the trust gate over those commands |
+| `skills` | propagating agent skills into worktrees |
+| `plugins` | the Agent Plugins store: install, validate, list, remove |
+| `registry` | the ACP Registry client: the index, its cache, and installed agents |
+| `config` | `opentree.toml` and the agent registry |
+| `notify`, `diag`, `ui`, `fsutil`, `gitutil` | the small shared pieces |
 
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.
 
+## Trademarks
+
+opentree draws each agent it drives — opencode, Claude Code, GitHub Copilot and Gemini CLI — under that agent's own wordmark and brand colour, so you can see at a glance which one you are talking to. Those marks belong to their respective owners. opentree is an independent project and is not affiliated with, sponsored by or endorsed by any of them. See [NOTICE](NOTICE).
+
 ## Acknowledgments
 
 - Inspired by [Conductor.build](https://conductor.build) by Sahil Lavingia

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axelgar/opentree",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Git worktree manager CLI for orchestrating parallel AI coding sessions",
   "repository": {
     "type": "git",
@@ -12,13 +12,15 @@
     "opentree": "bin/opentree"
   },
   "files": [
-    "bin/opentree"
+    "bin/opentree",
+    "LICENSE",
+    "NOTICE"
   ],
   "optionalDependencies": {
-    "@axelgar/opentree-linux-x64": "1.0.2",
-    "@axelgar/opentree-linux-arm64": "1.0.2",
-    "@axelgar/opentree-darwin-x64": "1.0.2",
-    "@axelgar/opentree-darwin-arm64": "1.0.2"
+    "@axelgar/opentree-linux-x64": "1.2.0",
+    "@axelgar/opentree-linux-arm64": "1.2.0",
+    "@axelgar/opentree-darwin-x64": "1.2.0",
+    "@axelgar/opentree-darwin-arm64": "1.2.0"
   },
   "engines": {
     "node": ">=18"