ccgrep

A grep for Claude Code and Codex conversation history, meant for agents and humans.

Pure Python with zero dependencies.

Install

uv tool install ccgrep      # install globally with uv
uvx ccgrep                  # or run without installing

pip install ccgrep           # install using pip
pipx install ccgrep          # or pipx

Usage

Project is auto-detected from CWD.

• Use -a/--all to disable CWD auto-detection and search all projects.
• Use -p/--project NAME to filter to a project substring.
• If both are provided, explicit -p wins (-a only disables auto-detect).

Source selection

ccgrep searches Claude Code and Codex history. When no flags are given, it auto-detects which source to search based on active sessions and project context:

• --source claude or --source codex — restrict to a single source (repeatable).
• --all-sources — always search both sources.
• No flag — auto-selects: if one source has an active session, uses that; otherwise searches all sources with matching history.

When searching multiple sources, search -l, search --oneline, and search -c include a source column to disambiguate results.

CLI behavior

• Global flags are accepted before or after subcommands (-a, -p/--project, --source, --all-sources, --current, --pager, --no-header).
• Explicit -p/--project always takes precedence over -a/--all.
• Running ccgrep with no subcommand prints help and exits with status code 2.
• Scope hints are shown for human TTY output and are suppressed for piped/machine-oriented output.
• For human TTY output, list/search/dump apply a safety soft-limit by default (-n/--limit overrides it).

Search

ccgrep search 'auth'                  # regex search in current project
ccgrep search -i 'todo|fixme'         # case-insensitive
ccgrep search -t user 'deploy'        # only user messages
ccgrep search --full 'auth'           # include tools/thinking in TTY output
ccgrep search -c 'error'              # count matches per session
ccgrep search --count-sessions 'auth' # number of sessions with matches
ccgrep search -l 'auth'               # session IDs only (pipe-friendly)
ccgrep search -l 'auth' | ccgrep dump -  # dump matching sessions
ccgrep search 'auth' -p my-repo       # project filter (after subcommand works too)
ccgrep search -j 'pattern' | jq .     # JSON output for scripting
ccgrep search --oneline 'pattern'     # compact one-line-per-match output
ccgrep search --source codex 'pattern'  # search only Codex history

Notes:

• search accepts a single positional pattern (use regex alternation like foo|bar when needed).
• On TTY output, search defaults to conversation view (user + assistant) unless type/tool filters are set.

List projects

ccgrep projects                       # list all projects; metadata on TTY, flat list when piped
ccgrep projects -j                    # JSON with short name, raw name, session count, last active

List sessions

ccgrep list                           # current project
ccgrep -a list                        # all projects
ccgrep list --project my-repo         # project filter
ccgrep list -n 50                     # cap output to 50 sessions
ccgrep list --after 2025-01-01        # date filter
ccgrep list --all-sources             # list sessions from all sources

Dump

ccgrep dump                           # dump all matching sessions
ccgrep dump abc123                    # dump session by ID prefix
ccgrep dump abc123 -n 50              # first 50 records
ccgrep dump abc123 --full             # include tools/thinking in TTY output
ccgrep dump abc123 --from-time 14:50  # from 14:50 UTC onward
ccgrep dump -x thinking -x progress   # skip noise
ccgrep dump -j -t tool_result         # tool results as JSON lines

Notes:

• --full has compatibility alias --all-records.

Tail

ccgrep tail                           # show last 20 records from latest session
ccgrep tail abc123                    # show last 20 records from a specific session
ccgrep tail -f                        # follow the latest session
ccgrep tail -f abc123                 # follow a specific session
ccgrep tail -x thinking -x progress   # skip noise
ccgrep tail -j                        # JSON output for piping

Stats

ccgrep stats                          # stats for all sessions in current project
ccgrep stats -s abc123                # stats for a specific session
ccgrep stats -j                       # JSON output

For agents

Consider adding the following to your project's CLAUDE.md and/or AGENTS.md:

## Conversation history

`ccgrep` is available in PATH for searching past Claude Code and Codex conversations. Use it to recover context after conversation compaction, find prior decisions, or continue work from previous sessions.

```
ccgrep list                               # list recent sessions (current project scope)
ccgrep -a list                            # list all projects
ccgrep search 'pattern'                   # search current project
ccgrep search -s <session-id> 'pattern'   # search one session
ccgrep search -t user 'pattern'           # user messages only
ccgrep search --count-sessions 'pattern'  # number of sessions with matches
ccgrep search -l 'pattern' | ccgrep dump -  # dump matching sessions
ccgrep dump <session-id> -n 50            # dump a specific session
ccgrep dump --conversation <session-id>   # user+assistant only
ccgrep stats -s <session-id>              # message/tool breakdown for a session
ccgrep tail <session-id> -n 50            # last 50 records from a session
ccgrep tail -f <session-id>               # follow new records live
ccgrep search -j 'pattern' | jq .         # JSON output for scripting
ccgrep tail --full -n 50                  # include tools/thinking in TTY output
ccgrep --source codex search 'pattern'    # search only Codex history
ccgrep --all-sources search 'pattern'     # search both Claude and Codex
```

### Searching the current conversation

Pass `--current` to scope any command to the conversation you are currently in:

```
ccgrep --current search 'pattern'         # search this conversation only
ccgrep --current dump --conversation      # dump this conversation (user+assistant)
ccgrep --current stats                    # stats for this conversation
```

`--current` works by scanning the tail of recently-written JSONL files for a `Bash` tool_call containing `ccgrep --current`, which Claude Code writes to the session file just before executing the command. **This only works when called as a Bash tool from within a Claude Code session** — running `ccgrep --current` directly in a terminal will always fail because no such tool_call record exists.

License

Apache-2.0