TUI: surface the paired terminal (Agent view indicator, live-mode swap, split preview) #4535

Activity

1. ChristopheVilain

   added

   enhancementNew feature or improvementNew feature or improvement

   on Oct 15, 2026
2. Seluj78

   self-assigned this

   on Oct 15, 2026
3. Seluj78 commented on Oct 15, 2026

   

   Seluj78

   on Oct 15, 2026

   Member

   More actions

   Thank you for the issue @ChristopheVilain !

   The web UI has this exact functionality, but it looks like the TUI doesn't. I'll investigate !
4. Seluj78 commented on Oct 15, 2026

   

   Seluj78

   on Oct 15, 2026

   Member

   More actions

   Note: Claude handled the investigation and prose via back-and-forth. Idea, decisions, and everything else are mine. — @Seluj78

   Dug into this. Most of what you describe already exists in the TUI, it is just hidden behind a view toggle. Rescoping this issue to the real gaps below, plus a split agent/terminal preview like the web UI has.

   What's there today

   • The terminal survives detach. T attaches the session's paired shell (aoe_term_<title>_<id>). Ctrl+b d only detaches; the tmux session keeps running. It is killed only by x in Terminal view or by stopping/deleting the agent session (src/session/instance/kill.rs:332).
   • Terminals are listed, in their own view. t flips the side panel from agent sessions to Terminals. Rows with a live shell show the running spinner; Enter reattaches (src/tui/home/render.rs:1234, :1784).
   • The Tab / Ctrl+Q flow works on terminals too. In Terminal view, Tab starts live mode on the shell with the sidebar still visible, Ctrl+Q leaves. Auto Live-Send On View Switch (Settings, Interaction) drops you into live mode as soon as you press t. See docs/guides/live-mode.md.
   • Same shell as the web UI. Web "Paired terminal" tab 0 and the TUI T terminal are one tmux session (src/session/instance/terminal.rs:116-124).

   Workaround today: select session, t, Tab, work in the shell, Ctrl+Q, t back to agents.

   Gaps

   1. No hint in Agent view that a terminal is running. The spinner only renders in Terminal view (render.rs:1784); after detaching, the shell looks gone. This is what you hit.
   2. Agent/terminal flip costs several keys in live mode. The leader menu only knows k, b, q (src/tui/home/input.rs:6090-6094). Toggling the view from the palette exits live mode first (input.rs:3862-3870).
   3. Agent and terminal cannot be on screen together. The preview is single-target: one capture worker and target (src/tui/home/mod.rs:229-230), one pane rect, scroll offset and selection (mod.rs:341, :344, :404).
   4. Docs. T is missing from the docs/quick-start.md key table, and docs/guides/web/terminal.md does not say the shell is shared with the TUI.

   Proposal

   A. Indicator + docs (XS). In Agent view, render a small terminal glyph on rows whose paired terminal exists, reusing the session_exists_for_display check from render.rs:1784. Add T to the quick-start table and note the shared shell in the web terminal guide.

   B. Leader t swaps the live target. In live mode, Ctrl+B then t switches LiveSendTarget between Agent and Terminal / ContainerTerminal (src/tui/home/live_send.rs:262) without leaving live mode, starting the terminal if it is not running. t is free in the leader menu.

   C. Split preview. Optional layout that stacks the agent preview over the paired terminal preview for the selected session:

   • Second capture worker for the terminal pane alongside the existing one. Terminal capture already runs without VT live (render.rs:2119-2121), so it reuses the capture-pane path.
   • Per-pane rect, scroll offset and selection instead of the single fields above.
   • Live mode relays to the focused pane (accent border), leader t from B moves focus. Each pane resizes its own tmux session through resize_window_if_owner (src/tmux/session.rs:1568); agent and terminal are separate tmux sessions, so the two resizes do not fight.
   • No tmux join-pane tricks: the web UI attaches the same sessions, and moving panes between sessions would break it.

   A and B are independent and small. C builds on B.

   User stories / regression tests

   Implementation MUST add tests covering each story below; PR is not done without them.

   • As a TUI user, when I open a session's terminal with T and detach with Ctrl+b d, then that session's row in Agent view shows a terminal-running indicator, and the indicator disappears after the terminal is killed with x.
     • Suggested test layer: Rust unit (src/tui/home/tests/, render buffer assertion).
   • As a TUI user in live mode on an agent, when I press Ctrl+B then t, then my keystrokes go to that session's paired terminal (started if missing) without leaving live mode, and Ctrl+B then t again sends them back to the agent.
     • Suggested test layer: Rust unit for the target swap, tests/e2e/ for the keystrokes landing in the right tmux pane.
   • As a TUI user with the split preview on, when I select a session with a running terminal, then the preview shows the agent pane and the terminal pane together, live mode relays only to the focused pane, and the focused pane has the accent border.
     • Suggested test layer: tests/e2e/ (capture both tmux panes after typing into each).

   Open questions

   • Split toggle: leader chord, a list-view key, or a persisted setting? And stacked only, or side-by-side on wide terminals?
   • In split mode with no terminal running, show an empty "press T to start" pane, or collapse back to a single preview?
   • Container sessions: split shows whichever terminal mode is selected (c toggle), or host only?

   Out of scope

   • Listing web extra terminal tabs (index 1 and up) in the TUI.
   • Standalone terminals not tied to an agent session.
   • Session cycling while fully attached through tmux (aoe installs no tmux key bindings).

   Cross-references

   • tui: persistent sidebar while attached (parity with web / mobile / cockpit) #1527: persistent sidebar while attached, closed via live mode; this extends live mode to the paired terminal.
5. Seluj78

   added

   P2Backlog: real, but not nowBacklog: real, but not now

   area:tuiTerminal UITerminal UI

   on Oct 15, 2026
6. Seluj78

   changed the title [-]TUI - Persist a terminal session in the side-panel[/-] [+]TUI: surface the paired terminal (Agent view indicator, live-mode swap, split preview)[/+] on Oct 15, 2026
7. Seluj78

   added this to Agent of Empireson Oct 15, 2026
8. github-project-automation

   moved this to Backlog in Agent of Empireson Oct 15, 2026
9. Seluj78

   moved this from Backlog to Ready in Agent of Empireson Oct 15, 2026
10. Seluj78

    moved this from Ready to In progress in Agent of Empireson Oct 15, 2026
11. njbrake

    closed this as completedin #4536on Oct 15, 2026
12. github-project-automation

    moved this from In progress to Done in Agent of Empireson Oct 15, 2026