{"id":50962104,"url":"https://github.com/mgacy/cc-session-tool","last_synced_at":"2026-06-18T15:03:03.383Z","repository":{"id":350890783,"uuid":"1190943099","full_name":"mgacy/cc-session-tool","owner":"mgacy","description":"A CLI to allow agents to query Claude Code session transcripts.","archived":false,"fork":false,"pushed_at":"2026-04-25T04:55:47.000Z","size":111,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T05:27:10.859Z","etag":null,"topics":["ai-tools","claude-code","cli"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mgacy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-24T19:13:49.000Z","updated_at":"2026-04-25T04:55:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mgacy/cc-session-tool","commit_stats":null,"previous_names":["mgacy/cc-session-tool"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mgacy/cc-session-tool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgacy%2Fcc-session-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgacy%2Fcc-session-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgacy%2Fcc-session-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgacy%2Fcc-session-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mgacy","download_url":"https://codeload.github.com/mgacy/cc-session-tool/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgacy%2Fcc-session-tool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34495380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","claude-code","cli"],"created_at":"2026-06-18T15:03:02.442Z","updated_at":"2026-06-18T15:03:03.374Z","avatar_url":"https://github.com/mgacy.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cc-session-tool\n\nA CLI tool for querying Claude Code session transcripts. Reads JSONL session files from `~/.claude/projects/` and compresses raw transcripts (50-120K tokens each) into focused JSON responses — designed for use by coding agents and scripts.\n\n## Installation\n\n```bash\nbun install\n```\n\n## Usage\n\n```bash\nbun run dev \u003ccommand\u003e [session] [options]\n```\n\nOr compile to a standalone binary:\n\n```bash\nbun run build\n./cc-session-tool \u003ccommand\u003e [session] [options]\n```\n\n### Session Identifiers\n\nSession-scoped commands require a `\u003csession\u003e` argument; `list` and `projects` do not. Three forms are accepted:\n\n| Form        | Example                                | Resolution                                             |\n| ----------- | -------------------------------------- | ------------------------------------------------------ |\n| Full UUID   | `DA2738E3-0ADE-40E7-B6AC-450F9CCE1B43` | Exact filename match                                   |\n| UUID prefix | `DA2738E3`                             | Prefix match (must be unambiguous)                     |\n| Slug        | `snuggly-floating-barto`               | Search across all `.jsonl` files (must be unambiguous) |\n\nAll session commands accept `--project \u003cpath\u003e` to specify the project directory (defaults to CWD). They also accept `--claude-project \u003cproject\u003e` when you need to target a raw Claude project directory basename returned by `search`, `list`, or `projects`. `--project` and `--claude-project` are mutually exclusive.\n\nUse `--claude-project` for stable follow-up from cross-project or worktree search results:\n\n```bash\ncc-session-tool shape DA2738E3 --claude-project -workspace-app\n```\n\n**Subagent targeting:** Append `:\u003cagent-id\u003e` to a session identifier in any session-scoped command (except `subagents`) to target a subagent session (e.g., `DA2738E3:a8361bc` or `snuggly-floating-barto:a8361bc`). The parent session is resolved normally, then the subagent file is located at `\u003csession-dir\u003e/subagents/agent-\u003cagent-id\u003e.jsonl`. Use the `subagents` command to discover available agent IDs.\n\n**Input validation:** Session IDs accept `[a-zA-Z0-9-]` characters; agent IDs also allow underscores `[a-zA-Z0-9_-]`. All other inputs are rejected with exit code 2.\n\n### Turn Numbering\n\nAll commands use consistent turn numbering:\n\n- Each JSONL entry of type `user` or `assistant` gets the next sequential integer, starting at 1.\n- Other entry types (`system`, `progress`, etc.) are excluded from numbering.\n- When an assistant entry contains multiple content blocks (e.g., thinking + tool_use), they share the same turn number. The `block_index` field (0-indexed) disambiguates blocks within a turn.\n- Turn numbers are consistent across all commands: turn 5 in `shape` is the same entry as turn 5 in `tools`, `tokens`, `messages`, `slice`, and `files`.\n\n## Commands\n\n### `list`\n\nIndex sessions by reading metadata from the first few lines of each file. A scoped `list --project \u003crepo\u003e` includes the repo's associated Claude-managed worktree transcript directories by default, matching `search`; use `--main-only` to inspect only the main project transcript directory.\n\n```bash\ncc-session-tool list [--project \u003cpath\u003e] [--main-only] [--all-projects] [--project-glob \u003cpattern\u003e] [--intent-match \u003ctext\u003e|--intent-regex \u003cregex\u003e] [--branch \u003cname\u003e] [--after \u003cdate\u003e] [--before \u003cdate\u003e] [--since \u003cduration\u003e] [--last \u003cn\u003e] [--min-lines \u003cn\u003e] [--include-subagents]\n```\n\n| Option        | Default | Description                                                    |\n| ------------- | ------- | -------------------------------------------------------------- |\n| `--branch`    | all     | Filter by git branch name                                      |\n| `--all-projects` | false | List sessions from every top-level Claude project directory under `~/.claude/projects`. |\n| `--main-only` | false | With scoped `--project`, skip associated Claude worktree transcript directories. Cannot be combined with `--all-projects`. |\n| `--project-glob` | —     | With `--all-projects`, filter by raw Claude project basename or display-only `project_path_guess`. Supports `*` and `?`. |\n| `--intent-match` | —     | Filter session intent sources (`slug`, first prompt token, first user message) by case-insensitive substring. |\n| `--intent-regex` | —     | Filter session intent sources by regex. Mutually exclusive with `--intent-match`. |\n| `--after`     | —       | Sessions after ISO 8601 date (mutually exclusive with `--since`) |\n| `--before`    | —       | Sessions before ISO 8601 date                                  |\n| `--since`     | —       | Sessions from the last duration: `30m`, `2h`, `1d`, `1w` (mutually exclusive with `--after`) |\n| `--last`      | all     | Return only the N most recent sessions                         |\n| `--min-lines` | 0       | Sessions with at least N lines                                 |\n| `--include-subagents` | false | Include `subagent_count` per session                    |\n\n**Output:** Sessions sorted by timestamp (newest first). When `--include-subagents` is set, each session includes a `subagent_count` field; otherwise the field is omitted entirely. Fields may be `null` for sessions with missing metadata. When `--last` is used, `_meta.total` reflects the pre-limit count and `_meta.hasMore` is `true` if results were truncated. When multiple project contexts are included, rows include `project`, `project_path_guess`, `project_role`, and `session_ref`; `_meta.included_projects` records the selected Claude project contexts. `project_path_guess` is display-only; use raw `project` or `session_ref.project` with `--claude-project` for follow-up commands.\n\n```json\n{\n  \"ok\": true,\n  \"data\": [\n    {\n      \"session_id\": \"DA2738E3-0ADE-40E7-B6AC-450F9CCE1B43\",\n      \"branch\": \"feature/auth\",\n      \"timestamp\": \"2026-03-07T22:31:26.359Z\",\n      \"version\": \"2.1.71\",\n      \"model\": \"claude-sonnet-4-5\",\n      \"lines\": 342,\n      \"slug\": \"snuggly-floating-barto\"\n    }\n  ],\n  \"_meta\": { \"total\": 1, \"returned\": 1, \"hasMore\": false }\n}\n```\n\n---\n\n### `projects`\n\nSummarize Claude project transcript directories and expose stable raw project handles.\n\n```bash\ncc-session-tool projects [--glob \u003cpattern\u003e] [--project \u003cpath\u003e]\n```\n\nWithout `--project`, `projects` scans all top-level Claude project directories under `~/.claude/projects`. With `--project`, it returns the main project plus associated Claude worktree transcript directories. Rows are sorted by raw `project` basename.\n\n| Field | Description |\n| ----- | ----------- |\n| `project` | Raw Claude project directory basename; pass this to session commands as `--claude-project`. |\n| `project_path_guess` | Best-effort display path only. Do not use it as a stable handle. |\n| `project_role` | `main`, `worktree`, or `global`. |\n| `session_count` | Count of parent `.jsonl` sessions in that Claude project directory. |\n| `total_lines` | Total non-empty transcript lines across counted sessions. |\n| `first_session_at` / `last_session_at` | Earliest/latest metadata timestamp, or `null`. |\n\n---\n\n### `shape \u003csession\u003e`\n\nTurn-by-turn skeleton with summary stats. Compresses a full session into a table of contents.\n\n```bash\ncc-session-tool shape \u003csession\u003e [--project \u003cpath\u003e | --claude-project \u003cproject\u003e]\n```\n\n**Output:**\n\n```json\n{\n  \"ok\": true,\n  \"data\": {\n    \"session_id\": \"DA2738E3-...\",\n    \"agent_id\": null,\n    \"turns\": [\n      { \"n\": 1, \"role\": \"user\", \"type\": \"user\", \"block_index\": 0 },\n      { \"n\": 2, \"role\": \"assistant\", \"type\": \"tool_use\", \"block_index\": 0, \"tools\": [\"Grep\"] },\n      { \"n\": 3, \"role\": \"user\", \"type\": \"tool_result\", \"block_index\": 0 },\n      { \"n\": 4, \"role\": \"assistant\", \"type\": \"thinking\", \"block_index\": 0 },\n      { \"n\": 4, \"role\": \"assistant\", \"type\": \"text\", \"block_index\": 1 }\n    ],\n    \"summary\": {\n      \"total_turns\": 42,\n      \"user_messages\": 8,\n      \"tool_calls\": { \"Grep\": 12, \"Read\": 8, \"Edit\": 5, \"Bash\": 4 },\n      \"first_edit_turn\": 15,\n      \"duration_minutes\": 38.2\n    }\n  },\n  \"_meta\": { \"total\": 5, \"returned\": 5, \"hasMore\": false }\n}\n```\n\n**Turn types:**\n\n| Role        | Type          | Description                              |\n| ----------- | ------------- | ---------------------------------------- |\n| `user`      | `user`        | User text message                        |\n| `user`      | `tool_result` | Tool result returned to assistant        |\n| `user`      | `image`       | Image attachment                         |\n| `assistant` | `text`        | Assistant text response                  |\n| `assistant` | `thinking`    | Thinking/reasoning block                 |\n| `assistant` | `tool_use`    | Tool invocation (includes `tools` array) |\n\n**`block_index`:** 0-indexed position within the turn's content blocks. When an assistant turn has multiple non-tool blocks (e.g., thinking + text), each gets a separate row with incrementing `block_index`. Assistant turns with `tool_use` blocks are collapsed into a single row with `block_index: 0`.\n\n**Summary fields:**\n\n| Field              | Description                                                         |\n| ------------------ | ------------------------------------------------------------------- |\n| `total_turns`      | Count of user + assistant entries                                   |\n| `user_messages`    | Count of user entries                                               |\n| `tool_calls`       | Map of tool name to call count                                      |\n| `first_edit_turn`  | Turn of first `Edit` or `Write` call (`null` if none)               |\n| `duration_minutes` | Minutes between first and last entry (`null` if missing timestamps) |\n\n---\n\n### `summary \u003csession\u003e`\n\nOne-call triage summary for a session.\n\n```bash\ncc-session-tool summary \u003csession\u003e [--project \u003cpath\u003e | --claude-project \u003cproject\u003e]\n```\n\nThe result combines the common first-pass fields agents previously gathered from `shape`, `tools`, `files`, and `messages`: model, timing, first prompt snippet, last assistant text snippet, tool counts, file access counts, and subagent metadata. When following a `search` or `list` row, use `session_ref.project` as `--claude-project`; do not use `project_path_guess` as a handle.\n\n---\n\n### `tools \u003csession\u003e`\n\nTool call log with condensed input summaries and outcome detection.\n\n```bash\ncc-session-tool tools \u003csession\u003e [--project \u003cpath\u003e | --claude-project \u003cproject\u003e] [--name \u003ctool\u003e|--name-match \u003ctext\u003e] [--input-match \u003ctext\u003e|--input-regex \u003cregex\u003e] [--failed] [--turn \u003cN|N-M\u003e]\n```\n\n`--input-match` and `--input-regex` search the raw structured tool input, including values omitted or truncated in `input_summary`. `--name` and `--name-match` are mutually exclusive, as are the two input filters.\n\n**Output:**\n\n```json\n{\n  \"ok\": true,\n  \"data\": {\n    \"session_id\": \"DA2738E3-...\",\n    \"agent_id\": null,\n    \"tool_calls\": [\n      {\n        \"turn\": 3,\n        \"tool\": \"Grep\",\n        \"input_summary\": \"pattern='AuthReducer' path='Sources/'\",\n        \"outcome\": \"empty\",\n        \"duration_ms\": 450\n      },\n      {\n        \"turn\": 7,\n        \"tool\": \"Read\",\n        \"input_summary\": \"file='AuthReducer.swift'\",\n        \"outcome\": \"success (245 lines)\",\n        \"duration_ms\": 120\n      }\n    ]\n  },\n  \"_meta\": { \"total\": 2, \"returned\": 2, \"hasMore\": false }\n}\n```\n\n**Input summary formats:**\n\n| Tool           | Summary Format                                  |\n| -------------- | ----------------------------------------------- |\n| `Grep`         | `pattern='...' path='...'`                      |\n| `Read`         | `file='\u003cbasename\u003e' offset=N limit=N`            |\n| `Edit`         | `file='\u003cbasename\u003e' old=(N chars) new=(N chars)` |\n| `Write`        | `file='\u003cbasename\u003e' (N chars)`                   |\n| `Bash`         | First 80 chars of command                       |\n| `Glob`         | `pattern='...' path='...'`                      |\n| `Agent`/`Task` | `prompt='...'` (first 80 chars)                 |\n| `WebFetch`     | `url='...'`                                     |\n| `WebSearch`    | `query='...'`                                   |\n| Other          | First 80 chars of JSON-encoded input            |\n\n**Outcome values:**\n\n| Outcome             | Meaning                                               |\n| ------------------- | ----------------------------------------------------- |\n| `success`           | Non-empty content                                     |\n| `success (N lines)` | N lines of content                                    |\n| `empty`             | Empty content                                         |\n| `error: \u003cmessage\u003e`  | Error (first 60 chars)                                |\n| `no_result`         | No matching `tool_result` found (interrupted session) |\n\n**`duration_ms`:** Milliseconds between assistant entry and corresponding tool_result. `null` if timestamps are missing.\n\n---\n\n### `files \u003csession\u003e`\n\nFiles touched in a session, grouped by file path or chronologically by turn.\n\n```bash\ncc-session-tool files \u003csession\u003e [--project \u003cpath\u003e | --claude-project \u003cproject\u003e] [--group-by \u003cfile|turn\u003e] [--turn \u003cN|N-M\u003e] [--operation \u003cop\u003e]\n```\n\n| Option        | Default | Description                                        |\n| ------------- | ------- | -------------------------------------------------- |\n| `--group-by`  | `file`  | `file` (one entry per unique path) or `turn` (chronological) |\n| `--turn`      | all     | Turn number `N` or range `N-M`                     |\n| `--operation` | all     | Filter by operation: `read`, `edit`, `write`, `grep`, `glob` |\n\n**Output (group-by=file, default):**\n\n```json\n{\n  \"ok\": true,\n  \"data\": {\n    \"session_id\": \"DA2738E3-...\",\n    \"agent_id\": null,\n    \"group_by\": \"file\",\n    \"files\": [\n      {\n        \"path\": \"/workspace/project/src/auth.ts\",\n        \"operations\": [\"read\", \"edit\"],\n        \"turns\": [6, 8, 12, 18],\n        \"errored\": false\n      },\n      {\n        \"path\": \"/workspace/project/src/auth.test.ts\",\n        \"operations\": [\"read\", \"write\"],\n        \"turns\": [10, 22],\n        \"errored\": false\n      }\n    ]\n  },\n  \"_meta\": { \"total\": 2, \"returned\": 2, \"hasMore\": false }\n}\n```\n\n**Output (group-by=turn):**\n\n```json\n{\n  \"ok\": true,\n  \"data\": {\n    \"session_id\": \"DA2738E3-...\",\n    \"agent_id\": null,\n    \"group_by\": \"turn\",\n    \"accesses\": [\n      { \"path\": \"/workspace/project/src/auth.ts\", \"operation\": \"read\", \"turn\": 6, \"errored\": false },\n      { \"path\": \"/workspace/project/src/auth.ts\", \"operation\": \"edit\", \"turn\": 8, \"errored\": true }\n    ]\n  },\n  \"_meta\": { \"total\": 2, \"returned\": 2, \"hasMore\": false }\n}\n```\n\n**Notes:**\n\n- Extracts full file paths from tool inputs (`Read`, `Edit`, `Write` use `file_path`; `Grep`, `Glob` use `path`).\n- `Grep`/`Glob` calls without a `path` argument are excluded (they search CWD implicitly).\n- `Bash` calls are excluded — file references in shell commands are not parsed.\n- Files are sorted by first turn accessed. `errored` is `true` if any operation on that file errored.\n\n---\n\n### `tokens \u003csession\u003e`\n\nPer-turn token usage from assistant entries.\n\n```bash\ncc-session-tool tokens \u003csession\u003e [--project \u003cpath\u003e | --claude-project \u003cproject\u003e] [--cumulative]\n```\n\n**Output:**\n\n```json\n{\n  \"ok\": true,\n  \"data\": {\n    \"session_id\": \"DA2738E3-...\",\n    \"agent_id\": null,\n    \"turns\": [\n      {\n        \"n\": 2,\n        \"input\": 20170,\n        \"output\": 11,\n        \"cache_read\": 0,\n        \"cache_create\": 20170\n      },\n      {\n        \"n\": 4,\n        \"input\": 5995,\n        \"output\": 380,\n        \"cache_read\": 20170,\n        \"cache_create\": 5995\n      }\n    ],\n    \"totals\": {\n      \"input\": 142000,\n      \"output\": 38000,\n      \"cache_read\": 890000,\n      \"cache_create\": 45000\n    }\n  },\n  \"_meta\": { \"total\": 2, \"returned\": 2, \"hasMore\": false }\n}\n```\n\n**Notes:**\n\n- Only assistant entries appear in `turns` (they carry `message.usage`). User turns are counted but not listed.\n- `totals` is always non-cumulative, even with `--cumulative`.\n- With `--cumulative`, each field in `turns` is a running total.\n\n**Token fields:**\n\n| Field          | Source                                      |\n| -------------- | ------------------------------------------- |\n| `input`        | `message.usage.input_tokens`                |\n| `output`       | `message.usage.output_tokens`               |\n| `cache_read`   | `message.usage.cache_read_input_tokens`     |\n| `cache_create` | `message.usage.cache_creation_input_tokens` |\n\n---\n\n### `messages \u003csession\u003e`\n\nFiltered, truncated message content for drilling into specific parts of a session.\n\n```bash\ncc-session-tool messages \u003csession\u003e [--project \u003cpath\u003e | --claude-project \u003cproject\u003e] [--role \u003cuser|assistant\u003e] [--type \u003cblock_type\u003e] [--turn \u003cN|N-M\u003e] [--max-content \u003cchars\u003e]\n```\n\n| Option          | Default | Description                                                         |\n| --------------- | ------- | ------------------------------------------------------------------- |\n| `--role`        | all     | Filter by `user` or `assistant`                                     |\n| `--type`        | all     | Filter by block type: `text`, `thinking`, `tool_use`, `tool_result` |\n| `--turn`        | all     | Turn number `N` or range `N-M`                                      |\n| `--max-content` | 200     | Truncate text/thinking content to N chars                           |\n\n**Output:**\n\n```json\n{\n  \"ok\": true,\n  \"data\": {\n    \"session_id\": \"DA2738E3-...\",\n    \"agent_id\": null,\n    \"messages\": [\n      {\n        \"n\": 1,\n        \"role\": \"user\",\n        \"content\": [{ \"type\": \"text\", \"text\": \"Implement the feature...\" }]\n      },\n      {\n        \"n\": 2,\n        \"role\": \"assistant\",\n        \"content\": [\n          { \"type\": \"thinking\", \"text\": \"I need to...[truncated, 4832 chars]\" },\n          { \"type\": \"tool_use\", \"name\": \"Grep\", \"id\": \"toolu_abc123\" }\n        ]\n      }\n    ]\n  },\n  \"_meta\": { \"total\": 2, \"returned\": 2, \"hasMore\": false }\n}\n```\n\n**Notes:**\n\n- Content is truncated with `...[truncated, N chars]` suffix.\n- `tool_use` blocks preserve `name` and `id` (not truncated).\n- `tool_result` blocks preserve `tool_use_id` and `is_error`, with truncated content.\n\n---\n\n### `slice \u003csession\u003e`\n\nRaw entries for a turn range. The escape hatch for getting full content of specific turns.\n\n```bash\ncc-session-tool slice \u003csession\u003e --turn \u003cN|N-M\u003e [--project \u003cpath\u003e | --claude-project \u003cproject\u003e] [--max-content \u003cchars\u003e]\n```\n\n| Option          | Description                                           |\n| --------------- | ----------------------------------------------------- |\n| `--turn`        | Turn range (**required**)                             |\n| `--max-content` | Truncate text/thinking/tool_result content to N chars |\n\n**Notes:**\n\n- Without `--max-content`, entries are output as-is (full content preserved).\n- Output is wrapped in the standard `{ ok, data, _meta }` envelope where `data` is a structured object with `session_id`, `agent_id`, and `entries` (array of raw session entries). When targeting a subagent via colon notation, `agent_id` contains the agent ID; otherwise it is `null`.\n\n---\n\n### `search`\n\nFind sessions matching structured filters. By default, search is scoped to the logical project derived from `--project \u003cpath\u003e` or the current working directory, and it also includes associated Claude-managed worktree transcript directories. This agent-first default means a query from the main checkout can find work performed from a Claude worktree without `--all-projects`.\n\n```bash\ncc-session-tool search [--project \u003cpath\u003e] [--all-projects] [--project-glob \u003cpattern\u003e] [--tool \u003cname\u003e] [--input-match \u003ctext\u003e|--input-regex \u003cregex\u003e] [--file \u003cpath\u003e] [--text \u003ctext\u003e|--text-regex \u003cregex\u003e] [--intent-match \u003ctext\u003e|--intent-regex \u003cregex\u003e] [--bash \u003ctext\u003e|--bash-regex \u003cregex\u003e] [--no-subagents] [--operation \u003cop\u003e] [--origin] [--sort \u003cmode\u003e] [--aggregate count-per-session|counters] [--counter NAME=text] [--counter-regex NAME=regex] [--bucket day|week] [--per-subagent] [--branch \u003cname\u003e] [--after \u003cdate\u003e] [--before \u003cdate\u003e] [--since \u003cduration\u003e] [--last \u003cn\u003e]\n```\n\n| Option           | Default | Description |\n| ---------------- | ------- | ----------- |\n| `--project`      | CWD     | Logical project path for scoped search. Scoped searches include associated Claude worktrees by default. With `--all-projects`, this becomes a file-identity query anchor, not a scan limit. |\n| `--all-projects` | false   | Search every top-level Claude project directory under `~/.claude/projects` for broad audits. Without an explicit `--project`, absolute file queries do not infer a logical project anchor from CWD or `project_path_guess`. |\n| `--project-glob` | —       | With `--all-projects`, filter by raw Claude project basename or display-only `project_path_guess`. Supports `*` and `?`. |\n| `--tool`         | —       | Match tool names by case-insensitive substring. |\n| `--input-match`  | —       | Match raw structured tool input by case-insensitive substring, including fields omitted or truncated by `input_summary`. |\n| `--input-regex`  | —       | Match raw structured tool input by regex. Mutually exclusive with `--input-match`. |\n| `--file`         | —       | Match touched file paths by substring. |\n| `--operation`    | all     | With `--file`, filter by matching file operation: `read`, `edit`, `write`, `grep`, `glob`. |\n| `--origin`       | false   | With `--file`, return earliest matching transcript write evidence. Implies `--operation write` and defaults to one result. |\n| `--sort`         | `session-newest` | Sort matches by `session-newest`, `match-earliest`, `match-newest`, or `project`. |\n| `--aggregate`    | `none`  | `count-per-session` returns per-session tool-input counts; `counters` returns named raw-input counters. |\n| `--counter` / `--counter-regex` | — | Named raw-input counter as `NAME=pattern`; requires `--aggregate counters`. |\n| `--bucket`       | `none`  | With `--aggregate counters`, bucket by `day` or `week`. Missing timestamps use `unknown`. |\n| `--per-subagent` | false   | With counter aggregation, emit transcript-level rows instead of parent session rollups. |\n| `--text`         | —       | Match user/assistant text and thinking by case-insensitive substring. |\n| `--text-regex`   | —       | Match user/assistant text and thinking by regex. |\n| `--intent-match` | —       | Match session intent sources (`slug`, first prompt token, first user message) by substring. |\n| `--intent-regex` | —       | Match session intent sources by regex. |\n| `--bash`         | —       | Match Bash command inputs by case-insensitive substring. |\n| `--bash-regex`   | —       | Match Bash command inputs by regex. |\n| `--no-subagents` | false   | Disable default one-level subagent transcript inclusion. |\n| `--branch`       | all     | Filter by git branch name. |\n| `--after`        | —       | Sessions after ISO 8601 date (mutually exclusive with `--since`). |\n| `--before`       | —       | Sessions before ISO 8601 date. |\n| `--since`        | —       | Sessions from the last duration: `30m`, `2h`, `1d`, `1w` (mutually exclusive with `--after`). |\n| `--last`         | all     | Return only the N matches after sorting. With `--origin`, defaults to 1 unless set. |\n\nAt least one selector is required: `--tool`, raw-input, file, text, intent, bash, or counter filter. You may provide more than one; multiple filters use AND semantics. `--operation` is valid only with `--file`, and it is tied to the same matching file access, not any other file access in the session.\n\nFor absolute `--file` queries inside the logical project, search compares exact canonical path candidates first, then exact project-relative logical identity. For example, `/workspace/app/src/auth.ts` in the main checkout matches `/workspace/app/.claude/worktrees/feature-a/src/auth.ts` from a related Claude worktree as the same logical file `src/auth.ts`. If a worktree path reaches the same file through a symlinked directory, the realpath candidate can also match even when the lexical absolute paths differ. If both sides normalize to logical paths and they differ, search does not fall back to substring matching.\n\n**Examples:**\n\n```bash\n# Search the current project for sessions that touched auth.ts\ncc-session-tool search --file auth.ts\n\n# From the main checkout, find worktree sessions that wrote the same logical file\ncc-session-tool search --file /workspace/app/src/auth.ts --operation write\n\n# Find the earliest transcript write for a file\ncc-session-tool search --file /workspace/app/src/auth.ts --origin\n\n# Search all selected Claude project identities for recent Bash usage\ncc-session-tool search --all-projects --project-glob \"*app*\" --bash \"bun test\" --since 1d --last 5\n\n# Broad audit with the main checkout used only as a file-identity anchor\ncc-session-tool search --all-projects --project /workspace/app --file /workspace/app/src/auth.ts --operation write\n\n# Audit raw Bash inputs, including long commands beyond the condensed summary\ncc-session-tool search --tool Bash --input-match \"bun test\" --aggregate count-per-session\n```\n\n**Output:**\n\n```json\n{\n  \"ok\": true,\n  \"data\": [\n    {\n      \"session_id\": \"DA2738E3-...\",\n      \"branch\": \"feature/auth\",\n      \"timestamp\": \"2026-03-07T22:31:26.359Z\",\n      \"slug\": \"snuggly-floating-barto\",\n      \"matches\": {\n        \"tools\": [\"Read\", \"Edit\"],\n        \"files\": [\"/workspace/app/src/auth.ts\"],\n        \"normalized_files\": [\"src/auth.ts\"],\n        \"evidence\": [\n          {\n            \"kind\": \"file\",\n            \"rawPath\": \"/workspace/app/.claude/worktrees/feature-a/src/auth.ts\",\n            \"logicalPath\": \"src/auth.ts\",\n            \"operation\": \"edit\",\n            \"turn\": 8,\n            \"block_index\": 0,\n            \"timestamp\": \"2026-03-07T22:34:10.000Z\"\n          }\n        ],\n        \"operations\": [\"read\", \"edit\"],\n        \"turns\": [6, 8]\n      }\n    }\n  ],\n  \"_meta\": { \"total\": 1, \"returned\": 1, \"hasMore\": false }\n}\n```\n\nWith `--aggregate count-per-session`, `data` is a per-session summary instead of full match rows:\n\n```json\n{\n  \"ok\": true,\n  \"data\": [\n    {\n      \"session_id\": \"DA2738E3-...\",\n      \"branch\": \"feature/auth\",\n      \"timestamp\": \"2026-03-07T22:31:26.359Z\",\n      \"slug\": \"snuggly-floating-barto\",\n      \"counts\": { \"tool_inputs\": 3 },\n      \"sample_matches\": [\n        { \"tool\": \"Bash\", \"input_summary\": \"bun test index.test.ts\", \"turn\": 9 }\n      ]\n    }\n  ],\n  \"_meta\": { \"total\": 1, \"returned\": 1, \"hasMore\": false }\n}\n```\n\nScoped responses include `_meta.included_projects`, showing the main project and associated worktree Claude project contexts that were scanned. All-project responses include every scanned Claude project unless narrowed by `--project-glob`; an explicit `--project` in all-project mode is only used to normalize absolute file queries against that logical checkout. Worktree or all-project result rows can include:\n\n| Field | Description |\n| ----- | ----------- |\n| `project` | Raw Claude project directory basename from `~/.claude/projects`. |\n| `project_path_guess` | Best-effort unmangled path guess, or `null` when the directory name is not in Claude's path-mangled form. This is display-only and lossy when path segments contain literal hyphens. |\n| `project_role` | `main`, `worktree`, or `global`. |\n| `session_ref` | Stable follow-up identity: `{ \"session_id\": \"...\", \"project\": \"\u003craw Claude project basename\u003e\" }`. |\n\nUse `session_ref.project` with `--claude-project` rather than relying on `project_path_guess`:\n\n```bash\ncc-session-tool tools DA2738E3 --claude-project -workspace-app--claude-worktrees-feature-a\n```\n\nAll-project responses also include `_meta.projects_scanned`. `--project-glob` matches Claude project identity fields, not filesystem globs over project files. Do not derive follow-up commands or roots from `project_path_guess`; it is for display and rough filtering only.\n\n`--origin` reports the earliest matching transcript write evidence that satisfies the filters. It is not VCS creation history.\n\n```json\n{\n  \"ok\": true,\n  \"data\": [\n    {\n      \"session_id\": \"DA2738E3-...\",\n      \"session_ref\": {\n        \"session_id\": \"DA2738E3-...\",\n        \"project\": \"-workspace-app--claude-worktrees-feature-a\"\n      },\n      \"matches\": {\n        \"files\": [\"/workspace/app/.claude/worktrees/feature-a/src/auth.ts\"],\n        \"file_evidence\": [\n          {\n            \"rawPath\": \"/workspace/app/.claude/worktrees/feature-a/src/auth.ts\",\n            \"logicalPath\": \"src/auth.ts\",\n            \"operation\": \"write\",\n            \"turn\": 6,\n            \"timestamp\": \"2026-03-07T22:33:00.000Z\"\n          }\n        ],\n        \"turns\": [6]\n      }\n    }\n  ],\n  \"_meta\": { \"total\": 1, \"returned\": 1, \"hasMore\": false }\n}\n```\n\n---\n\n### `subagents \u003csession\u003e`\n\nList subagents spawned during a session. Reads metadata from companion `.meta.json` files and counts JSONL lines for each subagent.\n\n```bash\ncc-session-tool subagents \u003csession\u003e [--project \u003cpath\u003e | --claude-project \u003cproject\u003e]\n```\n\n**Output:**\n\n```json\n{\n  \"ok\": true,\n  \"data\": {\n    \"session_id\": \"DA2738E3-...\",\n    \"subagents\": [\n      {\n        \"agent_id\": \"a8361bc\",\n        \"agent_type\": \"task\",\n        \"description\": \"Implement auth middleware\",\n        \"lines\": 84,\n        \"timestamp\": \"2026-03-07T22:35:00.000Z\"\n      }\n    ]\n  },\n  \"_meta\": { \"total\": 1, \"returned\": 1, \"hasMore\": false }\n}\n```\n\n**Notes:**\n\n- Subagents are sorted by timestamp (newest first). Null timestamps sort to end.\n- `agent_type` and `description` come from `agent-\u003cid\u003e.meta.json`; both are `null` if the meta file is missing.\n- Use the returned `agent_id` with colon notation to target a subagent with any session-scoped command (e.g., `shape DA2738E3:a8361bc`).\n- Colon notation is rejected by this command (subagents of subagents do not exist).\n\n## Composition Examples\n\n### Quick access to recent sessions\n\n```bash\n# Last 5 sessions\ncc-session-tool list --last 5\n\n# Sessions from the last day\ncc-session-tool list --since 1d\n\n# Last 3 sessions on a specific branch\ncc-session-tool list --branch feature/auth --last 3\n\n# Recent sessions across selected Claude project identities\ncc-session-tool list --all-projects --project-glob \"*app*\" --last 5\n```\n\n### Navigation analysis before first edit\n\n```bash\n# Find the session\ncc-session-tool list --branch feature/auth\n\n# See the structure -- note first_edit_turn in summary\ncc-session-tool shape DA2738E3\n\n# Extract all tool calls before the first edit (say turn 15)\ncc-session-tool tools DA2738E3 --turn 1-14\n```\n\n### Failed Grep patterns\n\n```bash\ncc-session-tool tools \u003csession\u003e --name Grep --failed\n```\n\n### Drill into a specific turn\n\n```bash\n# Full content of turns around the first edit\ncc-session-tool slice DA2738E3 --turn 14-16\n\n# Just the assistant's reasoning\ncc-session-tool messages DA2738E3 --role assistant --type thinking --turn 14-16\n```\n\n### What files did a session touch?\n\n```bash\n# All files, grouped by path\ncc-session-tool files DA2738E3\n\n# Just edits\ncc-session-tool files DA2738E3 --operation edit\n\n# Chronological log of all file accesses\ncc-session-tool files DA2738E3 --group-by turn\n```\n\n### Find which session wrote a file\n\n```bash\n# Current logical project, including associated Claude worktrees\ncc-session-tool search --file /workspace/app/src/auth.ts --operation write\n\n# Earliest matching transcript write with file evidence\ncc-session-tool search --file /workspace/app/src/auth.ts --origin\n\n# Broad audit across selected Claude project identities\ncc-session-tool search --all-projects --project-glob \"*app*\" --file src/auth.ts --operation write\n```\n\n### Token consumption comparison\n\n```bash\ncc-session-tool tokens \u003cplanning-session\u003e\ncc-session-tool tokens \u003cimplementation-session\u003e\n# Compare input/output ratios and cache_read/cache_create patterns\n```\n\n### Inspect subagent activity\n\n```bash\n# Discover subagents spawned during a session\ncc-session-tool subagents DA2738E3\n\n# See what a specific subagent did\ncc-session-tool shape DA2738E3:a8361bc\n\n# Check tool calls in a subagent session\ncc-session-tool tools DA2738E3:a8361bc\n\n# List sessions with subagent counts\ncc-session-tool list --include-subagents\n```\n\n## Output Format\n\nAll commands return JSON with a consistent envelope:\n\n```json\n{\n  \"ok\": true,\n  \"data\": { ... },\n  \"_meta\": { \"total\": 1, \"returned\": 1, \"hasMore\": false }\n}\n```\n\nErrors:\n\n```json\n{\n  \"ok\": false,\n  \"error\": { \"code\": \"NOT_FOUND\", \"message\": \"...\" }\n}\n```\n\n### Exit Codes\n\n| Code | Meaning                        |\n| ---- | ------------------------------ |\n| 0    | Success                        |\n| 1    | Format error / terminated      |\n| 2    | Invalid arguments or ID format |\n| 3    | Not found                      |\n\n## Testing\n\n```bash\nbun test\n```\n\n## Releasing\n\n```bash\nbun run release \u003cmajor|minor|patch\u003e\n```\n\nThe release script (`scripts/release.sh`) handles the full local workflow:\n\n1. Asserts clean working tree on `main`, up-to-date with remote\n2. Runs tests\n3. Bumps `VERSION` in `index.ts`, commits, tags `vX.Y.Z`\n4. Pushes commit + tag to origin\n\nThe tag push triggers the `release.yml` GitHub Actions workflow, which builds universal macOS binaries and creates a GitHub release with checksums.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgacy%2Fcc-session-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmgacy%2Fcc-session-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgacy%2Fcc-session-tool/lists"}