[idea] Ability to have the same session open on multiple terminal windows

[josevelaz]

idea / problem

In tmux, I am able to open two terminal windows, and attach the same session and each terminal window acts independent as long as i am in different tmux windows. Herdr mirrors the session regarless of the terminal window.

requested change

I would like to ability to have the same session open in seperate terminal windows.

why you want this

Adding this would allow me to monitor two, or even 3 workspaces simultaneously side by side without having to switch between them.

[renatojf]

Same need here: two Alacritty windows attached to the default session, want window A on workspace 2 and window B on workspace 1 at the same time. Today both mirror.

Dug into why. Selection is shared session state, so there is one selection for every attached client:

• AppState.active: Option<usize> (active workspace) — src/app/state.rs:1274
• Workspace.active_tab and Workspace::focused_pane_id()
• render_virtual() takes &AppState and draws that one active view, so every client gets the same frame modulo terminal size — src/server/render_stream.rs:271

So mirroring is structural, not a config gap. Independent windows need selection to become per-client.

The interesting part: AGENTS.md already classifies selection as client state, not shared runtime:

Sidebar layout, token placement, colors, selection, modals, mouse/viewport state: TUI/client.

and the project is "migrating toward a server-owned runtime protocol with the TUI as one client." So this feature is the endpoint of a migration already in progress, not a new concept. Workspaces/tabs/panes stay shared session organization. Only the view into them (which ws/tab/pane each client looks at) moves to the client layer, where the guardrail says it belongs.

Sketch of the seam:

• A per-client ClientView { active_workspace, active_tab_by_workspace, focused_pane_by_tab }, living next to the existing per-client state in ClientConnection (src/server/clients.rs).
• render(&AppState, &ClientView) so "what is active" comes from the requesting client; pane contents and session structure stay shared. Render stays pure.
• Navigation/input mutates the issuing client's ClientView instead of the global selection.

Phaseable: Phase 1 introduces ClientView with a single default view, byte-identical for one client (pure refactor, testable without PTYs). Phase 2 routes input per client and turns on independence. Phase 3 makes focus-derived behavior per-client (cursor reveal, host focus reporting, active-tab notification suppression, hyperlink visibility).

Open questions that need a maintainer call before any code:

1. Scope of v1: per-client workspace only (smallest seam, just AppState.active), or full per-client tab and pane focus too?
2. auto_switch on agent state change: move every client, only the owning client, or none?
3. Is ClientView ephemeral per connection, or restored on reattach? Interaction with resume_agents_on_restore.

Happy to build Phase 1 as a no-behavior-change PR if the seam looks right to you. Mainly want your read on direction and the v1 scope before writing it.

[Castrozan]

I have this working on my fork: the active workspace becomes per-client via a ClientView context swap, so two windows attached to the same session can sit on different workspaces at once, with no shared mirror. @renatojf's read is right, the blocker is that the active workspace is shared session state; this moves it into the client. diff at Castrozan#5

what you guys think?

[iamnolanhu]

Tested this fork (commit 65d6079, herdr 0.7.3) with two clients of
different sizes and orientations attached to one server.

The core behavior works. Both clients held different workspaces at the
same time, each sidebar highlighting its own selection, and the divergence
survived swapping assignments between clients, typing in a third workspace,
and extended mixed use. Stock herdr mirrors; this doesn't.

Findings beyond the happy path:

1. Views are per-client, sizing is not. All workspaces share one global
grid (the larger client's size), so the smaller client renders every
workspace clipped — columns cut off on one side, dead space at the bottom.
No stuck sizes or corruption after a client detached — just the fixed
shared grid. This is the main remaining limitation for the multi-monitor
use case.

2. done→idle "seen" is global. An agent ran to done in a workspace
neither client was viewing; the moment ONE client focused it,
agent_status flipped done → idle server-side — the second client never
saw the done state. Arguably right for one human on two monitors, but the
done-marker is consumed by whichever client looks first; worth documenting
either way. (Side note: shell panes always report agent_status: unknown,
so only a real detected agent exercises this.)

3. Focus is a single global value that tracks the last-interacted
client. focused_workspace_id/focused_pane_id re-point to whichever
client clicked or typed most recently, and herdr workspace focus mutates
the last-interacted client's view (the other client's view is untouched).
The API exposes no per-client state at all — no client list, no per-client
view or size. A plugin can't ask "what is client X looking at," and focus
queries race with whichever client last touched input. If per-client views
land, exposing per-client view state through the API (and defining which
client CLI focus commands act on) seems like the natural companion.

4. Concurrent interaction held up. A modal open in one client while the
other switched workspaces, and a selection drag in one client while input
arrived for another pane: all processed cleanly, views held, no corruption
observed.

5. Reattach does not restore a client's view. prefix+q detached
cleanly, the server and the other client were unaffected, and the
reattached client landed on the default workspace — neither its own last
view nor the surviving client's. Per-client view state is ephemeral. Fine
as a first version; worth documenting.

6. Heavy output didn't wedge anything. A several-hundred-thousand-line
flood into a pane one client was watching rendered fine, the socket API
stayed responsive throughout, and the other client's workspace kept
updating.

7. One unconfirmed client exit. While one client was viewing a
workspace, that workspace was closed via the CLI (driven by the other
client's interaction context); the viewing client's process exited without
writing the graceful-shutdown log entry that a normal detach writes. A
repeat attempt on the other client survived the same operation (it fell
back to a remaining workspace), so this is one unexplained death, not a
confirmed repro — flagging it in case the "viewed workspace closed under a
client" path has a known race.

Overall: the per-client view swap itself looks solid. The real gaps are
per-client sizing (1) and API visibility/semantics (3); (2) and (5) mostly
need a documented decision.

[taxilian]

I would also love to see this. in fact, until this is a thing I would never waste time (forgive me for putting it that way) learning herdr because while tmux isn't nearly as ideal for this, and herdr is clearly superior in a lot of ways, the ability to connect multiple clients to different parts of the same session (with different non-mirrored views) is an absolute requirement for my workflows. it's more common that I need that than that I don't.

I'd be happy to assist with development, but don't want to waste time if it's not something the core devs are willing to accept; I'd want some guidance on how they'd want to see it done as well.

[Qu4tro]

Disclosure: this comment was written by Fable, an AI model. The human posting it asked for an independent review of the working fork discussed above and is sharing the results here hoping they help. Two fresh reviewer agents examined the branch independently — one Fable agent at xhigh reasoning effort, one sol 5.6 at xhigh — and I (Fable) verified and synthesized their reports against the code. Everything below refers to @Castrozan's feat/per-client-active-workspace branch (Castrozan#5) at commit 65d6079, diffed against upstream 4617456; line numbers are at that commit.

---

First, what both reviewers cleared: the swap primitive itself. snapshot_client_view/restore_client_view are a clean mechanical save/restore, the ordering inside focus_client_view (reconcile → store outgoing owner → restore/adopt incoming) is correct for the fields it covers, every input/render call site pairs the swap with the matching client id, and disconnect bookkeeping clears client_view_owner without leaking. That matches the earlier hands-on testing in this thread.

Both reviewers also independently found the same two P1 bugs, plus two P2s from sol 5.6. These are new — none overlap with the limitations already reported above.

1. P1 — deferred request_* actions execute against whichever client's view is loaded (found by both)

The one-tick-deferred flags (request_new_workspace, request_new_tab, request_submit_worktree_create, etc. — src/app/state.rs:1344-1368) live on the shared AppState and are not part of ClientView, so they survive view swaps. The server drains all clients' pending events in one batch (drain_server_events, src/server/headless.rs:1466-1472), and each client's input first swaps in its own view (focus_client_view_for_input, src/server/headless.rs:2513).

Failure sequence with clients A and B attached:

1. A clicks "+ new workspace" → request_new_workspace = true is set while A's view is loaded.
2. B's already-queued keystroke is drained in the same batch → B's view is swapped in.
3. handle_deferred_requests_headless (src/server/headless.rs:622-634) runs with B's view loaded. create_workspace_with_launch_env (src/app/creation.rs:220-222) calls switch_workspace + mode = Terminal on the loaded state — B is force-switched into the new workspace (even out of a modal), while A, who clicked, sees nothing.

Silent-data-loss variant: A submits the worktree-create dialog; the handler runs against B's view where worktree_create is None, so submit_worktree_create_via_api (src/app/worktrees.rs:567-571) silently returns — the flag is already cleared, so A's request is dropped with no error and no retry.

Fix direction: carry the originating client with each deferred request. A minimal version: immediately after each client's input batch, harvest any set flags into a (client_id, request) queue (the owner is still known at that point), then execute each with that client's view focused. The open edge is requests raised outside client input (socket API, timers), which need a well-defined owner — which is really the per-client-seam question this thread already raises.

2. P1 — reconciliation misses index-bearing state: stale menus can close the wrong workspace, or panic the server (found by both)

reconcile_client_views_with_workspaces (src/server/headless.rs:1250-1287) re-points only the id-based fields (active_workspace_id/selected_workspace_id). But saved views also carry raw indices restored verbatim: context_menu (ContextMenuKind::Workspace/Tab { ws_idx, .. }), workspace_press, tab_press, drag (WorkspaceReorder/TabReorder), plus mode-carrying dialogs like ConfirmClose.

Failure sequence: A right-clicks workspace index 2 and leaves the context menu open (it can stay open indefinitely — that's normal). B closes a workspace, shifting indices. A then clicks "Close": the restored menu still says ws_idx: 2, and public_workspace_id (src/app/ids.rs:15-16) does unchecked self.state.workspaces[ws_idx] — so A closes the wrong workspace, or, if the list shrank enough, the server panics and takes down every attached client.

To be fair: the unchecked indexing and the fact that tree mutations don't clear menu/press/drag state both predate this branch. But under the mirrored model no client's view could stay diverged long enough to hit them; per-client views are exactly what makes this realistic.

Fix direction: no tradeoff-free complete fix at branch scope. Pragmatic combination: (a) cancel transient UI state (context menu, drag, press, confirm dialogs) in saved views whenever the workspace tree changes — mildly annoying (another client's action can dismiss your open menu) but strictly safer; plus (b) make public_workspace_id and friends checked so the worst case degrades to a no-op instead of a crash. The clean endgame is carrying stable ids instead of indices in those payloads, but that's a broader upstream refactor than this PR should have to carry.

3. P2 — per-client transients restored, but their expiry deadlines stay global (sol 5.6)

copy_feedback and the selection-highlight/autoscroll state are saved per client, but their deadlines live on the global App. If a deadline fires while that client's view is swapped out, the scheduled task clears the deadline against someone else's loaded state; when the client's view is restored, the feedback comes back with no deadline and sticks indefinitely. Fix: expire stale transients on restore, or move the deadlines into ClientView — mechanical either way.

4. P2 — mouse-capture mode computed from one view, broadcast to all clients (sol 5.6)

With ui.mouse_capture = false, the desired capture state depends on each client's own active workspace/mode and its focused terminal's mouse-reporting state. stream_host_mouse_capture_mode computes a single value from whichever view is loaded and broadcasts it, so a client viewing a different workspace can receive the wrong capture mode and stop getting mouse events it needs. Fix: make the computation a function of a given view and send per client.

---

The through-line

All four bugs have one root cause: the branch makes view state per-client, but everything else in the server — deferred commands, timers, broadcast decisions, socket-API mutations — still assumes a single loaded state, and lands on whichever view happens to be swapped in. The swap approach is a great existence proof and delivers the feature cheaply, but each global path needs patching individually, and these four are just the ones two review passes found. That reads as support for the explicit per-client seam (ClientView as a real architectural boundary, per the analysis earlier in this thread) rather than the scratch-slot swap as the mainline design — the fork demonstrates the feature is worth it; the seam is what makes it safe.

From the human posting this: I'm just hoping this helps move the idea along.

[itboat]

Heavy tmux user here. Two things I do constantly that herdr can't cover today.

Multiple windows of the same session on one machine. I usually keep four or five terminal windows open side by side, each on a different window of the same session, because I need to watch several agents at once and steer them in real time. When an agent goes off track, I want to catch it in the moment, not read about it afterwards. Splits inside a single window aren't a substitute — with five agents each pane gets too small to actually read, and I want them as separate OS windows I can place and size independently.

The same session from different machines at the same time. Laptop and phone over mosh, each looking at a different window. tmux grouped sessions give me both of these today.

I genuinely want to move to herdr — agents in panes with real status tracking is exactly the model I need, and I've already set it up as a second layer next to tmux. But the mirrored view is what blocks a full migration: if every attached client renders the same frame, five terminal windows just show me the same thing five times, which defeats the purpose.

+1 on this, and please consider implementing it. Happy to test on a real multi-agent workload, including across two very differently sized clients.

[josevelaz]

I have created a fork which seems to be working well from my quick testing.

https://github.com/josevelaz/herdr

CleanShot.2026-07-30.at.13.17.42.mp4

[josevelaz]

@ogulcancelik It would be great if this could get a look

[ogulcancelik]

some update on this:

this feature and #515 are joined together and will be, hopefully, released in next 1-2 updates.

multi-session requires some heavy refactors on how each session either remote or local is rendered so it's taking a bit of time. which would also enable multiple local clients per session. so bear with me :)

[IsaacYaner]

I know it’s a major refactor, and I didn’t see it in the most recent update. Could we expect it in the next one? That’d be a huge plus, we’d all be singing your praises

[cbrake]

This is something I miss from Zellij - looking forward to it!

[ogulcancelik]

this is live now with the multi-server update https://herdr.dev/blog/connecting-the-machines/