find-session

Search and resume coding sessions across AI agents — Claude Code, Codex, and OpenCode — from a single command.

Sessions from all agents are merged into one table sorted by time, with keyword search (AND logic), project filtering, and an interactive selection UI for resuming, inspecting, or exporting sessions.

Install

pip install find-session

or with uv:

uv tool install find-session

Example

Searching across all agents and projects:

$ find-session "auth" -g -n 5

                            Sessions matching: auth
╭───┬────────┬────────────┬──────────┬────────┬─────────────┬───────┬──────────────────────────────────╮
│ # │ Agent  │ Session ID │ Project  │ Branch │ Date        │ Lines │ Last User Message                │
├───┼────────┼────────────┼──────────┼────────┼─────────────┼───────┼──────────────────────────────────┤
│ 1 │ Claude │ a28d83f8…  │ myapp    │ main   │ 02/21 16:01 │   174 │ Can you add OAuth2 support to    │
│   │        │            │          │        │             │       │ the login flow?                  │
│ 2 │ OC     │ ses_37f6…  │ myapp    │ N/A    │ 02/21 15:48 │   216 │ refactor the auth middleware to  │
│   │        │            │          │        │             │       │ use JWT tokens instead           │
│ 3 │ Claude │ 0585e460…  │ backend  │ feat   │ 02/20 11:30 │  3179 │ debug the session expiry bug     │
│ 4 │ Codex  │ 0199bfc9…  │ myapp    │ main   │ 02/19 09:15 │    42 │ add rate limiting to auth        │
│   │        │            │          │        │             │       │ endpoints                        │
│ 5 │ OC     │ ses_3c18…  │ backend  │ N/A    │ 02/18 20:25 │   235 │ write tests for the new auth     │
│   │        │            │          │        │             │       │ module                           │
╰───┴────────┴────────────┴──────────┴────────┴─────────────┴───────┴──────────────────────────────────╯

Select a session:
  • Enter number (1-5) to select
  • Press Enter to cancel

After selecting a session, you get an action menu:

=== Session: a28d83f8... ===
Agent: Claude
Project: myapp

What would you like to do?
1. Resume session (default)
2. Show session file path
3. Copy session file to file (*.jsonl) or directory

Usage

find-session [keywords] [OPTIONS]

Examples

# Search current project across all agents
find-session "error,TypeError"

# Browse all sessions globally
find-session -g

# Search only Claude and OpenCode sessions
find-session "refactor" --agents claude opencode

# Use with shell wrapper for persistent directory changes
fs() { eval $(find-session --shell "$@"); }
fs "keyword" -g

Standalone commands

Each agent also has a dedicated command:

find-claude-session "keywords"       # Claude Code only
find-codex-session "keywords"        # Codex only
find-opencode-session "keywords"     # OpenCode only

Supported agents

Configuration

Optionally create ~/.config/find-session/config.json to customise agent display names, set custom home directories, or disable agents:

{
  "agents": [
    { "name": "claude", "display_name": "Claude", "enabled": true },
    { "name": "codex", "display_name": "Codex", "enabled": false },
    { "name": "opencode", "display_name": "OC", "enabled": true }
  ]
}

Origin

This project grew out of session-finding utilities in claude-code-tools, extracted into a standalone package to make it easy to install and maintain independently.

License

MIT