# hydra-acp ``` ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⣾⢃⣤⡶⠂ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⣶⣿⣿⣿⣿⣶⣤⡀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⠄⠀⠀⠀⠀⠀⢀⣠⣶⣿⣥⣾⣿⣿⣿⣿⣿⣍⠀⠀⠀⠀⠀⠀⠀⠀⠀⣄⡀ ⠀⠀⠀⠀⠀⠀⠀⠀⣠⣾⣯⣴⡾⠋⠀⠀⠀⠸⡿⠟⠋⣹⣿⡿⢿⣿⣿⣿⣿⢧⠀⠀⠀⠀⠀⠙⢷⣦⣼⣿⣄ ⠀⠀⠀⠀⠀⠀⣰⡾⠟⣿⣿⣿⣿⣿⣶⠄⠀⠀⢀⣠⢾⡿⠉⠀⢨⣿⣿⣿⣿⡄⠀⠀⠀⠰⣶⣿⣿⣿⣿⣿⠿⣷⣄ ⠀⠀⠀⠀⣶⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣄⠀⠈⠃⠀⠀⠀⠀⣼⣿⣿⣿⡏⠁⠀⠀⣴⣾⣿⣿⣿⣿⣿⣿⣷⣾⣿⣷⣦ ⠀⠀⠀⠀⠙⠋⠀⣠⣿⠿⠛⠉⢻⣿⣿⣿⣧⠀⠀⠀⠀⠀⢀⣼⣿⣿⣿⡿⠁⠀⠀⢠⣾⣿⣿⣿⠟⠉⠻⢿⣷⡀⠘⠹⠋ ⠀⠀⠀⠀⠠⢴⠋⠻⠇⠀⠀⠀⠀⣿⣿⣿⣿⠃⠀⠀⠀⢀⣾⣿⣿⣿⣿⠃⠀⠀⠀⢻⣿⣿⣿⡏⠀⠀⠀⠀⠿⠟⠳⡤ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢿⣿⣿⣿⡆⠀⠀⠀⣼⣿⣿⣿⣿⡇⠀⠀⠀⢀⣿⣿⣿⣿⠁⠀⠀⠀⠀⠀⠀⠀⠁ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿⣄⠀⢰⣿⣿⣿⣿⣿⡇⠀⠀⣠⣿⣿⣿⣿⡟ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢿⣿⣿⣿⣿⣷⣼⣿⣿⣿⣿⣿⣷⣴⣾⣿⣿⣿⣿⡟ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡋⠀⠀⠀⠀⠀⠀⠀⢀⣴⣿⠃ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣄⠀⠀⠀⠀⠐⢻⣿⠿ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣆⠀⠀⠀⠀⠘⣿⡄ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣟⣁⣀⠀⠀⣿⣿⡄ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣿⣿⣿⡏⠙⠻⠿⣿⣿⣿⣿⢿⣿⣿⣿⡿⣿⣿⣿⣿⣿⣿⣧⣤⣾⣿⣿⠃ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣾⣿⣿⡿⠁⠀⠀⢀⣿⣿⣿⠃⠸⣿⣿⣿⠃⠈⢻⣿⣿⡿⢿⣿⣿⡿⠟⠃ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⣶⣾⣿⣿⡿⠀⠀⢠⢶⣾⣿⡿⠃⣠⣴⣿⣿⣿⠀⢠⣶⣿⣿⣷ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⠉⠛⠙⠋⠉⠁⠀⠀⠀⠀⠀⠁⠀⠀⠋⠙⠉⠟⠉⠀⠈⠈⠁⠉ ``` > **Status: experimental.** One daemon owns your coding agents, so a session isn't tied to the window that started it. Built on the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/). ![Starting a session in the hydra-acp TUI, then switching between two live sessions from the picker](assets/demo.svg) ## What it is `hydra-acp` is a **session manager, multiplexer, and TUI** for AI coding agents. Many clients — a terminal TUI, your editor, a browser, Slack — attach to the same live session at once and see it update in real time. Start a session at your desk, follow it from your phone, hand it off to a teammate. The agent doing the actual work is one you already know: Claude, Codex, opencode, pi, or anything else in the ACP registry. Hydra defaults to `opencode` so there's something to run before you've chosen, and [pointing it at whatever you have a license for](#choosing-an-agent) is a one-liner. ```bash npm install -g @hydra-acp/cli # Node 20+ hydra-acp # launch the TUI and start a session ``` That puts `hydra-acp` (and `hydra`) on your PATH, and there is no setup step after it. `~/.hydra-acp/config.json` and the bearer token are written on first use, and the daemon starts itself the first time anything needs it. If you'd rather be explicit, `hydra-acp daemon start` brings it up ahead of time and `hydra-acp init` writes the config early — the latter mostly earns its keep as `init --rotate-token`. The TUI is the front door: it picks an agent, drives the conversation, lists your sessions, and lets you attach to one that's already running. From there you can wire up your editor, add a browser or Slack bridge, or pipe data through it on the command line. ### What it gives you - **A session manager.** Every session is tracked, named, listable (`hydra-acp session`), exportable, and resurrectable. Close your terminal and the session keeps running in the daemon; reattach later from anywhere. - **A multiplexer.** Many clients share one live session. Events broadcast to all attached clients; prompts serialize through a per-session queue; permission requests race (first response wins). Editor, TUI, browser, and Slack all watch the same agent at once. - **A TUI.** A full terminal UI for driving sessions interactively — picking agents, prompting, approving tool calls, scrolling transcripts, and switching between live sessions. - **Long sessions that stay coherent.** History [compacts](#compaction-and-recall) as it approaches the context window, and the agent keeps a recall tool to search back into what was compacted away. `/hydra uncompact` reverses the last one, and `/hydra fork` branches a conversation so you can chase a tangent without losing the thread. - **Extensions.** Optional companion processes — Slack bridge, web UI, desktop notifier, auto-approver, cross-machine sync — that the daemon spawns and manages for you. See [Extensions](#extensions) below. ## Choosing an agent Hydra has no model of its own. Every session is a real ACP agent running as a child process, and hydra is the thing that owns it, keeps it alive, and lets more than one client talk to it. So the first real decision is which agent sits underneath. Out of the box that's `opencode`, because it's the least setup to get something working. It's a reasonable place to start, not a recommendation. Most people point hydra at whatever they already pay for and never think about it again. Hydra spawns the same agent you'd run yourself, so it inherits whatever you already set up. If opencode, pi, or Claude work from your shell today, their existing login and config carry over as-is and there's nothing extra to do. For an agent you've never run before, run its own CLI once and complete its login there. `hydra-acp agent auth ` tries to drive that flow from inside hydra, but registry coverage of auth methods is patchy and it's less exercised than the rest of the surface, so treat it as a shortcut rather than the supported path. ```sh hydra-acp agent list # what exists, and what you already have installed ``` Nothing needs installing ahead of time. Agents are downloaded on first use into `~/.hydra-acp/agents/`. Short names work: `claude`, `pi`, and `codex` all resolve to their full registry ids (see [Registry id resolution](#registry-id-resolution)). How you switch depends on how permanent you want it: | Scope | How | |---|---| | Your default, everywhere | `hydra-acp agent set claude`, then `hydra-acp daemon restart` | | Default model for an agent | `hydra-acp agent set opencode openai/gpt-5-codex` | | A single session | `hydra-acp --agent codex` (or `HYDRA_ACP_AGENT=codex`) | | Mid-conversation, keeping the transcript | type `/hydra agent codex` in any composer | | One editor, pinned | point the editor at `hydra-acp launch claude` | Only the first needs the restart: `agent set` writes `config.defaultAgent` and the daemon reads that at startup. The others take effect immediately. The mid-conversation swap is worth knowing about if you hold licenses for several. `/hydra agent ` spawns the new agent, feeds it the conversation so far, and carries on in the same session, so you can hand an in-progress problem to a different model without starting over. ## Running it ### From the terminal ```bash hydra-acp # TTY: picker if you have sessions, else a new one hydra-acp tui # explicit form hydra-acp session # list sessions hydra-acp --reattach # reattach to this terminal's last session hydra-acp --session hydra_session_abc123 # attach to a specific session hydra-acp --workspace # new sessions get their own isolated checkout ``` `--workspace` is a mode, not a name: every session you *create* in that TUI runs in its own workspace, so two sessions in one repo can't edit each other's files. It applies to creation only — attaching to an existing session never changes that session's isolation. If the directory can't be isolated (not a repository, no commits yet), the session still starts in the source tree and says why. In the TUI, `^G` opens the key-binding help — that's the one binding worth memorizing. The others you'll reach for early: `^P` switches sessions, `^R` searches your prompt history and then scrollback, `^T` toggles the agent's reasoning, `^D` on an empty prompt detaches. Detaching leaves the session running in the daemon; `hydra-acp session` will still list it and you can attach again from anywhere. `^S` on an empty prompt opens the sidebar, which runs alongside the conversation and tracks what the agent is doing: running tools, the current todo list, files edited so far, git status, context usage, and your other sessions. Click a gadget's title to fold it. (With a draft in the composer, `^S` amends the in-flight turn instead.) ### Isolated workspaces A workspace is a git worktree on its own `hydra/