Skip to content
Back to search

ccrider

SkillWorks with Claude CodeGitHub

Search, browse, and resume your Claude Code sessions. Fast.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/neilberkman/ccrider with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/neilberkman/ccrider'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/neilberkman--ccrider/badge.svg)](/listings/neilberkman--ccrider)

HTML

<a href="/listings/neilberkman--ccrider"><img src="/api/listings/neilberkman--ccrider/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Configure your MCP-capable client to run `ccrider serve-mcp`. Examples:

**Claude Code:**

# Install for all your projects (recommended)
claude mcp add --scope user ccrider $(which ccrider) serve-mcp

# Or for current project only
claude mcp add ccrider $(which ccrider) serve-mcp

**Claude Desktop:**

Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

{
  "mcpServers": {
    "ccrider": {
      "command": "ccrider",
      "args": ["serve-mcp"]
    }
  }
}

**Other MCP clients:**

Use command `ccrider` with args `["serve-mcp"]`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 328 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # ccrider
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  3. [![Release](https://img.shields.io/github/v/release/neilberkman/ccrider)](https://github.com/neilberkman/ccrider/releases)
  4. [![Homebrew](https://img.shields.io/badge/homebrew-neilberkman%2Ftap-orange)](https://github.com/neilberkman/homebrew-tap)
  5. [![Show HN](https://img.shields.io/badge/Show%20HN-black?logo=ycombinator)](https://news.ycombinator.com/item?id=46512501)
  6. Search, browse, and resume your Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, Pi, Antigravity, and Amp sessions, plus MCP server to remember past context.
  7. When your coding agent forgets, tell it: _[see what you have done](#the-king)_.
  8. ## Why ccrider?
  9. You've got months of coding agent sessions sitting in `~/.claude/projects/`, `~/.codex/sessions/`, `~/.copilot/`, `~/.local/share/opencode/`, `~/.pi/agent/sessions/`, `~/.gemini/antigravity*/brain/`, and your Amp account. Finding that conversation where you fixed the authentication bug? Good luck grepping through nested JSON files and separate tools.
  10. ccrider indexes Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, Pi, Antigravity (CLI, IDE, and desktop app), and Amp sessions into a single searchable database, with a TUI browser, CLI search, and an MCP server so your agent can search past sessions too.
  11. ```bash
  12. # Import sessions from every detected local provider (and Amp when explicitly enabled)
  13. ccrider sync
  14. # Launch the TUI - browse, search, resume
  15. ccrider tui
  16. # Or search from command line
  17. ccrider search "authentication bug"
  18. ```
  19. Stay in your terminal. Find any conversation. Resume where you left off. Sessions are tagged with their provider in the TUI for easy identification.
  20. **Installation:**
  21. ```bash
  22. # Homebrew (recommended)
  23. brew install neilberkman/tap/ccrider
  24. # Installed 1.11.1 or earlier with Homebrew? ccrider is now a cask, not a formula:
  25. brew uninstall --formula ccrider
  26. brew trust --cask neilberkman/tap/ccrider
  27. brew install --cask neilberkman/tap/ccrider
  28. # Or from source
  29. git clone https://github.com/neilberkman/ccrider.git
  30. cd ccrider
  31. go build -o ccrider cmd/ccrider/main.go
  32. sudo mv ccrider /usr/local/bin/
  33. # Optional: install the MCP server in Claude Code
  34. claude mcp add --scope user ccrider $(which ccrider) serve-mcp
  35. ```
  36. <a id="the-king"></a>
  37. _"Vibe code like ~a king~ The King!"_
  38. https://github.com/user-attachments/assets/5b008290-076e-4323-a775-f27f704b1ff2
  39. ## Core Features
  40. ### 1. Interactive TUI Browser
  41. ```bash
  42. ccrider tui
  43. ```
  44. Browse your sessions with a polished terminal UI:
  45. - **Arrow keys** to navigate
  46. - **Enter** to view full conversation
  47. - **o** to open session in new terminal tab (auto-detects Ghostty, iTerm, Terminal.app)
  48. - **/** to search across all messages
  49. - **p** to toggle project filter (show only current directory)
  50. - **?** for help
  51. Sessions matching your current directory are highlighted in light green - instantly see which sessions are relevant to your current work.
  52. ### 2. Full-Text Search
  53. ```bash
  54. ccrider search "postgres migration"
  55. ccrider search "error handling" --project ~/code/myapp
  56. ccrider search "authentication" --after 2024-01-01
  57. ```
  58. Powered by SQLite FTS5 - search message content, filter by project or date, get results instantly.
  59. ### 3. Resume Sessions
  60. Press **r** in the TUI to launch the provider's resume command in the right directory with the right session. Use **c** to copy that command or **o** to open it in a new terminal. Pi resumes with `pi --session <id>` and forks with `pi --fork <id>`; Antigravity CLI sessions resume with `agy --conversation <id>` and fork interactively with `/fork`; Antigravity IDE and desktop app conversations are searchable and browsable but have no terminal resume command, so reopen them in the app; Amp resumes with `amp threads continue <id>`.
  61. ### 4. Incremental Sync
  62. ```bash
  63. ccrider sync # Import new sessions from all providers
  64. ccrider sync --force # Re-import everything
  65. ```
  66. Automatically discovers Claude Code (`~/.claude/projects/`), Codex CLI (`~/.codex/sessions/`), GitHub Copilot CLI (`~/.copilot/session-state/`), OpenCode (`~/.local/share/opencode/opencode*.db`), Pi (`~/.pi/agent/sessions/`), Antigravity CLI (`~/.gemini/antigravity-cli/brain/`), Antigravity IDE (`~/.gemini/antigravity-ide/brain/`), and the Antigravity desktop app (`~/.gemini/antigravity/brain/`) sessions. Antigravity imports each canonical `transcript.jsonl`, excluding its diagnostic transcript. To import Amp, set `amp_enabled = true` in `~/.config/ccrider/config.toml` and install/authenticate the `amp` CLI. ccrider then lists archived and active threads and exports only new or changed threads.
  67. Amp threads are cloud-backed. The integration is disabled by default because enabling it downloads searchable text into ccrider's local SQLite database. MCP requests never contact Amp; they search cached Amp data from an earlier CLI/TUI sync.
  68. ---
  69. ## MCP Server
  70. ccrider includes a built-in MCP (Model Context Protocol) server that gives your coding agent access to your session history.
  71. Ask your agent to search past conversations while working on new problems:
  72. - "Find sessions where I worked on authentication"
  73. - "Show me my most recent Elixir sessions"
  74. - "What was I working on last week in the billing project?"
  75. - "Search my Codex sessions for database migrations"
  76. ### Setup
  77. Configure your MCP-capable client to run `ccrider serve-mcp`. Examples:
  78. **Claude Code:**
  79. ```bash
  80. # Install for all your projects (recommended)
  81. claude mcp add --scope user ccrider $(which ccrider) serve-mcp
  82. # Or for current project only
  83. claude mcp add ccrider $(which ccrider) serve-mcp
  84. ```
  85. **Claude Desktop:**
  86. Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
  87. ```json
  88. {
  89. "mcpServers": {
  90. "ccrider": {
  91. "command": "ccrider",
  92. "args": ["serve-mcp"]
  93. }
  94. }
  95. }
  96. ```
  97. **Other MCP clients:**
  98. Use command `ccrider` with args `["serve-mcp"]`.
  99. ### Available Tools
  100. - **search_sessions** - Full-text search across all session content with date/project/provider filters
  101. - **list_recent_sessions** - Get recent sessions, optionally filtered by project or provider
  102. - **get_session_messages** - Get messages from a session (supports tail mode, context around search matches)
  103. - **generate_session_anchor** - Save a unique session anchor, optionally with a descriptive label and a known session ID
  104. - **list_session_anchors** - List saved anchors and their matching sessions, with project/provider/session filters and pagination
  105. - **wait_for_session** - Wait for another session to finish a turn, write a message or phrase, or send a signal
  106. - **send_session_signal** - Post a signal to a channel, waking sessions that wait on it
  107. `search_sessions`, `list_recent_sessions`, and `list_session_anchors` support a `provider` parameter to filter by `claude`, `codex`, `copilot`, `opencode`, `pi`, `antigravity`, `antigravity-ide`, `antigravity-desktop`, or `amp`. Search and retrieval tools read your local session database; anchor generation saves a bookmark there. Local providers are read from disk; Amp threads are fetched from your authenticated Amp account during sync and then stored locally.
  108. ### Saving and finding session anchors
  109. Ask your agent to bookmark a conversation with a descriptive label. For example, `generate_session_anchor` with `{"label": "Add REST endpoint"}` saves a tag such as `add-rest-endpoint-a12bc34de56f`. The agent supplies the label from the conversation; no separate LLM service is required. Omitting `label` keeps the original four-random-word format.
  110. If the agent knows the session ID, it can also supply `session_id` to attach the bookmark immediately. Otherwise, it includes the returned phrase in its response and waits for a user reply so the phrase can be written to the transcript. `list_session_anchors` syncs local transcripts and finds conversations containing the phrase, without a date cutoff.
  111. Call `list_session_anchors` to retrieve saved labels, phrases, timestamps, and matching sessions with resume commands. Use a returned `session_id` with `get_session_messages` to read the conversation. The list defaults to 20 anchors per page (maximum 100); pass its `next_offset` as `offset` to continue. Optional `project`, `provider`, and `session_id` filters select associated sessions.
  112. An anchor appears in the unfiltered list as soon as it is generated, even if its `sessions` list is still empty. Session filters omit unmatched anchors. A phrase copied into multiple conversations can match more than one session; an explicit `session_id` binding takes precedence. Large session lists can be shortened with `sessions_truncated: true` and the full `session_count` retained.
  113. The registry includes anchors generated after this feature was added. Previously generated phrases and manually written tags remain searchable as ordinary conversation text.
  114. ### Waiting on another session
  115. One session can wait for another, even when they run in different harnesses. There are two kinds of watch.
  116. **Transcript watches** follow a Claude Code or Codex session's transcript, with no cooperation needed from it. Call `wait_for_session` with a `session_id` and `until` set to any of:
  117. - `turn_end`: the session finishes a turn. The event's `outcome` is `completed`, `failed`, `refused` or `interrupted`. Codex events include the turn's final message as `excerpt`.
  118. - `message`: the session writes any new assistant message.
  119. - `phrase`: the session writes a message containing a phrase. Pass `mint_phrase: true` to get a unique phrase to hand to the other session.
  120. `turn_end` needs an interactive Claude Code session; headless `claude -p` sessions don't record turn ends. A turn already running when the watch is armed reports its end. A Codex thread is followed when it moves to another rollout file.
  121. **Signal watches** work with any harness. Arm with `{"until": ["signal"], "mint_channel": true}`, give the channel to the other session, and have it call `send_session_signal` with a short result when it's done. Signals are kept for 7 days. Resending with the same `idempotency_key` and body doesn't post twice.
  122. Arming returns immediately with a cursor. Each wait returns as soon as something matches, or after `max_wait_seconds` (default 20) with status `waiting` and a cursor to continue from. Nothing is lost between calls, and every event has an `event_id` for deduplication. If a transcript is rewritten, truncated or replaced, the wait returns status `gap` with a fresh cursor, since events in between may be missing.
  123. The same works from a shell, which suits agents that can run a background command and resume when it exits:
  124. ```bash
  125. ccrider wait arm <session> --until turn_end # prints a cursor
  126. ccrider wait <cursor> --timeout 2h # exits 0 on an event, 2 on timeout, 3 on a gap
  127. ccrider wait arm --signal --mint-channel # signal watch: prints a channel and cursor
  128. ccrider signal <channel> "tests pass" # from the other session
  129. ```
  130. The design and its limits are in `docs/plans/2026-10-30-session-watch-spec.md`.
  131. ### Recovering earlier context
  132. `generate_session_anchor` helps an agent identify its current conversation after context compaction. The agent calls the tool, includes the returned phrase in its response, and asks you to reply so that response can be written to the transcript. It then calls `search_sessions` with the phrase as `anchor_phrase` and the topic it needs as `query`. You do not need to keep a separate record of the phrase for this workflow.
  133. A unique phrase already visible in the conversation can also be used as `anchor_phrase` without calling the generator. The `anchor_phrase` search filter matches transcript text and, by default, only considers matches from the last hour; explicit `after_date` or `before_date` filters override that window. For a saved bookmark, use `list_session_anchors` to obtain the session ID directly, including when the bookmark was attached without writing its phrase into the transcript.
  134. To find an older conversation using a tag you know, including a descriptive tag you wrote yourself, search for it directly:
  135. ```json
  136. {
  137. "query": "how-to-add-a-rest-endpoint-in-this-repo-abc123",
  138. "exact_match": true
  139. }
  140. ```
  141. This ordinary `search_sessions` query has no default date restriction. Use a returned `session_id` with `get_session_messages` to read the conversation.
  142. ---
  143. ## Configuration
  144. > **Note:** Claude Code auto-deletes session JSON files after 30 days by default. ccrider preserves all session content in its own database, but if you want the original files kept (for resume, etc.), add `"cleanupPeriodDays": 99999` to your `~/.claude/settings.json`.
  145. ccrider looks for config in `~/.config/ccrider/`:
  146. ```toml
  147. # config.toml - pass additional flags to each provider's resume command
  148. claude_flags = ["--dangerously-skip-permissions"]
  149. # codex_flags = ["--dangerously-bypass-approvals-and-sandbox"]
  150. # copilot_flags = []
  151. # opencode_flags = []
  152. # pi_flags = []
  153. ```
  154. ```txt
  155. # terminal_command.txt - custom command for 'o' key
  156. # Available placeholders: {cwd}, {command}
  157. wezterm cli spawn --cwd {cwd} -- {command}
  158. ```
  159. ```txt
  160. # resume_prompt.txt - customize the prompt sent when resuming sessions
  161. ```
  162. See [CONFIGURATION.md](docs/CONFIGURATION.md) for full details.
  163. ---
  164. ## Architecture
  165. Built with strict core/interface separation following [Saša Jurić's principles](https://www.theerlangelist.com/article/phoenix_is_modular):
  166. - **Core** (`pkg/`, `internal/core/`): Pure business logic - parsing, database, search, multi-provider import
  167. - **Interface** (`internal/interface/`, `cmd/`): Thin wrappers - CLI, TUI, MCP server
  168. Uses proven technologies:
  169. - **Go** for performance and single-binary distribution
  170. - **SQLite with FTS5** for fast full-text search
  171. - **Bubbletea** for polished terminal UI
  172. - **MCP** for coding agent integration
  173. ### Why This Matters
  174. Other coding agent session tools are broken:
  175. - Incomplete schema support (can't parse all message types)
  176. - Broken builds and abandoned dependencies
  177. - No real search (just grep)
  178. - Can't actually resume sessions
  179. - Single-provider only
  180. ccrider fixes this with:
  181. - 100% schema coverage - parses all message types correctly
  182. - Multi-provider - Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, Pi, Antigravity, and Amp in one database
  183. - SQLite FTS5 search - fast, powerful full-text search
  184. - Single binary - no npm, no pip, no dependencies
  185. - Native resume - one keystroke to resume sessions
  186. - Incremental sync - detects new messages in ongoing sessions
  187. ---
  188. ## Development
  189. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
  190. ### Project Structure
  191. ```
  192. cmd/ccrider/ # CLI entry point + MCP server
  193. internal/
  194. core/ # Business logic (no UI concerns)
  195. db/ # Database operations
  196. importer/ # Session import/sync and Amp CLI client
  197. search/ # Full-text search
  198. session/ # Session launch logic
  199. interface/ # Thin UI wrappers
  200. cli/ # Command handlers
  201. tui/ # Terminal UI (bubbletea)
  202. pkg/
  203. ccsessions/ # Claude Code session parser (public API)
  204. codexsessions/ # Codex CLI session parser (public API)
  205. copilotsessions/ # GitHub Copilot CLI session parser (public API)
  206. opencodesessions/ # OpenCode session parser (public API)
  207. pisessions/ # Pi session parser (public API)
  208. antigravitysessions/ # Antigravity session parser (public API)
  209. ampsessions/ # Pure Amp export parser (public API)
  210. ```
  211. ### Quick Build
  212. ```bash
  213. go build -o ccrider cmd/ccrider/main.go
  214. ./ccrider sync
  215. ./ccrider tui
  216. ```
  217. ---
  218. ## Documentation
  219. - [Configuration Guide](docs/CONFIGURATION.md)
  220. - [Resume Prompts](docs/RESUME_PROMPT.md)
  221. - [Design Document](docs/plans/2025-11-08-ccrider-design.md)
  222. - [Schema Documentation](research/schema.md)
  223. - [Requirements](research/requirements.md)
  224. ## License
  225. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.