cc-readback

# cc-readback **Read your Claude Code sessions from Claude Desktop.** A local, read-only [MCP](https://modelcontextprotocol.io) server over the session files Claude Code already writes to `~/.claude`. Ask Claude Desktop what your terminal sessions did today, which one is blocked, when you decided something, or which files a session touched, without pasting anything. Nothing listens on a port. Nothing is uploaded. Tool output, thinking blocks, attachments, pastes, and keys are never read. Every string it returns passes through secret redaction first. ``` You (in Claude Desktop): "What did my Claude Code sessions do today, and is anything waiting on me?" Claude: Two projects were active. - payments-api (branch fix/webhook-retry): 3 sessions. The last one ended on a question: "should the retry cap be configurable?" - waiting on you. - cc-readback (branch main): 1 session, shipped a redaction pipeline. ``` ## Why Claude Desktop, claude.ai, and the Claude mobile app cannot see your local Claude Code sessions. Anthropic's own support calls the separation intentional. Remote Control steers a *live* session; it does not let a normal chat read the sessions that are already over. Every workaround is manual copy-paste, a `grep` across `~/.claude/projects`, or a private export. cc-readback is the read path. It is not memory (memory is what Claude chose to keep). It is not sync (nothing leaves your machine on its own). It is a read-only view of the record that is already on your disk, exposed to the Claude you are already talking to. ## Install Requires Node 22.13+ and Claude Desktop and/or Claude Code. **One click (Claude Desktop):** download the `.mcpb` from [Releases](https://github.com/affirmitv/cc-readback/releases/latest) and open it (Claude Desktop → Settings → Extensions). Done. **From source (Desktop + Claude Code):** ```bash git clone https://github.com/affirmitv/cc-readback && cd cc-readback npm install && npm run build node dist/cli.js install all # registers with Claude Desktop AND Claude Code (user scope) ``` **From npm** (once published): `npm install -g cc-readback && cc-readback install all`. Then **quit Claude Desktop fully (Cmd-Q) and reopen it.** The tools appear under the connectors menu. In Claude Code they are available immediately as `mcp__readback__*`. To skip the Desktop tap-to-approve on every call, add to `~/.claude/settings.json`: ```json { "permissions": { "allow": ["mcp__readback__*"] } } ``` Uninstall with `cc-readback uninstall all` (or `node dist/cli.js uninstall all`). Pause instantly with `cc-readback off`, resume with `cc-readback on`. ## What it can answer | Tool | Answers | |------|---------| | `briefing` | What did my sessions do since <when>, and which are waiting on me? | | `list_projects` | Which projects have Claude Code history? | | `list_sessions` | Show me sessions in this project with titles and branches. | | `get_session_digest` | Summarize one session: prompts, answers, files, PRs, decisions. | | `get_session_timeline` | Walk one session turn by turn. | | `search_sessions` | When did we change X? Where did I discuss Y? | | `get_recent_prompts` | What have I been asking Claude Code lately? | | `get_file_changes` | Which sessions touched this file? | | `get_memory` | What does this project's auto-memory say? | | `get_status` | Index health, redaction totals, what is and is not shared. | Each result is token-budgeted so it fits in a chat, and wrapped as data the model is told not to treat as instructions. ## The security posture Claude Code transcripts are plaintext and, by Anthropic's own documentation, contain whatever a tool printed: `.env` reads, command output, keys, customer data. A tool that exposes them has to earn it. cc-readback's defense is layered and the layers are ordered so the strongest one is the default: 1. **A deny-by-default record allowlist.** Only a fixed set of record kinds is read at all: your typed prompts, assistant text, titles, tool *names* with a file-path or description digest, file paths touched, PR links, compaction summaries, and project memory. Tool result bodies, thinking blocks, attachments, pastes, uploads, the `atis-latch` token, `bridge-session` identity, `settings.json`, `~/.claude.json`, and the `sessions/*.key` files are never parsed. New record types that appear in a future Claude Code release are counted and dropped, not guessed. 2. **A path allowlist with realpath containment.** Only `projects/**/*.jsonl`, `history.jsonl`, `sessions/*.json`, and `projects/<slug>/memory/*.md` are ever opened. Symlinks that escape the store are refused. A `.nobridge` file in a project directory (or beside one session) hides it. 3. **Secret redaction on every emitted string**, including the server's own logs. Named patterns for the common credential families (AWS, GitHub, OpenAI, Anthropic, Slack, Stripe, Supabase, GCP, JWTs, private keys, `Authorization` headers, `.env` assignments), then an entropy backstop for unknown high-entropy tokens, then optional PII. Over-redaction of a hash or an id is the accepted side of the trade. 4. **Local only, read only.** stdio transport, zero network connections, zero write/exec/shell tools. A lint rule forbids importing a network module in the source, and a test blocks `fetch` and runs a full session to prove nothing dials out. 5. **A preflight that refuses to start** if your store files are group- or world-readable, with a one-line fix. An append-only audit log records every read: what, when, how many bytes, which redaction rules fired, never the content. A kill switch (`cc-readback off`) makes every call return an error until you turn it back on. Validated against a real 750 MB, 115-session store: every record type recognized, redaction fired on real secrets (high-entropy tokens, internal IPs, card numbers, keychain dumps, a JWT), and zero secret-shaped strings survived into any tool output. Full detail: [SECURITY.md](SECURITY.md), [docs/RECORD-ALLOWLIST.md](docs/RECORD-ALLOWLIST.md), [docs/DATA-HANDLING.md](docs/DATA-HANDLING.md). ## Your phone Desktop reads over stdio and needs no network. A normal claude.ai or mobile chat is different: Anthropic's servers, not your phone, connect to a custom connector, so that path needs a public HTTPS endpoint on your machine. That is deliberately out of scope for v1, where the default is a local server with no listener at all. The v1 way to reach the tools from your phone is Anthropic's own Remote Control: keep a `claude remote-control` session running, open the Claude app's Code tab, and ask it for a briefing. `cc-readback rc` prints the exact command. A hosted connector with real OAuth is planned as a separate, opt-in package so the default install never opens a port. ## What it will not do No writes, no deletes, no shell, no resume, no opening arbitrary files. It cannot show raw command output or build logs (you get the `claude --resume <id>` command instead). It does not read subagent transcripts. It cannot see sessions older than Claude Code's own `cleanupPeriodDays` (default 30), because Claude Code deletes them. Anything a chat returns is sent to Anthropic under your plan's terms; the tool tells you so and cannot change it. ## Data handling A local Desktop call still sends the tool's result to Anthropic's API as part of your chat, the same as any message you send. cc-readback redacts before returning, but the safe assumption is that whatever you ask it to surface, you are sending to Anthropic under your plan. See [docs/DATA-HANDLING.md](docs/DATA-HANDLING.md). ## Development ```bash npm install npm run build # tsup -> dist/cli.js (single ESM bundle) npm test # vitest: redaction, allowlist, path containment, cache, server e2e npm run test:corpus # opt-in: run the parser + redactor over your real ~/.claude, read-only npm run pack:mcpb # build the Claude Desktop .mcpb bundle ``` The transcript format is internal to Claude Code and changes between releases; the parser is tolerant of unknown records and pins its expectations to a committed schema note. If a release renames a record, digests degrade until a patch, and the parser fails safe rather than throwing. ## License MIT. See [LICENSE](LICENSE).