sessions
Find and resume AI coding sessions.
Browse conversations from Claude Code, Codex, and Pi with fuzzy search, scoped to the current repo or across all projects.
Why
AI coding tools don't make it easy to find old sessions. Claude Code buries them in ~/.claude/projects/, Codex and Pi have their own layouts. You end up grepping JSONL files or scrolling through claude --resume hoping to spot the right one.
sessions indexes all three tools, extracts the first user prompt from each conversation, and presents them in a unified fuzzy-searchable list. Pick a session and the resume command is copied to your clipboard.
Install
Homebrew
brew install nicknisi/formulae/sessions
Or, equivalently:
brew tap nicknisi/formulae
brew install sessions
From source
git clone https://github.com/nicknisi/sessions && cd sessions
bun install && bun run build
The compiled binary is at dist/sessions. Requires Bun when building from source. The Homebrew install is a standalone binary — no runtime needed.
Dependencies
- fzf (optional but recommended) — used for fuzzy selection. If fzf is not installed, a built-in numbered list selector is used as a fallback. Install with
brew install fzf.
Usage
sessions # Browse all sessions with fzf
sessions <query> # Search session content for a phrase
sessions --here # Scope to current git repo only
sessions --tool claude # Filter to Claude Code sessions only
Options
| Flag / Command | Description |
|---|
setup | Install plugin and configure MCP for detected tools |
uninstall | Remove plugin and MCP config from all tools |
cleanup | Full reset: uninstall plugin + clear search index |
--here | Scope to the current git repo (default: all projects) |
--tool <name> | Filter by tool: claude, codex, or pi |
--mcp | Start as an MCP server (stdio transport) |
--clear-cache | Remove the search index (rebuilds on next use) |
--no-color | Disable colored output |
-h, --help | Show help |
Browsing
With no arguments, sessions scans all session directories, extracts the first user prompt from each conversation, and pipes the results into fzf for fuzzy selection:
● my-project claude today Refactor the auth middleware to use JWT
● my-project pi 2d Help me debug the flaky integration test
● api-server codex 1w Add rate limiting to the /api/v2 endpoints
○ old-project claude 2025-03 Set up the initial project structure
- ● (green) — the project directory still exists
- ○ (red) — the project directory has been deleted
Searching
Pass a query to search across user messages in all sessions:
sessions "rate limit"
This greps through session content (user messages only, ignoring system-injected blocks) and shows matching sessions with a snippet of the matching context. The search is case-insensitive.
After selection
When you pick a session, sessions displays the resume command and copies it to your clipboard:
my-project (claude)
Refactor the auth middleware to use JWT
cd /Users/you/Developer/my-project && claude --resume abc123
(copied to clipboard)
For Claude Code sessions, the command includes --resume <session-id>. For Pi and Codex sessions, it navigates to the project directory (these tools don't support direct session resume).
Quick Setup
After installing, run:
sessions setup
This automatically:
- Copies the plugin and skills to
~/.local/share/sessions/plugin/
- Detects which AI tools you have installed (Claude Code, Cursor, Codex)
- Adds the MCP server config to each tool
- Registers the plugin so skills are discoverable
❯ sessions setup
sessions setup
✓ Plugin installed to ~/.local/share/sessions/plugin/
✓ MCP server added to Claude Code
✓ Plugin registered with Claude Code
✓ MCP server added to Cursor
✓ Plugin registered with Cursor
