Terminal Sessions – VSCode extension for tmux terminals that survive restarts

Persistent terminal sessions for Cursor and VS Code, with first-class awareness of your AI coding agents — Claude Code, Codex, Antigravity ( agy), and Grok (xAI). Terminals survive full editor restart, organized per workspace, and the sidebar shows live agent state: working/tool/waiting, context usage, cost, last user and assistant messages. Browse, read, name, resume, and clean up every past conversation on your machine, across all four agents.

Every terminal is wrapped in a tmux session whose server runs independent of the editor. Quit Cursor, reboot the window, crash the renderer: Claude Code, dev servers, REPLs, migrations, SSH sessions keep running. Reopen the workspace and everything is where you left it.

Platform	tmux backend	Notifications	Click-to-focus on notif	Status
macOS (local)
Native	macOS Notification Center + modal alert	Yes (osascript / terminal-notifier)	Full support
Linux (local)
Native	notify-send (libnotify) + optional zenity modal
Yes (zenity)	Full support
Remote-SSH / Remote-WSL
Native (tmux on the remote)	IPC-forwarded VS Code toast or modal in the local Cursor window	Yes (via VS Code API)	Full support
Windows (native)
Not supported — needs WSL or Remote-SSH	Falls back to VS Code toast	No	Requires WSL or SSH

Windows users:tmux does not run natively on Windows. The extension works normally on:

WSL— install the extension in the WSL-Remote window, install tmux in WSL (sudo apt install tmux

)Remote-SSH— connect to a Linux/macOS host, install the extension on the remote sideNative Windows (PowerShell, cmd, Git Bash) is not supported.

Remote-SSH / Remote-WSL users:you do NOT need to installterminal-notifier

orlibnotify

on the remote machine. The extension detects the remote extension host viavscode.env.remoteName

and routes notifications through the VS Code API, which forwards them to your local Cursor UI automatically. TheShow terminal

button on waiting alerts still works across the IPC bridge.

VS Code's built-in terminal.integrated.persistentSessionReviveProcess

only survives window reloads, not full app quits. Child processes always die when the editor fully restarts. This extension solves it by wrapping each terminal in a tmux session whose server daemon is independent of the editor process.

Three moving pieces, each independent, composed to give you a persistent and observable terminal layer.

1. tmux as the process keeper. Every persistent terminal you open is actually tmux attach-session

against a named session on a tmux server that runs outside of Cursor. Quit Cursor, reboot the window, crash the renderer: the shells and anything they spawned (Claude Code, npm run dev

, a migration, a long SSH) keep running in the tmux server. When you reopen the workspace, the extension offers to re-attach. Sessions are named ts-<workspace-hash>-<tabId>

, so two projects or two git worktrees of the same repo never collide.

2. A managed ~/.terminal-sessions/tmux.conf. The extension writes its own tmux config with defaults tuned for Cursor: mouse on, large scrollback, OSC 52 clipboard, modern CSI-u keys, DECSET 2026 synchronized output, and since v0.11 the

CLAUDE_CODE_NO_FLICKER

and CLAUDE_CODE_DISABLE_MOUSE_CLICKS

env vars baked in so Claude Code renders cleanly in alt-screen and trackpad scroll stays inside the conversation view. Your own ~/.tmux.conf

is never touched; the managed file loads it at the end if it exists, so your personal theme or keybindings still apply.3. AI-agent awareness via hooks + transcript tailing. If you opt in, the extension installs lifecycle hooks for each agent you use — SessionStart | UserPromptSubmit | PreToolUse | PostToolUse | Notification | Stop | SessionEnd

for Claude (~/.claude/settings.json

), the equivalent events for Codex (~/.codex/hooks.json

) and Antigravity (~/.gemini/antigravity-cli/settings.json

, plus a statusLine

for live context). A single shared forwarder normalizes each agent's differing event payload and writes a JSON line to ~/.terminal-sessions/agent-events.log

, tagged with the agent id and the tmux session the agent is running in. A file watcher feeds those events into an in-memory map and sets the per-session state (working, tool, waiting, idle). In parallel, a transcript tailer follows the agent's on-disk conversation file and, through that agent's provider, extracts model, token counts, context-window usage, and cost. The sidebar reads both streams and renders the merged snapshot. A conversation can only belong to one tmux session at a time; starting the same conversation in a different tab transfers ownership so the sidebar never shows duplicate live states. Everything below works the same way for Claude, Codex, and Antigravity — Claude is simply the most battle-tested provider.

What persists across what

Event	tmux session	Shell process	Claude process	Conversation (.jsonl )
Close a tab	kept	kept	kept	kept
Reload window (Cmd+R )
kept	kept	kept	kept
Quit Cursor (Cmd+Q )
kept	kept	kept	kept
Restart Session command	killed	killed	killed	kept (auto-resumed in v0.11+)
Mac reboot	killed	killed	killed	kept (recreate from index)

Persistent sessions across full editor quit/restart via tmuxWorkspace-scoped naming— each project gets its own namespace (8-char path hash), no cross-project collisions** Git-worktree aware**— different paths = different hashes, so worktrees automatically get separate sessions** Auto-resume toaston workspace open — "Found N sessions from last time — [Resume All / Pick... / Ignore]" Configurable auto-restore**—auto

resumes all,ask

prompts,off

disablesMax age filter— skip auto-restore for sessions older than N hours (default 72h)** Safe tab close**— closing a terminal tab detaches; session keeps running in the background** Explicit killvia command palette, right-click on sidebar item, or "Kill all for this workspace" Auto-prunestale sessions after configurable days (default 14) Lock a session against Kill**— right-click →** Lock (Protect from Kill); a padlock takes the Kill button's place and the session can no longer be killed — not from the row, not by "Kill all for this workspace", not by auto-prune — until you right-click →Unlock (Allow Kill)**. The inline padlock is a deliberate indicator only (clicking it won't unlock), so an important long-runner survives an accidental click. Restart and Stop stay available

Terminal Profile "Persistent Session"— available in the+ ∨

dropdown; can be set as default so every new terminal auto-wraps in tmuxSidebar tree view— grouped by workspace, with status indicators (attached vs detached) and relative timestamps. Lives** under the Explorerby default; drag it (or right-click its header →Move View) to your own Activity Bar icon, the panel, or the secondary sidebarRich hover tooltip**— hovering a session row shows its tmux ID, workspace, the actual** start folder (cwd)for subfolder sessions, created/last-attached times, and — while an agent is active — the live Conversation ID**, model, API-equivalent cost, context %, token totals, and the last user/assistant messages** Sidebar badge**(v0.11+) — a red numeric badge appears on the view's host icon (the Explorer, or wherever you've placed the view) when Claude sessions need attention.waiting

count takes priority (user permission pending), falls back toworking

count. Tooltip explains which is whichClick terminal tab → reveal sidebar session(v0.11+) — clicking anyTerminal Sessions #N

tab in the VS Code terminal panel selects and highlights the matching row in the Terminal Sessions sidebar, auto-expanding its workspace groupStatus bar badge—⚡ ts: 2▶ 4⇄

(attached · detached), click to open the attach pickerView conversation— open the session's agent transcript as readable Markdown; reads the transcript.jsonl

directly, so it works on stopped sessions too (not just live ones) and shows the real conversation regardless of rendererRename sessions with custom labels (persisted in index)Custom icon & color per session— pick from codicons (robot, rocket, flame, database, server, bug, etc.) and ANSI colors; applied to the terminal tab icon and sidebarRestart session(v0.11+: with Claude auto-resume) — kill the current tmux session (any program in it, incl. Claude Code) and respawn a fresh shell; keeps the label, icon, color, and workspace. If Claude was running, the extension auto-detects its session ID, verifies the transcript is still on disk, and runsclaude --resume <id>

in the new shell. Conversation context survives, Ink renderer state is cleanSmart click behavior— clicking a session that's already attached focuses its existing terminal tab instead of opening a duplicate** Right-click context menuon sidebar items — View Conversation, Restart, Stop/Start, Rename, Icon, Color, Mute notifications, Lock/Unlock, Kill Explorer right-click → "Open in Integrated Terminal - Persistent"**— on any folder, opens a persistent tmux session rooted at that folder. The VS Code tab description reflects the actual folder name (v0.11+; earlier versions always showed the workspace root)

Custom— drag sessions in the sidebar to rearrange; order persisted across restarts (stored per-session in~/.terminal-sessions/index.json

)Recently used— most recently focused session floats to top** Creation order**— oldest first (default, backward-compatible)** Alphabetical**— by session label- Toggle via the $(list-ordered)

icon in the sidebar title bar; dragging automatically switches to Custom

Filter modes— showall

, onlyrunning

, or onlystopped

sessions via the$(filter)

icon in the title bar (terminalSessions.sidebarFilterMode

)Stop / Start a session— a session (kills the tmux session but keeps the row, with its label, icon, color, and agent history) and start it again later, instead of killing it outright. Stopped rows get an inline$(play)

Groups & master groups— organize sessions under named groups, and groups under master groups, via right-clickNew Group…

/New Master Group…

/Move to Group…

, with drag-and-drop and per-group rename/delete. Purely organizational; the underlying tmux sessions are untouchedRe-attach All Ghost Terminals— one click ($(debug-restart)

in the title bar) revives the orange/disconnected tabs you get after a Cursor restart, in sidebar orderReveal Session Folder— right-click → open the session's working directory in the OS file manager (Finder/Explorer), or jump to its row from the terminal tab viaReveal in Terminal Sessions View

Copy Last Conversation ID / Path— right-click → put the most recent agent conversation's UUID, or the full path to its transcript.jsonl

, on the clipboard (works for Claude, Codex, and Antigravity)

— one collapsible row groups every subagent a Claude session spawned, so sessions with lots of agents stay tidy. Auto-expanded while anything is live; collapsed when everything finishes. Tooltip previews the first five agents with their state🤖 Agents (N running · M done)

folder per sessionLive per-subagent rows— state icon (spinner / tools / check), elapsed time, current tool with input preview, last streamed message. Nests recursively for agents that spawn sub-subagentsInline subagent counter in the session description—Terminal Sessions waiting input · 69% ctx · 🤖 2 running

(falls back to🤖 N done

after completion). See live agent activity without expandingAgent label—<subagent_type> — <description>

pulled from theAgent

/Task

tool input (e.g.researcher — MCP servers for note apps

). Tooltip shows depth, parent agent id, and timestampsBackground-agent support— Claude Code ≥ 2.1.119 spawns subagents via theAgent

tool withrun_in_background: true

; their activity is written to per-agent transcripts in<main-jsonl>/subagents/agent-<id>.jsonl

(not as sidechain messages). The tailer scans that sibling directory on a 3-second poll, so live state surfaces within ~3 s even without the main jsonl being written. The classic synchronousTask

tool path keeps working too(defaultterminalSessions.showCompletedSubagents

true

) — keeps completed agents visible so short runs don't flicker in and out. Flip tofalse

(or runTerminal Sessions: Toggle Show Completed Subagents

) to focus only on live work— right-click a subagent row → opens its transcript jsonl in an editor tab jumped to the first line where that agent was registered. For background agents this is the small per-agent file, much easier to read than the main conversation transcriptOpen Subagent Transcript

commandAuto-done on parent idle— when the parent session has been idle for 2+ minutes, stragglers flaggedworking

are marked done in the rendered snapshot so the sidebar doesn't spin forever on interrupted agents

One sidebar, four agents— the same live status, context %, cost, history, and auto-resume work for** Claude Code**,** Codex**,** Antigravity**(agy

), andGrok(xAI). Each tracked session shows which agent it's running, so a row readsCodex working 12s

vsClaude working 12s

Auto-detection— Claude is always on; Codex, Antigravity and Grok turn on automatically when their CLI (codex

/agy

/grok

) is found on yourPATH

. Override explicitly withterminalSessions.enabledAgents

(e.g.["claude", "codex"]

)Per-agent hooks, one forwarder—Terminal Sessions: Install AI Agent Hooks

writes the right hook into each agent's own settings file (~/.claude/settings.json

,~/.codex/hooks.json

,~/.gemini/antigravity-cli/settings.json

); a single shared script normalizes their differing event payloads. Your model and MCP config are never disturbedGrok needs no hooks— Grok's lifecycle hooks are project-scoped and trust-gated, so the extension tracks it without installing anything: it discovers live Grok sessions from~/.grok/active_sessions.json

, matches each to its tmux pane by process tree, and tails the session's ACPupdates.jsonl

for status, tokens, and messages. Nothing is written into your projectsAgent-correct resume— restart/resume runs the right command per agent:claude --resume <id>

(cwd-sensitive),codex resume <id>

(restores its own recorded cwd), oragy --conversation <id>

. The extension picks it from the session's recorded agent automaticallyProvider abstraction— adding more agents later is a new provider file, no core changes; all three share one tracker, state machine, and notification path

Per-session state indicator— icon + description reflect whether the agent isworking

, running atool

(with tool name),waiting

for user permission, oridle

(with time-since). State is derived from the transcript directly so it stays correct even when hooks are out of dateAPI-equivalent cost in USD— real cost per session computed from the transcript using the live Anthropic rate card, per-model (Opus 4.7 at $5/$25 in/out, Opus 4.1 at $15/$75, Sonnet at $3/$15, Haiku at $1/$5, plus separate cache-read and 5-min/1-hour cache-write tiers). Retried turns are de-duplicated bymessage.id

; subagents on different models are counted automatically with their own rate. Sidebar showsopus · $55.25 · 364 turns

; tooltip shows per-model breakdown and the raw token totalsContext-window gauge(v0.11 fix) — the31% ctx

suffix appears next to every Claude-active session. CrossesterminalSessions.contextWarnPct

(default 0.8) →⚠ 87% ctx

. Limit is auto-detected per session: Opus/Sonnet 4.5+ default to 1M-context, older models to 200k; if any single turn exceeds 200k we pin the limit to 1M. Subagent turns are excluded because they have their own contextNested detail rows— under each active session, rows show last user message, last Claude reply, model/cost/turns, current tool with its input (e.g.Bash: "npm run build"

); configurableauto | always | off

Search past sessions—$(search)

button in the sidebar (orTerminal Sessions: Find Session by Prompt…

command) opens a fuzzy picker over every transcript on your machine. Jump to transcript, copy session ID, or reveal the cwdDeduplicated live state(v0.11+) — if you ranclaude --resume <id>

in multiple tabs over time, the tracker now transfers ownership on each new hook event, so only the tab currently running that conversation shows live state. Others snap back to idle

Resume Session from Archive— the$(history)

button on the sidebar toolbar (orTerminal Sessions: Resume Session from Archive…

) opens a picker ofevery past conversation on disk, across all three agents, even when nothing is live in tmux for it. Defaults to the current workspace with a one-click toggle to show all projects. Accepting a row resumes it into your active session or a fresh persistent oneView Conversation— right-click a session (or the eye button in the archive picker) to open a readable Markdown rendering of the conversation in VS Code's preview: user and assistant turns, with thinking blocks and tool calls in collapsible sections. No more squinting at raw.jsonl

Name Conversation— give any session a friendly name; it shows in the archive picker and the viewer title. Names live in the extension's sidecar index, so the agent's transcript files are never modifiedClean Up Empty / Invalid Sessions— a maintenance action (sidebar overflow⋯

menu) that finds empty or "Invalid API key" conversations and soft-deletes them into~/.claude/projects/.bak

, with a preview and confirmation. The agent's own database and session index are never touched; moved files can be restored manually

Claude Stop notification— fires when Claude finishes a response. Distinct from the waiting variant so you can glance at the sound/icon and know whether you need to act. Min-duration filter prevents notif-storms on short turnsClaude Waiting notification(v0.11+) — fires when Claude blocks for user permission (tool approval, risky command, URL access). Distinct sound (defaultSosumi

vsGlass

for Stop),⚠ Claude needs approval

title, subtitle is the session label. Two styles viaterminalSessions.waitingAlertStyle

:banner

— standard macOS/Linux notification, auto-dismissesalert

—persistent modal dialog with aShow terminal

button that activates Cursor and focuses the matching tab. macOS usesosascript display alert

; Linux useszenity --question

(if installed)

Click-to-focus(v0.11+, macOS) — ifterminal-notifier

is installed (brew install terminal-notifier

), clicking any notification banner or alert brings Cursor to the foreground instead of Script Editor. Withoutterminal-notifier

notifications still work, but click lands in Script Editor — see the Requirements section for the exact trade-offWorks over Remote-SSH / Remote-WSL(v0.11+) — when the extension host runs on a remote machine (the tmux session lives on the server, Cursor runs on your laptop), OS native notifications posted from the remote can't reach your desktop. The extension auto-detects this viavscode.env.remoteName

and routes through the VS Code API instead: waiting events become an IPC-forwarded warning toast (banner style) or a blocking modal dialog (alert

style) that pops up in your local Cursor window. TheShow terminal

button still works the same way — click it and the extension iteratesvscode.window.terminals

on the remote extension host and focuses the matching tab in your local UI. No extra setup on the remote; libnotify/terminal-notifier are not used in remote mode because they would be uselessGlobal on/off toggle(v0.11+) — bell icon in the Terminal Sessions sidebar title bar togglesnotifyOnClaudeWaiting

. When off, the icon switches to$(bell-slash)

. Command Palette also hasTerminal Sessions: Toggle Claude Waiting Alerts (Global)

Per-session mute(v0.11+) — right-click a session →Mute Notifications

. Stop and Waiting notifications for that session are silenced until you unmute. Muted sessions display a🔕

in the sidebar description. Useful for long-running experiments where you don't want beepsNative macOS Notification Center— mode-switchable (auto

: native when Cursor is unfocused / toast when focused;always

;never

)Native Linux(v0.11+) — usesnotify-send

with urgencycritical

for warnings (sticky until dismissed on most desktop environments); falls back to VS Code toast if libnotify is missingSound picker— 14 macOS built-in sounds (Glass, Ping, Hero, Pop, Sosumi, …). Separate settings for Stop (notificationSound

) and Waiting (notificationSoundWaiting

). Linux sound mapping is not implemented; sound is macOS-onlyLong-running command alerts— notification when a command takes longer than a configurable threshold (default 30s)** Post-reboot recovery**— "Recreate Sessions from Index" rebuilds your sessions after a reboot wiped the tmux server; optionalclaude --resume <id>

hint toast so you can reattach Claude Code sessions by ID

macOS decides whether notifications show as auto-dismissing banners or sticky alerts at the OS level, not from the app. To make every notification stay on screen until you dismiss it:

• Open System Settings → Notifications - Find Script Editor(that is the app that posts our notifications via osascript) - Change Notification style fromBanners

toAlerts

Alerts get a Show

button and stay in the top-right corner until you click it or Close. The terminalSessions.waitingAlertStyle: "alert"

setting is an alternative that works without changing System Settings — it produces a modal dialog instead of a banner.

The extension generates and manages ~/.terminal-sessions/tmux.conf

with sensible defaults tuned for Cursor. Your default ~/.tmux.conf

is not touched — this file only loads when the extension starts a session.

Defaults include:

Mouse on, 50 000 line scrollback, 10ms escape time, focus events,exit-empty off

True color support (tmux-256color

+xterm-256color:RGB

)OSC 52 clipboard(set-clipboard on

) — selections copy to the system clipboard through Cursor automaticallyDECSET 2026 synchronized output passthrough (terminal-features xterm*:sync

) — apps like Claude Code that emit the sequence stop producing flicker through tmux— TUIs can send OSC/kitty-graphics/clipboard sequences through unfilteredallow-passthrough on

— modern CSI-u encoding so Ctrl+Shift combos reach Claude Code correctlyextended-keys on

andCLAUDE_CODE_NO_FLICKER=1

baked in viaCLAUDE_CODE_DISABLE_MOUSE_CLICKS=1

set-environment -g

(v0.11+) — every new tmux window inherits these, so Claude renders in alt-screen and trackpad scroll stays inside the conversation view. No shell rc edit requiredDrag-select stays in copy-mode(tmux default exits copy-mode and jumps to prompt — override usescopy-selection-no-clear

)Trackpad-friendly scroll— 1 line per tick (default 5 is too fast on trackpads)** Custom prefix**(screen-style).Ctrl+A

Ctrl+A Ctrl+A

sends a literal Ctrl+AMenu on— copy mode, paste, splits, zoom, rename, kill, respawn, reload configCtrl+A q

Status bar off— Cursor has its own UI, saves a row** Inherit**~/.tmux.conf

if present (append your theme/keybinds)

On updates, if the managed file is out of date you get a one-time toast offering to regenerate it. The old file is backed up next to it with a timestamp before any rewrite.

Two commands:

Terminal Sessions: Open tmux.conf

— opens the file in an editorTerminal Sessions: Reload tmux Config

— applies changes to all running sessions

Remote-SSH support— runs on whichever side hosts the workspace (remote when connected over SSH, local otherwise). Install on both, the right copy activates per window. One VSIX works both local and remoteNo lock-in— everything is plain tmux. If the extension breaks you cantmux ls

andtmux attach -t ts-xxx

from any system terminalIndex file at~/.terminal-sessions/index.json

maps workspace hashes to readable paths and labels (for debugging or external tools)

tmux on yourPATH

:brew install tmux

(macOS) orsudo apt install tmux

(Debian/Ubuntu) orsudo dnf install tmux

(RHEL/Fedora)Claude Code ≥ 2.1.110 if you want theCLAUDE_CODE_NO_FLICKER

rendering fix to take effect (earlier versions had a regression that wiped scrollback)

The extension works out of the box, but the click-to-focus behavior on notifications depends on small platform helpers. Without them, you still get the notification — you just can't click it to jump straight to the right terminal tab.

macOS

brew install terminal-notifier

— makesclick on a instead of bouncing you to Script Editor. Without it, notifications still show up, but they are posted viaClaude done

/Claude needs approval

banner focus Cursorosascript

which attributes them to Script Editor.app; clicking "Show" opens Script Editor, not the IDE. With it, the extension usesterminal-notifier -activate <Cursor bundle id>

so clicks land in Cursor.- For fully persistent banners that stay on screen until you dismiss them: System Settings → Notifications → Script Editor (or Terminal Notifier, if you installed it) → set Notification style to Alerts instead of Banners. Alternatively keep banners and flipterminalSessions.waitingAlertStyle

to"alert"

so waiting events come through as a modal dialog (persistent and click-to-focus, macOS-only).

Linux

libnotify

— required for any native notification at all:sudo apt install libnotify-bin

(Debian/Ubuntu) orsudo dnf install libnotify

(RHEL/Fedora). Without it, the extension falls back to VS Code toasts (in-editor popups, auto-dismissing).zenity

(optional) — enables the persistent modal dialog for waiting alerts (waitingAlertStyle: "alert"

). Without it, thealert

style silently falls back to a stickynotify-send -u critical

banner. Install withsudo apt install zenity

orsudo dnf install zenity

.

Node.js 20+

Platform	Package	Without it	With it
macOS	terminal-notifier
Notifications appear but clicking them opens Script Editor	Notifications appear and clicks focus Cursor
macOS	Notification style = Alerts (System Settings)	Banners auto-dismiss in 5s	Banners stay until dismissed, have Show button
Linux	libnotify-bin
Notifications fall back to VS Code toasts	Native desktop notifications via notify-send
Linux	zenity
waitingAlertStyle: "alert" falls back to sticky banner
Real modal dialog with Show terminal button

cursor --install-extension terminal-sessions-0.20.14.vsix --force

Or in Cursor: Extensions panel → ⋯

→ Install from VSIX...

cd path/to/terminal-sessions
npm install
npm run compile
npm install
npm run package   # produces terminal-sessions-<ver>.vsix

The extension runs on the workspace side (remote when connected over SSH, local otherwise). Install it on both so the right copy picks up per window.

• Install tmux on the remote server
• In a Remote-SSH window: Cmd+Shift+P → "Extensions: Install from VSIX..." → pick your local .vsix

. Cursor uploads and installs on the remote automatically - Reload the remote window. Sidebar and commands operate against the remote tmux

• In a WSL-Remote window, open a workspace under \\wsl$\...

• Install tmux in WSL: sudo apt install tmux

• Install the extension in the WSL-Remote extension host (same VSIX flow as above)

• Reload

• Install tmux on the target machine

• Install the extension and reload Cursor (full quit + reopen if you see stale state)

• Run Terminal Sessions: Set as Default Terminal Profile

so every+

button creates a tmux-wrapped terminal - Find the Terminal Sessions section under the Explorer (or drag it out to its own Activity Bar icon / the panel — VS Code remembers where you put it) - Optional: run Terminal Sessions: Install AI Agent Hooks

to enable live agent state + notifications for Claude, Codex, and Antigravity

Command	What it does
Terminal Sessions: New Persistent Terminal
Creates a new tmux-wrapped terminal for the current workspace
Terminal Sessions: Attach to Session...
Quick-pick across all sessions (any workspace)
Terminal Sessions: Resume All For Workspace
Open terminals for every detached session of the current project
Terminal Sessions: Reveal Sidebar
Focus the sidebar tree view
Terminal Sessions: Kill Session
Pick a session to kill
Terminal Sessions: Kill All Sessions for This Workspace
Clean up this project
Terminal Sessions: Kill All Stale Sessions
Prune sessions older than pruneAfterDays
Terminal Sessions: Find Session by Prompt...
Fuzzy picker over every Claude transcript on your machine
Terminal Sessions: Set as Default Terminal Profile
Write the VS Code setting so + auto-wraps
Terminal Sessions: Open tmux.conf
Edit ~/.terminal-sessions/tmux.conf
Terminal Sessions: Reload tmux Config
Apply config changes to running sessions
Terminal Sessions: Install AI Agent Hooks
Writes lifecycle hooks for each enabled agent into its own settings file (Claude ~/.claude/settings.json , Codex ~/.codex/hooks.json , Antigravity ~/.gemini/antigravity-cli/settings.json )
Terminal Sessions: Uninstall AI Agent Hooks
Removes the hooks for all agents
Terminal Sessions: Resume Session from Archive...
Picker over every past conversation on disk (Claude/Codex/Antigravity); resume, view, or name any of them
Terminal Sessions: Resume Other Session...
Resume a different past conversation into the current session (cross-agent)
Terminal Sessions: Change Sidebar Filter
Show all / running-only / stopped-only sessions
Terminal Sessions: Fix Claude Code Rendering in Shell
Appends CLAUDE_CODE_NO_FLICKER=1 and CLAUDE_CODE_DISABLE_MOUSE_CLICKS=1 to your rc file (optional — v0.11 bakes these into tmux.conf so most users won't need this)
Terminal Sessions: Toggle Claude Waiting Alerts (Global)
Flip the notifyOnClaudeWaiting setting
Terminal Sessions: Recreate Sessions from Index
After a reboot, rebuild tmux sessions from the stored index
Right-click on sidebar session → Restart
Kill + fresh shell; auto-resume the agent if detected
Right-click on sidebar session → View Conversation
Render the session's transcript as Markdown (reads the .jsonl directly — works on stopped sessions too)
Right-click on sidebar session → Name Conversation...
Give the session a friendly name (shown in the archive picker)
Right-click on sidebar session → Stop / Start
/respawn the tmux session while keeping the sidebar row
Right-click on sidebar session → Copy Last Conversation ID / Copy Last Conversation Path
Clipboard the agent conversation's UUID or the full path to its transcript .jsonl
Right-click on sidebar session → Reveal Session Folder
Open the session's working directory in Finder/Explorer
Right-click on workspace/group → New Group… / Move to Group…
Organize sessions into (master) groups
Sidebar overflow ⋯ → Clean Up Empty / Invalid Sessions...
Soft-delete empty/invalid conversations to ~/.claude/projects/.bak
Right-click on sidebar session → Rename
Set a friendly label
Right-click on sidebar session → Change Icon / Change Color
Pick custom icon or theme color
Right-click on sidebar session → Mute Notifications / Unmute Notifications
Per-session silencing
Right-click on sidebar session → Lock (Protect from Kill) / Unlock (Allow Kill)
Protect a session from Kill (padlock takes the Kill slot); Unlock to allow killing again
Right-click on sidebar session → Kill
Terminate that session (hidden while the session is locked)
Right-click on folder in Explorer → Open in Integrated Terminal - Persistent
New tmux session rooted at that folder

Key	Action
Ctrl+A q
Menu: copy mode, paste, splits, zoom, rename, kill, respawn, reload config
Ctrl+A Ctrl+A
Send a literal Ctrl+A (for shell "beginning of line")
Mouse drag-select	Copy to clipboard, stay in copy-mode
Mouse wheel in pane	Enter copy-mode, scroll 1 line/tick
q or Esc or Enter
Exit copy-mode
Right-click	Cursor context menu (Copy/Paste/Kill Terminal/etc.)

Setting	Default	Description
terminalSessions.tmuxPath
""
Absolute path to tmux binary. Empty = autodetect from PATH and common locations
terminalSessions.sessionPrefix
"ts"
Prefix for session names, e.g. ts-a3f2c71d-1
terminalSessions.enabledAgents
[] (auto-detect)
Which AI CLIs to track. Empty = Claude always on, Codex/Antigravity on when found on PATH. Override e.g. ["claude","codex"]
terminalSessions.autoRestore
"ask"
On workspace open: auto , ask , or off
terminalSessions.autoRestoreMaxAgeHours
72
Skip auto-restore for sessions older than this
terminalSessions.pruneAfterDays
14
Offer to prune sessions idle longer than this (0 to disable)
terminalSessions.sidebarSortMode
"created"
custom , mru , created , or alphabetical
terminalSessions.sidebarFilterMode
"all"
Filter sidebar by state: all , running , or stopped
terminalSessions.claudeSidebarDetails
"auto"
Expand the nested rows under a Claude session: auto /always /collapsed /off
terminalSessions.claudeNoFlicker
"auto"
CLAUDE_CODE_NO_FLICKER mode. auto = off on Cursor (conversation copyable), on in VS Code (clean alt-screen). on = always clean, no copy from live view. off = always copyable, slight flicker
terminalSessions.contextWarnPct
0.8
Threshold (0-1) for the ⚠ 87% ctx warning next to Claude state
terminalSessions.nativeNotifications
"auto"
auto (native when Cursor unfocused), always , never
terminalSessions.notificationSound
"Glass"
macOS sound for Claude Stop notifications
terminalSessions.notificationSoundWaiting
"Sosumi"
macOS sound for Claude Waiting notifications (distinct from Stop)
terminalSessions.notifyOnClaudeStop
true
Send a notification when Claude finishes a response
terminalSessions.notifyOnClaudeWaiting
true
Send a notification when Claude blocks for user permission
terminalSessions.waitingAlertStyle
"banner"
banner (auto-dismiss) or alert (persistent modal dialog with Show button)
terminalSessions.claudeStopMinDurationSeconds
15
Skip Stop notifications for turns shorter than this
terminalSessions.autoResumeClaude
false
After recreating sessions post-reboot, auto-run claude --resume
terminalSessions.enableLongRunNotifications
true
Notify when a command takes >N seconds
terminalSessions.longRunThresholdSeconds
30
Threshold for long-run notifications

{prefix}-{8-char SHA-256 hash of workspace path}-{tab number}

Example: ts-a3f2c71d-1

is the first persistent terminal opened in whatever workspace hashes to a3f2c71d

. The index at ~/.terminal-sessions/index.json

maps hashes to human-readable paths and labels.

Git worktrees automatically get separate namespaces (different absolute paths → different hashes).

Plain tmux under the hood:

tmux ls                         # list all sessions on the default socket
tmux attach -t ts-a3f2c71d-1    # attach from any system terminal
tmux kill-session -t ts-...     # kill from CLI if extension won't

Claude Code's TUI writes full-frame redraws into the main terminal buffer on every state change, which tmux faithfully captures, producing scrambled scrollback, duplicate prompts, and corruption after detach/reattach or during heavy subagent use. This is a Claude-Code-side issue (Ink/React renderer), not tmux. See anthropics/claude-code#29937

, #41814

, #46981

.

The managed ~/.terminal-sessions/tmux.conf

now emits

set-environment -g CLAUDE_CODE_NO_FLICKER 1
set-environment -g CLAUDE_CODE_DISABLE_MOUSE_CLICKS 1

so every new tmux window inherits these at startup. No shell rc edit needed. The extension auto-prompts to regenerate older configs on upgrade.

— Claude Code renders into the alternate screen buffer (likeCLAUDE_CODE_NO_FLICKER=1

vim

,less

,htop

). tmux no longer captures each intermediate frame, so scrollback stays clean across detach/reattach and parallel subagents— clicks are handed to tmux (so you can still click-select panes, tabs, the sidebar, etc.) but scroll events still reach Claude Code. Trackpad scrolls Claude's conversation view directly.CLAUDE_CODE_DISABLE_MOUSE_CLICKS=1

DISABLE_MOUSE=1

alone would block trackpad scroll

Requires Claude Code ≥ 2.1.110 (earlier versions had a regression that wiped scrollback).

Default is editor-aware ( terminalSessions.claudeNoFlicker: auto): on

Cursor, NO_FLICKER is

off by default — Claude uses the classic renderer so the conversation lands in tmux scrollback and copies cleanly via pbcopy/xclip (Cursor mis-decodes Claude's own OSC 52 copy, so this is the only way to copy accented text). On

VS Code it stays

on(clean alt-screen; VS Code copies OSC 52 fine, so nothing is lost). Force it either way with

on

(always clean, but no copy from the live Claude view) or off

(always copyable, at the cost of a little flicker on heavy redraws). Changing it regenerates and reloads tmux.conf; restart the Claude session to apply.If you started Claude in a session before the v3 config was applied, the env vars aren't in that shell yet. Either run Restart Session

on the sidebar (auto-resumes the conversation) or exec bash

/ exec zsh

inside the pane to pick them up.

From plain shell output (git, build logs, bash): drag-select with the trackpad as usual. Selection copies to the system clipboard via OSC 52From the Claude conversation: pressCtrl+O

then[

inside Claude. That dumps the current conversation view into the main tmux scrollback. From there, drag-select normally. PressCtrl+O

then/

for Claude's own in-view searchCmd+F / tmux copy-mode search only sees content in the main buffer. The live Claude view lives in alt-screen, so it is not searchable that way — useCtrl+O

/

inside Claude insteadOver Remote-SSH: an agent's own copy (Claude/Codex "copied to clipboard") reaches yourlocal machine's clipboard with correct UTF-8, accents included. A headless remote has no clipboard tool (xclip

/pbcopy

fail) and Cursor's terminal mis-decodes OSC 52 for non-ASCII, so the extension installs a tiny writer on the remote and bridges what it captures to the local clipboard through the VS Code API. No setup on the remote

See CHANGELOG.md.

MIT

source & further reading

github.com — original article