Metadata-Version: 2.4
Name: ccgrep
Version: 0.1.0
Summary: Search Claude Code conversation history
Keywords: claude,claude-code,history,grep,conversation
Author: 499602D2
License-Expression: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Project-URL: Repository, https://github.com/499602D2/ccgrep
Description-Content-Type: text/markdown

# ccgrep

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

Pure Python with zero dependencies.

## Install

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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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
