sessions

Search and memory across your AI coding sessions.
One index over Claude Code, Codex, and Pi — fuzzy-find and resume past sessions from the CLI, give agents recall over prior work via MCP, and see where your tokens go.

Why

Every AI coding session leaves a transcript behind. Claude Code buries them in ~/.claude/projects/, Codex and Pi have their own layouts — and everything in them (what you tried, what you decided, what broke) is effectively write-only.

sessions builds a full-text search index over all of it and makes that history useful in three ways:

• Search & resume (CLI) — fuzzy-find any past session across all three tools, ranked by relevance, and jump back in.
• Agent memory (MCP) — agents search your history, pull a repo-scoped context primer when you return to a codebase, and answer "what did I do last week?" via bundled skills.
• Usage reports — a token/cost dashboard across tools, models, and projects.

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.

Quick Setup

After installing, run:

sessions setup

This automatically:

1. Copies the plugin and skills to ~/.local/share/sessions/plugin/
2. Detects which AI tools you have installed (Claude Code, Cursor, Codex)
3. Adds the MCP server config to each tool
4. 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

  Skills available:
    /context           Context primer for the current repo
    /weekly-summary    Summarize your past week's AI sessions
    /standup           Yesterday + today activity for standups
    /recall            What did I do on a specific project?
    /session-metrics   Usage dashboard with tool breakdown

  Run `sessions setup` again after upgrading to update skills.

After upgrading sessions (e.g., brew upgrade sessions), run sessions setup again to update the skills to the latest version.

To remove everything: sessions uninstall

CLI: search & resume

sessions                     # Browse all sessions with fzf
sessions <query>             # Full-text search across session content
sessions --here              # Scope to current git repo only
sessions --tool claude       # Filter to Claude Code sessions only
sessions --errored           # Only sessions that hit an error
sessions context             # Print a context primer for the current repo
sessions report              # Usage report (HTML dashboard, opens in browser)

Options

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 run a full-text search across all sessions:

sessions "rate limit"

The CLI uses the same search index as the MCP server: results are ranked by relevance (BM25) rather than recency, matching uses porter stemming (refactor matches refactoring), and multi-word queries match sessions containing any of the terms with the closest matches first. Search covers both your messages and the assistant's replies; system-injected content (<system-reminder>, etc.) is stripped from your messages so you only match what you actually typed. Matching sessions are shown with a snippet of context, then piped into fzf.

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).

Agent memory

sessions includes an MCP server that gives AI agents searchable access to your past conversations — across every tool, not just the one they're running in. sessions setup configures it automatically; for manual setup, add to your MCP configuration (e.g., ~/.claude/.mcp.json):

{
  "mcpServers": {
    "sessions": {
      "command": "sessions",
      "args": ["--mcp"]
    }
  }
}

MCP tools

The MCP server exposes five tools:

The get_activity_digest tool supports a detail parameter: "compact" (default) returns topics and file paths only, "highlights" adds first and last user messages for substantive sessions (best for summaries), and "full" includes all user messages per session.

Skills

The plugin ships five skills that compose the MCP tools into repeatable workflows:

Skills work with Claude Code, Cursor, Codex, and any agent that supports the skills.sh format.

Context primer

When you return to a codebase, the primer answers "where did I leave off?" — recent sessions in detail, older ones as headlines, including the branch you were on and the last exchange of each session. It's available three ways:

• On demand from an agent — the /context skill or the get_context_primer MCP tool
• On demand from the shell — sessions context prints it as markdown (--full widens detail; --limit/--days/--tool filter; --worktree narrows to the current worktree; --out <path> writes to a file)
• Automatically at session start — opt-in, below

Auto-injecting context at session start (opt-in)

You can have a small primer injected automatically at the start of every Claude Code session via a SessionStart hook:

sessions setup --hooks    # enable auto-injection (Claude Code)

Run without --hooks and setup will ask interactively (when on a TTY); it is off by default because it costs a small number of tokens on every session. The hook runs sessions context --hook — a tiny primer (the 3 most recent sessions for the current repo). In a fresh repo with no history, or outside a git repo, it injects nothing and never blocks session start.

To turn it off, run sessions uninstall (which also removes the plugin and MCP config). The hook lives in ~/.claude/settings.json under hooks.SessionStart; enabling and disabling preserve any other hooks you have configured.

Codex and Cursor are not yet supported — their session-start hook contracts are still being confirmed. The hook also requires sessions to be on your PATH at session start.

Usage reports

sessions report does a fresh pass over your local Claude Code, Codex, and Pi logs and produces a token/cost usage report. By default it renders a self-contained HTML dashboard and opens it in your browser; JSON output is available for piping.

sessions report                              # HTML dashboard, opens in your browser
sessions report --out ./report.html          # save the dashboard instead of opening it
sessions report --format json --stdout       # print JSON to stdout (for piping)
sessions report --days 30 --tool claude      # last 30 days, Claude Code only
sessions report --this-month                 # current month to date
sessions report --month 2026-05              # a specific calendar month
sessions report --here                       # current project only

The selected period is shown prominently at the top of both outputs (and in the JSON period).

Report options

What's in the report

Both outputs are built from the same data:

• Summary — total cost, tokens, sessions, messages, active days, current/longest streak, peak hour, and most-used model.
• Breakdowns — by tool, provider, model, and project.
• Daily series — per-day tokens/cost/sessions/messages with an hourly histogram.
• Insights — a weekly trend plus hour-of-day and weekday activity profiles.

The JSON is a sessions-owned UsageReport ({ "generator": "sessions", "version": 1, ... }). The HTML is fully self-contained (inline SVG charts, no external assets) and adapts to light/dark.

Cost is estimated from LiteLLM pricing data, fetched at most once per day and cached locally, with an embedded snapshot as the offline fallback — a failed fetch never blocks the report. Pi sessions use the cost recorded in their own logs. Tokens for unknown models are still counted, with cost shown as $0. Token totals exclude cache reads (replayed context, mostly free reuse).

How it works

Session discovery

sessions reads JSONL session files from these locations:

Each session file is parsed to extract:

• Working directory — read from the session metadata to determine which project the session belongs to
• First user prompt — the initial message you sent, cleaned of system-injected tags
• Custom title — if the session was renamed in Claude Code, that title is used instead
• Message count — total user + assistant messages in the session
• Timestamps — first and last timestamps for session duration and date-range queries
• Subagent content — for Claude Code, user messages from subagent sidecar files are folded into the search index

Search index

Both the CLI and the MCP server share a SQLite + FTS5 index at ~/.cache/sessions/index.db. The index is built automatically on first use (~5s for thousands of sessions) and updated incrementally on subsequent runs by checking file modification times — only new or changed sessions are re-indexed.

To clear the index and force a full rebuild:

sessions --clear-cache

Scoping with --here

When --here is passed, sessions resolves the current git repo root and only shows sessions whose working directory falls under that root. This works with bare repo worktrees — if a .git file points to a .bare directory, the parent is used as the repo root.

Development

bun install                  # Install dependencies
bun run dev                  # Run directly without compiling
bun run build                # Compile to dist/sessions
bun run typecheck            # Type-check with tsc
bun run lint                 # Lint with oxlint
bun run format               # Format with oxfmt
bun run format:check         # Check formatting without writing

Cross-compilation

The release workflow compiles binaries for three platforms:

Binaries are compiled with bun build --compile --minify and distributed as .tar.gz archives attached to GitHub Releases.

Release process

Releases are automated with release-please:

1. Push commits to main using conventional commit messages
2. Release-please opens a version-bump PR with an auto-generated changelog
3. Merge the PR to trigger the release pipeline
4. Binaries are built, attached to the GitHub Release, and the Homebrew formula is auto-updated

License

MIT