Multi-Session (Layer 2)

Layer 2 turns agent-shell from a single-buffer chat into a full session management system.

Unified Session Picker (`C-c s`)

The session picker combines three sources into one completing-read:

Agent session:
  [new]   Start a new auggie session
  [live]  *agent-shell*<proptrack-fix>
  [live]  *agent-shell*<decknix-docs>
  [saved] a1b2c3d4  2h ago   12x  Investigate proptrack pubsub timeout...
  [saved] e5f6g7h8  3d ago    8x  Refactor agent-shell keybindings... [decknix, refactor]

[new] — starts a fresh agent-shell session
[live] — switches to an existing Emacs buffer
[saved] — resumes a saved auggie session (boots a new agent-shell with --resume <id>)

Saved sessions show: truncated ID, relative time, exchange count, first message preview, and tags (if any).

Session Resume

When you select a saved session, the picker:

Appends --resume <session-id> to the ACP command
Starts a new agent-shell buffer with the auggie session restored
Stores the auggie session ID in a buffer-local variable for history/tagging

For Claude, Emacs restores the visible transcript from disk while native ACP session/resume restores the model context. The bridge's similarly named replay-user-messages option only echoes newly submitted stdin messages for turn acknowledgement; it does not replay saved conversation history.

When you multi-select many saved sessions, decknix routes the resumes through the spawn queue so the bridge startups are staggered instead of all cold-starting at once.

;; The resume mechanism — auggie CLI handles the actual session restore
(let ((agent-shell-auggie-acp-command
       (append agent-shell-auggie-acp-command
               (list "--resume" session-id))))
  (agent-shell-start :config (agent-shell-auggie-make-agent-config)))

Session History (`C-c h` / `C-c H`)

View the full conversation history for any session:

C-c h — DWIM: if in an agent-shell buffer with a known session, shows that session's history. Otherwise, prompts to pick.
C-c H — Always pick: shows the session picker regardless of current buffer.

History is rendered by generating a share link via auggie session share <id> and opening it in xwidget-webkit (embedded browser) or eww (text browser) as fallback — all inside Emacs.

Clean Quit (`C-c q`)

Quitting a session:

Prompts for confirmation (y-or-n-p)
Switches to the previous buffer
Kills the agent-shell buffer (sends SIGHUP to auggie, which auto-saves the session)

The session is immediately available in the picker's saved list for future resume.

Buffer Rename (`C-c r`)

Rename the agent-shell buffer for clarity:

*agent-shell*  →  *agent-shell*<proptrack-pubsub-fix>

Uses agent-shell-rename-buffer from the core package.

Extensions

Manager Dashboard (`C-c m`)

agent-shell-manager provides a tabulated list of all agent-shell buffers at the bottom of the frame. Toggle with C-c m.

Workspace Tab (`C-c w`)

agent-shell-workspace creates a dedicated tab-bar tab with a sidebar showing all agent sessions. Toggle with C-c w.

Attention Tracker (`C-c j`)

agent-shell-attention places a mode-line indicator; decknix supplies its counts from the same states the sidebar's Needs you block uses:

AS:2/5    ← 2 sessions need you (netfail / waiting / asking), 5 need you or are working

Click it to choose one. Those three states share one look everywhere: the ⚑ glyph and decknix-attention-face (purple) in the sidebar, on Requests rows and Reviews group rows, and the same purple as a tab-bar tint.

C-c j (C-c A j globally) jumps to the next session that needs you, by decknix's own session states: netfail, then waiting, then asking, the longest wait first within each. Pressing it again moves on to the next one, C-u lets you choose, and a session living in another tab is visited in that tab. In the sidebar, j moves to that session's row and J goes to it.

Nix Options

programs.emacs.decknix.agentShell = {
  manager.enable = true;    # Tabulated dashboard
  workspace.enable = true;  # Tab-bar workspace
  attention.enable = true;  # Mode-line tracker
};

Decknix Documentation