ccsession

ccsession

An fzf-powered session picker for resuming local agent sessions.

ccsession lists local agent sessions (Claude Code by default, with optional OpenCode, Grok, and Codex backends), lets you fuzzy-find across all of your projects with a live preview pane, and resumes the one you pick in its original working directory.

Features

• Cross-project listing — every session from every project in one view, sorted by last activity.
• Three search modes — fuzzy (default), directory-only, and full-text grep over JSONL transcripts, with configurable mode-switch keys.
• Live preview — last 30 messages of the highlighted session, with timestamps and roles. In grep mode the matched query is highlighted in the preview so you can spot the hit at a glance.
• Faithful resume — chdirs back to the session's original cwd before exec'ing the selected agent's resume command, so paths and tooling Just Work.
• Single static binary — written in Go with no cgo; bundles a pure-Go SQLite reader (for OpenCode support) and a small TOML parser for the optional config file.

Requirements

ccsession depends on newer fzf actions such as transform, rebind, unbind, disable-search, and change-nth. The newest of those, change-nth, landed in fzf 0.58.0, so older versions may start but the mode switch bindings will not work correctly.

Install

Go

go install github.com/sorafujitani/ccsession/cmd/ccsession@latest

Requires Go 1.25 or newer (the pure-Go SQLite reader for OpenCode support needs it; see #52).

Version metadata is recovered from runtime/debug.ReadBuildInfo, so ccsession --version works for go install builds as well.

Pre-built binaries

Grab the ccsession_<ver>_<os>_<arch>.tar.gz for your platform from the Releases page, extract it, and drop the binary somewhere on your PATH:

tar xzf ccsession_0.1.0_darwin_arm64.tar.gz
install -m 0755 ccsession ~/.local/bin/

If macOS Gatekeeper complains:

xattr -d com.apple.quarantine ~/.local/bin/ccsession

Nix flake

nix run github:sorafujitani/ccsession             # one-off
nix profile install github:sorafujitani/ccsession # install into a profile

Homebrew

brew install sorafujitani/tap/ccsession

The formula lives in sorafujitani/homebrew-tap and GoReleaser refreshes it on every tagged release. fzf is installed as a dependency; the claude CLI must be installed separately. opencode, grok, and codex are needed only with their matching --source backends — they back optional features (unlike fzf, which is always required), so they are intentionally left out of the formula's depends_on.

Usage

ccsession                            # list -> fzf -> resume
ccsession --grok                     # use Grok sessions from ~/.grok/sessions
ccsession --codex                    # use Codex sessions from ~/.codex/sessions
ccsession list  [--grep Q] [--regex] # emit TSV rows to stdout
ccsession preview [--query Q] [--regex] <id> # render the preview pane (Q highlighted)
ccsession resume  <id>               # chdir to the session's cwd, exec the selected agent
ccsession --version
ccsession --help

Keys inside fzf

The three mode-switch keys are the defaults and can be overridden (see below).

Configuring the keybindings

If a mode-switch key clashes with your terminal, shell, or muscle memory, you can remap any of the three. Keys are resolved in this order (first wins):

CLI flags > environment variables > config file > defaults

The on-screen header is regenerated from the resolved keys, so the hint always matches what is active.

# CLI flags (highest precedence)
ccsession --bind-grep ctrl-r --bind-fuzzy alt-f

# environment variables
export CCSESSION_BIND_GREP=ctrl-r
export CCSESSION_BIND_DIR=ctrl-o
export CCSESSION_BIND_FUZZY=alt-f

Config file at ~/.config/ccsession/config.toml (lowest precedence before defaults; honors XDG_CONFIG_HOME). ccsession only reads this file — it never creates it, so create it yourself only if you want file-based overrides:

[keybindings]
grep  = "ctrl-r"
dir   = "ctrl-o"
fuzzy = "alt-f"

Any key you leave unset falls through to the next source. A key name must be lower-case fzf syntax (ctrl-r, alt-f, f1, …); the three keys must be distinct and must not be a reserved fzf event name (enter, change, …), or ccsession exits with an error instead of starting the picker.

How it works

1. ccsession list reads the selected backend (~/.claude/projects/*/ by default, or --source=opencode / --source=grok / --source=codex) and prints one TSV row per session (id, epoch, relative time, cwd basename, label).
2. fzf consumes the TSV. The three key bindings swap fzf's matcher between fuzzy mode, directory-only mode, and grep mode (which reloads via ccsession list --grep <query> on every keystroke). The current query is also forwarded to the preview as ccsession preview --query <query> <id>, which highlights its matches in the rendered messages.
3. On Enter, ccsession resume <id> resolves the session's original cwd, chdirs into it, and execves the selected agent's resume command so the resumed process fully replaces the picker.

Backend-specific homes can be overridden with GROK_HOME for Grok and CODEX_HOME for Codex. Codex defaults to ~/.codex, reading sessions from its sessions subdirectory.

Development

nix develop                    # Go + fzf + gopls + goreleaser
go build ./cmd/ccsession
go test ./...

Snapshot a release locally

goreleaser release --snapshot --clean --skip=publish
ls dist/

Build with Nix

nix build
./result/bin/ccsession --version

Contributing

Bug reports and pull requests are welcome at https://github.com/sorafujitani/ccsession. For larger changes, please open an issue first to discuss what you'd like to change.

License

MIT