session-explorer

session-explorer

A Claude Code plugin that turns ~/.claude/projects/*.jsonl transcripts into a file-explorer-style listing: browse, organize, and resume sessions from a single slash command.

The Textual TUI gives you arrow navigation, expand/collapse, rename, move, delete, notes, a preview pane, live filter, and a live indicator showing which sessions are running right now. The text-mode list subcommand remains for scripting.

See SPEC.md for the full design.

What it looks like

Sessions are grouped by project, then by the /-separated folders encoded in their names. Stat columns show age, approximate context size, the share of the context window used, and message count.

Press Space for a preview pane with the full name, project, branch, notes, first prompt, and transcript path:

Press h for the built-in help (it also auto-opens on first launch):

Side by side with your session

When tmux is available, resuming doesn't take over the terminal. The explorer stays in the left pane and the session you resume docks in a pane on the right, so you watch the tree and the running session at once. F9 flips focus between the two panes (or click either one), F12 zooms the focused pane fullscreen, and the tmux status line keeps those hints visible even when a pane is zoomed. Selecting a different session swaps it in; the others keep running off-screen. Press c to start a brand-new session, which docks the same way.

Without tmux, resume instead hands the whole terminal straight to claude.

Live sessions

Sessions running right now are flagged in the left column — an animated green spinner for a session actively working, a dim ○ for one that's open but idle — and the subtitle shows ● N active. Live rows refresh from their transcript about every 2 seconds, so the first prompt, message count, tokens, and context % fill in and tick up as the agent works. Live sessions appear even when unnamed.

Screenshots use sample data.

Install

This GitHub repo is the plugin marketplace — there's no separate packaging or publishing step. Installing and distributing are the same two commands.

Option A — Claude Code marketplace (recommended; also how you share it)

Run these inside Claude Code:

/plugin marketplace add johan-lindahl/session-explorer
/plugin install session-explorer@session-explorer

session-explorer@session-explorer is <plugin-name>@<marketplace-name>; both happen to be session-explorer here.

Distributing to colleagues: the repo is public, so just send them those two lines — no access grants needed. When you push a new version, they update with:

/plugin marketplace update session-explorer
/plugin install session-explorer@session-explorer

Option B — plain shell installer (local development)

git clone https://github.com/johan-lindahl/session-explorer.git
cd session-explorer
./install.sh

Both paths register session-explorer's lifecycle hooks (session indexing plus the live-session indicator). Neither touches your Claude Code settings: managing session retention (which changes cleanupPeriodDays) is opt-in — the explorer asks the first time you open it. See Cleanup & retention.

Platform note: /session-explorer:open opens the TUI in a new terminal window — macOS (Terminal.app) and Linux (your $TERMINAL or a known emulator) are supported directly. On Windows, use WSL: the plugin runs as a Linux app there, and the launcher opens a Windows Terminal window back into your distro when wt.exe is available. If no launcher is found on any platform, the command to run is printed so you can paste it into a terminal yourself. Native (non-WSL) Windows is not supported.

Add to your Dock (macOS)

Once installed (either path above), create a clickable Dock launcher:

session-explorer install-app

This builds ~/Applications/Session Explorer.app with the explorer icon and pins it to your Dock. Clicking it opens the explorer in a new Terminal window — with tmux, the same as /session-explorer:open. If automatic pinning doesn't take, drag the app from ~/Applications onto your Dock yourself.

To remove it later, run the uninstall (it removes the app and unpins it):

session-explorer uninstall

Usage

After install, start any new Claude Code session in any project. The hook records the session into ~/.claude/session-explorer-index.json automatically.

From inside Claude: