{"id":51232607,"url":"https://github.com/aahoughton/cctx","last_synced_at":"2026-06-28T17:32:12.745Z","repository":{"id":347402389,"uuid":"1193235284","full_name":"aahoughton/cctx","owner":"aahoughton","description":"CLI tool to search, rename, summarize, and manage Claude Code conversation history — browse sessions,   bulk rename with LLM, full-text search, and clean up project directories","archived":false,"fork":false,"pushed_at":"2026-05-31T14:06:33.000Z","size":78,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T15:23:49.267Z","etag":null,"topics":["anthropic","claude","claude-code","cli","command-line-tool","conversation-history","developer-tools","go","golang","llm"],"latest_commit_sha":null,"homepage":"","language":"Go","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/aahoughton.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-27T02:26:46.000Z","updated_at":"2026-05-31T14:06:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aahoughton/cctx","commit_stats":null,"previous_names":["aahoughton/cctx"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/aahoughton/cctx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aahoughton%2Fcctx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aahoughton%2Fcctx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aahoughton%2Fcctx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aahoughton%2Fcctx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aahoughton","download_url":"https://codeload.github.com/aahoughton/cctx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aahoughton%2Fcctx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34898562,"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-28T02:00:05.809Z","response_time":54,"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":["anthropic","claude","claude-code","cli","command-line-tool","conversation-history","developer-tools","go","golang","llm"],"created_at":"2026-06-28T17:32:12.569Z","updated_at":"2026-06-28T17:32:12.728Z","avatar_url":"https://github.com/aahoughton.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cctx\n\nA CLI for browsing and managing Claude Code's local conversation history.\n\nClaude Code stores everything locally as JSONL files under `~/.claude/projects/`.\nIts built-in `--resume` lets you pick recent sessions, but there's no way to\nsearch across conversations, bulk-rename sessions, manage project directories,\nor get LLM-generated summaries of past work. cctx fills that gap.\n\n## Examples\n\nSee what you've been working on across all projects:\n\n```\n$ cctx\nSESSION   PROJECT             MSGS  MODIFIED    SUMMARY\n0c5dc16b  ~/personal/cctx     270   5 min ago   native anthropic sdk support\nbd66e34e  ~/personal/cctx     33    11h ago     conversation naming best practices\na1b2c3d4  ~/src/myapp         45    yesterday   auth middleware rewrite\ne5f6a7b8  ~/src/myapp         120   2d ago      api endpoint security audit\n```\n\nList conversations for the current project:\n\n```\n$ cctx convs\nSESSION   MSGS  MODIFIED    SUMMARY\n0c5dc16b  270   5 min ago   native anthropic sdk support\nbd66e34e  33    11h ago     conversation naming best practices\n29e5b4b2  123   15h ago     llm summarization debugging\n```\n\nFind that conversation where you fixed the auth bug last week:\n\n```\n$ cctx search -f \"auth middleware\"\n4 hit(s) across 2 conversation(s):\n\n  a1b2c3d4  2026-03-20T11:42:00Z  auth middleware rewrite\n    [user] the old auth middleware is storing session tokens in a way that doesn't meet compliance...\n    [assistant] I'll refactor the middleware to use encrypted session storage. The main changes are in...\n    [user] looks good but we also need to handle the refresh token rotation\n\n  e5f6a7b8  2026-03-18T09:15:00Z  api endpoint security audit\n    [assistant] Found three issues in the auth middleware: 1) session tokens stored in plaintext...\n```\n\nGet a detailed summary of what happened in a session:\n\n```\n$ cctx show --llm a1b2c3d4\nSession:  a1b2c3d4-...\nModified: 2026-03-20 11:42:00\nMessages: 45\n\nRewrote the auth middleware to use encrypted session storage, driven by\na compliance requirement around token handling. The main changes were in\nmiddleware/auth.go and session/store.go, replacing the plaintext cookie\napproach with AES-GCM encrypted tokens and adding refresh token rotation.\n\nAlso updated the test suite to use real database connections instead of\nmocks, after discovering that the previous mock-based tests had masked\na migration issue in production.\n```\n\nGive your sessions meaningful names in bulk:\n\n```\n$ cctx rename -a\nFound 12 unnamed conversation(s) in /Users/me/src/myproject\n\n  a1b2c3d4  parsed-tumbling-lantern    -\u003e auth middleware rewrite\n  e5f6a7b8  spicy-exploring-pebble     -\u003e api endpoint security audit\n  ...\n\nRenamed 12 conversation(s).\n```\n\n## Install\n\n```sh\ngo install github.com/aahoughton/cctx@latest\n# or\ngo build -o cctx . \u0026\u0026 cp cctx ~/bin/\n\n# Shell completions\ncctx completion fish \u003e ~/.config/fish/completions/cctx.fish\ncctx completion bash \u003e /etc/bash_completion.d/cctx\ncctx completion zsh \u003e \"${fpath[1]}/_cctx\"\n```\n\n## Commands\n\n```sh\ncctx                                 # recent conversations across all projects\ncctx -n 20                           # show 20 most recent (default 10)\ncctx -T                              # absolute timestamps\ncctx -L                              # full session UUIDs (for `claude --resume`)\n\ncctx ls                              # list projects\ncctx ls -o                           # orphaned projects only\ncctx convs                           # list conversations (cwd project)\ncctx convs -T                        # absolute timestamps\ncctx convs -p ~/other/project        # specific project\n\ncctx show abc123                     # conversation digest\ncctx show -f abc123                  # full transcript\ncctx show --llm abc123               # LLM-generated narrative summary\n\ncctx rename abc123 \"my new name\"     # manual rename\ncctx rename abc123                   # auto-name via LLM\ncctx rename -a                       # batch-rename all unnamed\ncctx rename -an                      # preview batch rename\n\ncctx search \"auth middleware\"        # search metadata (fast, case-insensitive)\ncctx search -f \"handleRequest\"       # full-text search\ncctx search -A \"refactor\"            # search all projects\ncctx search -E \"fix(ed|ing) bug\"     # regex\ncctx search -u \"please add\"          # user messages only\ncctx search -a \"created file\"        # assistant messages only\ncctx search -s \"TODO\"                # case-sensitive\ncctx search -l \"auth\"                # session IDs only (grep -l style)\n\ncctx rm                              # preview project removal\ncctx rm -x                           # apply\ncctx mv ~/old/path ~/new/path        # preview path update\ncctx mv -x ~/old/path ~/new/path     # apply\ncctx merge ~/orphaned ~/current      # preview merge\ncctx merge -x ~/orphaned ~/current   # apply\ncctx prune                           # preview empty conversation removal\ncctx prune -Ax                       # apply across all projects\n```\n\nAll destructive operations are dry-run by default and require `-x` to apply.\n\nThe `-p` flag scopes any command to a specific project (defaults to cwd).\n\n## LLM Configuration\n\n`rename` and `show --llm` use an LLM for summarization. Claude models (any\nmodel starting with `claude-`) use the Anthropic API natively; all others\nuse the OpenAI-compatible chat completions API (Ollama, LM Studio, vLLM,\nOpenAI, Groq, Together, etc).\n\nConfigure via (in priority order): flags, environment variables, or config file.\n\n**Config file** (`~/.config/cctx/config.toml`):\n\n```toml\n[llm]\nurl = \"http://localhost:11434/v1\"   # Ollama, LM Studio, etc.\nmodel = \"qwen3-4\"                   # fast, good instruction following\napi_key = \"\"                        # optional for local models\n```\n\nFor Claude models, just set the model — the API key is picked up from\nthe environment:\n\n```toml\n[llm]\nmodel = \"claude-haiku-4-5\"\n# api_key from ANTHROPIC_API_KEY env var\n```\n\n**Environment variables**:\n\n```sh\nexport CONTEXT_LLM_URL=http://localhost:11434/v1\nexport CONTEXT_LLM_MODEL=llama3\n# API key: LLM_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY\n```\n\n**Flags**: `-U`, `-M`, `-K` override everything (available on `rename`\nand `show`).\n\n## Similar projects\n\nClaude Code has built-in `--resume` (session picker with keyword search)\nand `/rename` (current session only), but no cross-session search, bulk\noperations, or project directory management.\n\nSeveral third-party tools cover parts of this space:\n\n- **[claude-history](https://github.com/raine/claude-history)** (Rust) —\n  TUI for fuzzy-searching and reading conversations. Polished browsing\n  experience with vim keybindings, resume/fork support. Read-only.\n\n- **[claude-session-index](https://github.com/lee-fuhr/claude-session-index)** (Python) —\n  Indexes sessions into SQLite with FTS5. Analytics, topic tracking,\n  cross-session synthesis. Heavier infrastructure (database, hooks).\n\n- **[cc-conversation-search](https://github.com/akatz-ai/cc-conversation-search)** (Python) —\n  SQLite + FTS5 search with date filtering. Also available as a Claude\n  Code skill for natural language queries.\n\ncctx focuses on the management side: bulk LLM rename, project directory\noperations (ls/rm/mv/merge), pruning, and LLM-generated narrative\nsummaries. It's a single Go binary with no database or indexing step.\n\n## How it works\n\nClaude Code stores conversations under `~/.claude/projects/` in directories\nnamed by encoding the project's filesystem path (e.g. `/Users/me/src/foo`\nbecomes `-Users-me-src-foo`). Each conversation is a JSONL file with a UUID\nsession ID.\n\nThe encoding is lossy — literal hyphens in path components are\nindistinguishable from directory separators. cctx resolves this ambiguity\nby checking `sessions-index.json`, conversation `cwd` fields, and\nfilesystem probing, in that order.\n\n### Schema versioning\n\ncctx checks the `version` field in `sessions-index.json` against an\nexpected constant. If Claude changes its storage format, operations fail\nwith a clear error rather than silently corrupting data. When the index is\nmissing or incompatible, cctx falls back to parsing JSONL files directly.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faahoughton%2Fcctx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faahoughton%2Fcctx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faahoughton%2Fcctx/lists"}