Guided Tour

A "screencast" of the Agent Shell, grouped by topic — from the welcome screen to opening the sidebar and running the everyday flows. Each step shows the keys pressed and a mock of what appears. Colours are the real Emacs face colours (same palette as the Sidebar Layouts); the frames are mock-ups, so spacing is approximate — colour and layout are the contract.

Legend — provider glyph A Auggie · C Claude · P Pi. Session state:

{dm}○{/} initializing   {y}◐{/} working   {r}◐{/} waiting (needs input)
{g}●{/} ready          {ac}●{/} finished  {r}●{/} killed

Getting oriented

The welcome screen

Emacs opens on the *decknix* buffer. Press C-c w to return to it any time.

emacs

  {hd}       __     _   __  __  _   ___ ___{/}
  {ac}   __| |___ / | | ' \|  \/  || | / __/ __| {/}
  {c}  / _` / -_) || |  ' <| |\/| || || \__ \__ \ {/}
  {br}  \__,_\___|_||_|_|\_\_|  |_||_|/_|___/___/ {/}

  {bd}Welcome to dEckMACS{/} — a modern, batteries-included Emacs config
  {dm}Vertico • Consult • Marginalia • Corfu • Embark • Magit{/}

  {c bd}1{/} Navigation & Search   {dm}C-s   M-s r   C-x b{/}
  {c bd}2{/} Editing               {dm}C-/   C-?     C-x u{/}
  {c bd}3{/} Completion & Code     {dm}TAB   C-.     M-n/p{/}
  {c bd}4{/} Git (Magit)           {dm}C-x g C-x M-g s / u{/}
  {c bd}5{/} Buffers & Windows     {dm}C-x C-f C-x k C-x 1{/}
  {c bd}6{/} Help & Discovery      {dm}C-h f C-h k  C-h t{/}

  {dm}Press 1-6 for full cheat sheets • r refresh • q quit{/}
  {dm}C-h ? help • C-x b buffers • C-x C-f files • C-c w this screen{/}

The shipping welcome buffer. Numbers 1–6 open per-topic cheat sheets.

…with agents surfaced (proposed)

The welcome screen is a natural home for a live agent summary and quick-actions into the Agent Shell. A proposed addition — a category 7 plus a status strip that mirrors the sidebar's Live section:

  {c bd}6{/} Help & Discovery      {dm}C-h f C-h k  C-h t{/}
  {c bd}7{/} {ac bd}AI Agents{/}            {dm}C-c A a start  C-c A w sidebar  C-c A s sessions{/}

  {dm}Agents{/}  {y}◐ 2 working{/}   {r}◐ 1 waiting{/}   {g}● 3 ready{/}   {dm}·  C-c A w to open{/}

Proposed, not yet shipped — mocked to show the intent (see How It Compares → roadmap).

Open the Agents sidebar

C-c A w

The four-section workspace sidebar opens on the right: Requests → WIP → Live → Sessions.

{hd}Requests (3){/} ⇅
{c}⎇ {/} {y}2d{/} upside{gd}#16570{/} {g}●{/}{gd bd}@{/}{ac}◉{/} {gd}CSE-201: refactor token cache{/}
{dm bd}↓ {/}{r}15d{/} upside#16568 {bo}π{/}   {dm}bump: dependency update{/}
{dm bd}↓ {/} {y}1d{/} reapit#123 {r}◐{/}{c bd}@{/} CSE-204: fix pubsub timeout

{hd}WIP (2){/}
{g bd}⎇*{/} {g}●{/} decknix{gd}#812{/}       [3⬆ 2✓]
{c}⎇ {/} {y}★{/} decknix-config#77  {y}draft{/}

{hd}Live (2){/}
 > {y}A{/} {y}◐{/} feature/token-cache  {rp}decknix{/}   [2⬆ 1✓] {r bd}📥1{/}
   {g}C{/} {g}●{/} review/auth          {rp}decknix{/}   {sg bd}↩{/}

{hd}Sessions (18){/}  {dm}…recent by tag / date{/}

Colour is load-bearing: green approved/ready, red needs-you/CI-fail, yellow draft/working, blue branch, pink bot. ⎇* = branch live in a session; ◉ = a review session is already open on that PR.

Running a session

Start a session

C-c A n

A provider picker appears (Vertico). Choose the agent to launch.

{dm}Start agent (provider):{/}
 {ac}>{/} {g}C{/}  Claude Code        {dm}(default · claude-code){/}
   {y}A{/}  Auggie             {dm}(Augment Code){/}
   {c}P{/}  Pi                 {dm}(Contextual AI){/}
   {dm}?{/}  Gemini             {dm}(Google){/}

Pick C and a fresh Claude session buffer opens; the Live section gains a ○→◐ row.

Watch its sub-agents

C-c A w

As the agent spins up sub-agents, the Live section shows each with its own state — colour tells you at a glance who needs you and who's done.

{hd}Live (1 · 3 sub){/}
 > {g}C{/} {y}◐{/} feature/token-cache   {rp}decknix{/}
     {dm}├─{/} {g}●{/} explore   {dm}mapped cache call-sites{/}
     {dm}├─{/} {y}◐{/} implement {dm}editing cache.rs …{/}
     {dm}└─{/} {r}◐{/} verify    {r bd}needs input{/} {dm}approve test run?{/}

Per-sub-agent status + colour + a fold toggle for completed ones is the near-term build (Feature 1 of the resourcing roadmap); mocked as the target UX.

Compose a multi-line prompt

C-c A e

A dedicated compose buffer opens — write freely, then submit.

{dm}─ *compose: feature/token-cache* ──────────────{/}
 Refactor the token cache to expire entries lazily
 on read instead of a background sweep. Keep the
 public API stable; add a test for the 410 path.

{dm}────────────────────────────────────────────────{/}
 {ac}C-c C-c{/} submit   {dm}C-c C-k cancel   M-p/M-n history   M-r search{/}

C-c C-c sends it; M-p/M-n walk prompt history, M-r searches it (consult).

Reviewing & shipping

Review a PR

C-c A c→r

From a Requests row (or the quick-action), launch a review session pre-linked to the PR.

{hd}Requests (3){/}
 {ac}>{/} {c}⎇ {/} {y}2d{/} upside{gd}#16570{/} {g}●{/}{gd bd}@{/} {gd}CSE-201: refactor token cache{/}
       {dm}review session launching…{/} {ac}◉{/}
   {dm bd}↓ {/}{r}15d{/} upside#16568 {bo}π{/} {dm}bump: dependency update{/}

The ◉ marks the row now has a live review session. C-c s l links another PR to the current session; C-c s u unlinks.

Inspect · tag · link

C-c s i

C-c s i prints a one-line session summary; C-c s t a adds a tag; C-c s l links a PR.

{dm}Session:{/} 3f9a1c2e…  {dm}Conv:{/} b71e…  {dm}Model:{/} {g}opus{/}  {dm}Mode:{/} {y}auto{/}
{dm}Tags:{/} {c}#token-cache #CONN-473{/}   {dm}Exchanges:{/} 14
{dm}Workspace:{/} ~/tools/decknix
{dm}Created:{/} 2026-07-08 09:12   {dm}Modified:{/} 2026-07-08 13:47

Tags, workspace, model, permission-mode and linked PRs all persist per-conversation and survive resume/fork.

Copy a region as Slack / HTML / PDF

C-c x s

Select any Markdown in the buffer and export it — s Slack mrkdwn, h HTML, P PDF, t plain / re-align table.

{dm}region (Markdown):{/}
  **Root cause:** the `/rest/api/2/search` endpoint was removed.
  See [the changelog](https://x/CHANGE-20).

{ac}C-c x s{/}  {dm}→ clipboard (Slack mrkdwn):{/}
  {g}*Root cause:* the `/rest/api/2/search` endpoint was removed.
  {/}

Fence- and table-aware, pure-string transforms — paste straight into Slack, a PR comment, or a doc.

Managing many sessions

Resume a past session

C-c A s

One picker spans live + saved + new. Live rows are coloured, saved ones dimmed; M-a / M-c / M-p toggle Auggie / Claude / Pi rows, C-u C-c A s expands every saved snapshot.

{dm}Sessions — live + saved  (M-a/M-c/M-p filter · C-u expand):{/}
 {ac}>{/} {g}C{/} {g}●{/} review/auth          {dm}decknix · 2m{/}      {c}#auth{/}
     {y}A{/} {y}◐{/} feature/token-cache   {dm}decknix · now{/}
     {dm}C{/} {dm}·{/}  CONN-473 spike        {dm}decknix · 3d{/}      {c}#spike{/}
     {dm}A{/} {dm}·{/}  proptrack timeout     {dm}nurturecloud · 5d{/}

Selecting a saved row resumes it with its history window restored and input ring rebuilt. C-c A f forks a session instead — the fork keeps the source's tags, workspace and conversation identity.

Search every session

C-c A g

Full-text ripgrep across all transcripts, with the match in context. RET jumps straight to the matching turn.

{dm}Grep all sessions:{/} {c}pubsub timeout{/}
 {gd}proptrack timeout{/}   {dm}nurturecloud · 5d{/}
   {dm}…the {/}{y}pubsub timeout{/}{dm} was an unacked message redelivery …{/}
 {gd}CONN-473 spike{/}      {dm}decknix · 3d{/}
   {dm}…retry policy on a {/}{y}pubsub timeout{/}{dm} should back off …{/}

Never lose a decision — find the conversation where you made it.

Jump to what needs you

C-c A j

Cycle straight to the next session carrying red/amber attention — the agent-shell answer to cmux's "which one needs me?"

{dm}Jump to attention →{/}  {r}◐{/} feature/token-cache  {dm}(verify: “approve test run?”){/}

Repeated presses walk the attention queue: waiting sessions first, then CI failures and review requests.

Batch one prompt to several sessions

C-c A s→C-SPC…B

Mark rows in the picker with C-SPC, then batch a single prompt to all of them — handy for "rebase onto main" or "add the new lint" across several worktrees.

{dm}Sessions  (C-SPC mark · B batch):{/}
 {g}✓{/} {g}C{/} {g}●{/} review/auth           {rp}decknix{/}
 {g}✓{/} {g}A{/} {g}●{/} feature/token-cache   {rp}decknix{/}
   {dm}A{/} {dm}·{/}  proptrack timeout      {rp}nurturecloud{/}
 {dm}2 marked{/} {ac}· B → send one prompt to both{/}

Marked sessions each receive the composed prompt; results stream back into their own buffers.

Keys used in this tour

Inside an agent-shell buffer the A prefix is dropped — C-c s, C-c e, C-c ?. Full reference: Keybindings.