feat: first-class herdr multiplexer support — native splits + classic attach (WIP)

[salemsayed]

Status: WIP / RFC. This is feature-complete enough to use daily but still under active on-device testing. Opening as a draft to get your eyes on the direction and the herdr abstraction before I polish. Happy to split it into smaller topical PRs if you'd prefer to land it in stages — see the commit ladder below, each commit is independently green.

What this adds

First-class support for herdr — a terminal multiplexer built for orchestrating coding agents (workspaces → tabs → panes, each pane running an agent with an idle / working / blocked / done status). This wires herdr into chuchu the same way iTerm2 integrates tmux with tmux -CC: chuchu can either take over herdr's UI and render it natively, or attach to herdr's own TUI over a plain SSH session.

herdr is driven entirely through its JSON CLI (herdr api snapshot, herdr terminal session control|observe <pane>, focus/create/close verbs), so there's no wrapper service and no herdr-specific network protocol — it's the same MultiplexerType abstraction the tmux/zmx support already uses, extended with a runtime control plane.

Two modes (per-host toggle)

Native splits (default-on, hidden setting). chuchu hides herdr's TUI entirely and becomes the multiplexer chrome:

• herdr's tabs become chuchu's tab strip; a switcher home lists every workspace with per-status agent counts, each expandable in place (caret) to jump straight to a specific tab or pane.
• Each pane is streamed via herdr terminal session control|observe <pane> --cols N --rows M, which emits an ndjson terminal.frame stream (server re-renders ANSI at the exact geometry chuchu asks for). Each pane is fed into its own native ghostty VT and laid out in a native split that mirrors herdr's own layout geometry (layouts[] from the snapshot, in cell units).
• Input/resize/scroll are routed to the focused pane over the terminal.input / terminal.resize / terminal.scroll uplink. Tap a pane to focus; tap the focused pane to raise the keyboard.
• A "needs you" section surfaces agents that are done-and-unseen. This is grounded in herdr's attention semantics: done = finished + unseen (wants your attention), idle = already seen. Focusing a pane flips done → idle server-side, so the triage list stays honest.
• Create/destroy from the UI. Because native mode routes keystrokes to the focused pane's PTY, herdr's own keybindings never reach the server — so pane/tab/workspace lifecycle is surfaced explicitly and dispatched via herdr's CLI verbs (pane split --direction right|down, pane close, tab create/close, workspace create/close). A compact + menu on the tab strip (split right / split down / close pane / new tab) acts on the focused pane/tab; long-press a tab to close it; the switcher home has + new and a ✕ per workspace. Destructive closes go through a confirmation since they terminate the running agent.
• Transport is one shared SSH connection carrying N exec channels (added to the Zig/libssh2 bridge), so switching panes/workspaces doesn't spin up a new connection each time.

Classic attach (toggle off). Exactly today's behavior — a normal SSH session attached to herdr's own TUI, with chuchu's terminal rendering it. No native takeover, no extra streams. This is the fallback for anything the native path doesn't cover yet (e.g. inline images, which aren't in the frame stream).

Screenshots

Switcher home + "needs you" triage (native mode)

Native splits — two panes rendered side-by-side, focused pane has the accent border, layout mirrors herdr's own geometry:

How it's built (commit ladder)

Each commit is independently green (./gradlew testDebugUnitTest + compileDebugKotlin); the native path stays inert until the "render herdr tabs as native splits" commit flips it on:

1. parse herdr layout geometry in snapshot — kotlinx.serialization models + fixtures + parser tests
2. add herdr terminal frame codec — ndjson framing, seq/restart policy, terminal.input/resize/scroll encoders (pure + tested)
3. stream herdr panes into native terminals — HerdrPaneHost (one VT + one channel per pane) + engine stream reconciliation
4. route input to the focused herdr pane — focus state + sink branching
5. render herdr tabs as native splits — HerdrSplitLayout + the flip
6. add per-host herdr native splits toggle — HostProfile.herdrNativeMode + Room v11→v12 AutoMigration + AddServer switch
7. multi-exec-channel SSH bridge, switcher home, needs-you triage, workspace create, and a series of on-device fixes (pane geometry sync, scroll direction, tap-to-focus, connection labels, crash-hardening)

Alignment with the repo's conventions

• Multiplexer-agnostic — reuses the existing MultiplexerType / MultiplexerRegistry abstraction; no wrapper services, no herdr daemon.
• kotlinx.serialization throughout (no org.json).
• Thin ViewModels — control-plane logic lives in the engine/repository; the VM combines flows and forwards intents.
• Hidden, default-on setting — the native toggle only appears once herdr is selected as the multiplexer.
• Battery-conscious — pane streams are opened lazily (only for the visible tab's panes), disposed on background, and rebuilt on foreground; polling cadence is tuned and cancellable.
• Tests — 8 new unit-test suites (framing, seq policy, encoders, snapshot/layout parsing, stream policy, shared-connection, notifier).

Testing status

• ✅ Native splits mirror the desktop layout; tap-to-focus + typing reach the right pane; rotation re-streams at the new geometry; two-finger scroll drives server scrollback.
• ✅ Switcher home, "needs you" triage (verified against a live agent going done), and workspace-create verified on-device.
• ✅ Pane lifecycle verified on-device: + pane → splits (new pane, focus follows), ✕ pane → confirm → pane closes and the layout reflows, with the neighbouring pane's session surviving.
• ✅ Multi-channel transport verified (stable connection count, no per-switch connection spikes).
• ✅ Classic attach + non-herdr hosts (tmux/zmx/plain) regression-checked.
• 🚧 Still shaking out: takeover-vs-observe edge cases when the desktop TUI holds control, VT mode replay (bracketed paste / DECCKM arrows), and pane renaming/reordering. Mouse forwarding to herdr's own UI is deliberately out of this PR — the explicit lifecycle controls above cover the create/destroy gap that native takeover would otherwise leave.

Tested on an Oppo Pad Mini against herdr 0.7.4 (protocol 16) over SSH.

How to try it

1. Add/edit a host, pick herdr as the multiplexer. "Native splits (beta)" is on by default; toggle it off for classic attach.
2. Requires a herdr session already running on the host (native mode does not launch one for you yet — the classic toggle is the fallback).
3. Connect → you land on the switcher home; tap a workspace to open its tabs as native splits.

---

Would love feedback on the herdr abstraction and whether you'd rather see this as one PR or staged. 🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9a58336b-86d1-4be2-af65-43568df18971

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[jossephus]

Hey @salemsayed, keep making updates on the PR. Although i doubt we will land this to main, i can see how useful it can be.

a while ago, i was working on plugins to chuchu, i got distracted by other stuff but the ultimate goal was to enable customizations like this. Let me see if I can push on the plugin implementation this week, and i will be using this PR as the demo.

also loving herdr so far

[salemsayed]

Hey @salemsayed, keep making updates on the PR. Although i doubt we will land this to main, i can see how useful it can be.

a while ago, i was working on plugins to chuchu, i got distracted by other stuff but the ultimate goal was to enable customizations like this. Let me see if I can push on the plugin implementation this week, and i will be using this PR as the demo.

also loving herdr so far

Oh a plugin is exactly the correct way for this, I also agree that it it's too far to land on main but I've been using it for a couple of days and I think it's really beneficial for working with herdr and especially on a small phone as the herdr tui is hard to manage on a phone when you've adjusted it on your big screen computer.