All pages

Docs · Right-sidebar surfaces

Claude Code sessions

Availability: macOS. Session restore is the macOS app's — see Platforms.

A pane that was running Claude Code comes back running the same conversation after a restart or a crash, instead of a bare shell in the right folder.

Claude Code already keeps every conversation on disk, at ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl, and claude --resume <id> reopens one. What was missing was the link between a pane and its session id. TRMNLY records that link and keeps it in the session snapshot next to the pane's working directory, so restore can offer the right conversation in the right pane — including when several panes share one directory.

Setting it up

Settings → AI Agent → Claude Code sessions.

The Install hook button adds a SessionStart hook to ~/.claude/settings.json. That hook is what tells TRMNLY which session a pane is holding; without it the feature falls back to a guess (below). The install is a merge — an existing Stop hook, such as the queue-drain one in Queue, and every other key in the file are left alone — and running it twice changes nothing. If the file isn't valid JSON, TRMNLY says so and writes nothing rather than replacing configuration you may still want.

To install it by hand instead, expand Install it by hand and paste the snippet.

What a restored pane does

Setting After you quit After a crash
Don't remember sessions nothing nothing
Type the resume command types it types it
Type it — but run it after a crash (default) types it runs it
Always run it runs it runs it

"Types it" means the command is put on the pane's prompt without a Return: press Return to resume, or edit the line, or clear it and do something else.

The default splits the two cases on purpose. Quitting is a decision to stop, and typing into your shell on next launch would be presumptuous. A crash is not a decision, and what you want afterwards is to be back where you were.

This applies to all three ways a window comes back: Restore Previous Session, the automatic restore after a crash, and macOS reopening windows at login.

What was on the screen

A restored pane comes back with its output still on it, not as an empty terminal above a resume command.

Each pane keeps the last 256 KB of what its program wrote — raw pty bytes, escape sequences included, so colours, cursor position and a half-drawn TUI replay exactly as they were rather than as flattened text. The files live in ~/Library/Application Support/TRMNLY/scrollback/<surface-uuid>.vt, under Application Support rather than a scratch directory, because scratch directories are wiped on reboot and a reboot is the restart this exists for.

Three things follow from it being a tail:

  • Scrollback past those 256 KB is not restored. It is roughly a screenful of a busy TUI's repaints, or a few thousand lines of ordinary output. History older than that is gone on restart; if you need it, tee it to a file.
  • A pane you closed deliberately drops its file. Closing is a decision, and a pane reopened later should not come back full of the session you ended.
  • A pane that never returns is cleaned up after 14 days, so the directory doesn't grow one file per pane you ever opened.

Without the hook

If the hook isn't installed, TRMNLY doesn't know the session id — but it does know, from the snapshot, whether a pane's foreground process was claude. Such a pane is restored with claude -c (continue the most recent conversation in this directory) typed on its prompt.

Two limits, both deliberate:

  • It is never run for you, under any setting. It's a guess about which conversation you meant.
  • If two panes shared a directory, neither gets it. claude -c resolves to the same transcript for both, so restoring both panes would hand two agents one conversation and lose the other. Install the hook and both come back correctly.

When it doesn't work

  • The session file is gone — ~/.claude cleared, or the project folder moved. The command is still typed; running it fails with Claude Code's own message, in the pane where you can see it.
  • claude isn't on your PATH — the typed line fails as command not found.
  • The hook isn't firing. Check Settings for the installed marker, and trmnly identify inside the pane to confirm $TRMNLY_SURFACE_ID is set. The hook exits silently when it runs outside a TRMNLY pane, which is deliberate: it fires on every Claude Code start anywhere on the machine, and printing errors into an unrelated terminal would be worse than doing nothing.
  • Inside tmux. Every shell in a tmux session inherits the environment of whichever pane started tmux, so $TRMNLY_SURFACE_ID there can name a pane you left long ago. trmnly doesn't trust it: it asks tmux which client is attached and uses the pane that client is running in. trmnly identify shows the pane it settled on. With the session detached, or attached from outside TRMNLY, there is no pane and nothing is recorded. A hook installed before 0.1.89 only runs when $TRMNLY_SURFACE_ID is set, so a tmux server started outside TRMNLY is skipped; the current command is under Settings → AI Agent → Claude Code sessions.

For agents

surface_set_claude_session records the link, taking session_id (a UUID) and an optional cwd. The SessionStart hook calls it through trmnly claude-session --stdin, which reads Claude Code's hook payload and targets the pane from $TRMNLY_SURFACE_ID. You rarely need to call it directly — the hook covers the normal path — but it is there if you are launching Claude Code in a way the hook can't see.

Session ids must be UUIDs. Anything else is refused rather than stored, because the value ends up on a command line.

To read what was said in a Claude Code session — more than the screen read_terminal sees — list_claude_code_sessions lists the transcripts on disk for a folder (the focused pane's by default), newest first with each one's opening prompt, and read_claude_code_session returns its turns (the last 20 by default; head for the first ones). Tool calls and thinking are left out unless you ask for them.