Summarizes AI coding sessions into structured recaps covering intent, key decisions, changes, and open threads.
Also known as BruceXcluding/session-recap
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.6.1
- Last commit
- Nov 8, 2026
- License
- MIT
What is session-recap MCP?
session-recap summarizes AI coding sessions into structured recaps covering intent, key decisions, changes, and open threads.
Summary generated from the project's README
About session-recap MCP server
session-recap helps developers maintain continuity in AI coding projects by transforming long, overwhelming transcripts into structured summaries. It captures essential information such as original intent, key decisions, file changes, and unresolved threads. This tool is designed for developers using various AI agents like Claude Code, Codex, dsh, and OpenCode, allowing them to quickly understand where a session left off and what the next logical step should be.
Users can interact with the server through an MCP client, a command line interface, or a local web viewer. When used via MCP, the agent's own model handles the summarization, meaning no additional API keys are required for the server itself. It also offers specialized plugins for Claude Code and dsh, as well as a local viewer accessible at localhost to browse session histories and maps across different agents. The system prioritizes privacy by redacting secrets like tokens and credentials before any text is processed by a model.
What you can do with it
- 1Summarize a current coding sessionAsk your AI agent to create a structured recap of the work you just completed.
Written from the project's README. Every use case is checked against a quote from it.
How to install session-recap MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall session-recap MCP in Claude Code
$ claude mcp add session-recap -- npx -y session-recapInstall session-recap MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"session-recap": {
"command": "npx",
"args": [
"-y",
"session-recap"
]
}
}
}Install session-recap MCP in VS Code
.vscode/mcp.json
{
"servers": {
"session-recap": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"session-recap"
]
}
}
}Install session-recap MCP in VS Code CLI
$ code --add-mcp '{"name":"session-recap","type":"stdio","command":"npx","args":["-y","session-recap"]}'Install session-recap MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"session-recap": {
"command": "npx",
"args": [
"-y",
"session-recap"
]
}
}
}Install session-recap MCP in Codex
$ codex mcp add session-recap -- npx -y session-recapInstall session-recap MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.session-recap] command = "npx" args = ["-y", "session-recap"]
Install session-recap MCP in Gemini CLI
$ gemini mcp add -s user session-recap npx -- -y session-recapInstall session-recap MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"session-recap": {
"command": "npx",
"args": [
"-y",
"session-recap"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablebrucexcluding/session-recap is public and reachablegithub.com/brucexcluding/session-recap ↗Pass
- Package names this repository as its sourcesession-recap names brucexcluding/session-recap as sourcenpmjs.com/package/session-recap ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/brucexcluding/session-recap ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from session-recapPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubsession-recap
Projects grow, and so does the number of sessions in each one, often across several agents. After a few weeks a session is a 100 MB transcript you no longer remember: why you started it, what you decided, what was left half done.
session-recap reads a session's whole transcript and writes a short, structured recap. Use it from any MCP client (Codex, Cursor, Zed, Cline, Gemini CLI, OpenCode, Claude Code…), in a local viewer for every agent's sessions, from the command line, or through native plugins for Claude Code, dsh and Codex.
| Section | What it answers |
|---|---|
| Intent | What was I ultimately trying to achieve? |
| Key ideas and decisions | What did we choose, and why? Which alternatives were rejected? |
| What changed | Files, features, documents, commits, PRs |
| Open threads | What is unfinished, unverified or still a question |
| Where to resume | The most sensible next step today |
Every recap also has a Map: the phases the work went through (pivots marked) down to "you are here", the key decisions with what was turned down, and lists of what shipped, what is open and what was dropped. Recaps are written in the language you mostly write in.
Quick start
npm install -g session-recap
session-recap mcp-config # prints the MCP entry for your client
session-recap serve # opens the local viewer
Then, in your agent: "Recap this session", "What was my last session in this project about?", "总结一下这个会话".
No API key needed. Through MCP, the agent you are talking to writes the recap with its own model; session-recap only reads and condenses the transcript. A model of session-recap's own is optional (for the CLI and the viewer's Write recap button).
Or run it without installing: npx session-recap …. session-recap has no dependencies and runs no install scripts. The development version: npm install -g github:BruceXcluding/session-recap --allow-git=all (npm 12 blocks installs from GitHub without the flag).
Requirements: Node.js 20+, python3 (macOS ships one), and for dsh sessions the zstd command or Python 3.14+.
Ways to use it
| Best for | How | |
|---|---|---|
| MCP server | any MCP client | session-recap mcp-config <client>, see below |
| Local viewer | browsing every agent's sessions, Recap and Map | session-recap serve |
| Claude Code plugin | a Recap / Map pane beside the chat | /plugin install session-recap --marketplace BruceXcluding/session-recap |
| dsh plugin | /recap and the session_recap tool in dsh |
packages/dsh |
| Codex plugin | the MCP server, packaged for Codex | plugins/codex |
| Command line | scripts, quick looks, other formats | session-recap, session-recap list |
MCP server
session-recap mcp-config <client> prints the entry for claude, codex, cursor, gemini (and Qwen Code), opencode, zed, vscode or cline, with absolute paths so an IDE started from the dock finds it. For example:
session-recap mcp-config codex >> ~/.codex/config.toml
claude mcp add --scope user session-recap -- session-recap mcp
Tools:
| Tool | What it does |
|---|---|
list_sessions |
Sessions of every agent, filtered by title words, project folder or agent |
recap_session |
The recap of the current session (or one named): a stored one if the session has not changed; else written by session-recap's model if one is configured; else the condensed, secret-free transcript and instructions for the calling agent to write it |
save_recap |
Stores the recap the agent wrote, so it is reused, and updated from the new part next time |
recap_session also takes format: standup, handoff or pr instead of the recap.
Local viewer
session-recap serve opens http://127.0.0.1:4711 with every agent's sessions by project folder, grouped by time, filtered by agent; each session's Recap and Map; and, with a model configured, Write recap and Update recap. It reads the recaps written by the Claude Code plugin, the CLI and MCP clients alike. It answers only on loopback, to the browser tab it opened.
Claude Code plugin
/session-recap recaps the session you are in; /session-recap browse lists projects and sessions; /session-recap <name> opens a project or a session by name. The pane shows Recap and Map, uses the session's own model (or one picked under Model), and shows your Claude Code sessions first, with All agents one tap away.
Command line
| Command | What it does |
|---|---|
session-recap [words] |
Recaps the session whose title holds the words; with none, the newest one in this folder |
session-recap list [words] |
Lists sessions (the calling agent's; --all for every agent) |
session-recap --format standup |
A standup note instead (handoff, pr) |
session-recap --dry-run |
Shows the size that would be sent, and how many secrets were removed, without calling a model |
session-recap models |
Lists your provider's models |
session-recap config set model <id> |
Saves settings (partModel, api, baseUrl; the key with config set apiKey - from stdin) |
The CLI's own model: SESSION_RECAP_API (anthropic or openai), SESSION_RECAP_BASE_URL, SESSION_RECAP_API_KEY, SESSION_RECAP_MODEL, or ANTHROPIC_*, DEEPSEEK_API_KEY, OPENAI_API_KEY.
Supported agents
| Agent | Sessions read from |
|---|---|
| Claude Code | ~/.claude/projects/ |
| Codex | ~/.codex/sessions/, archived_sessions/ (review threads left out) |
| dsh (deepseek-harness) | ~/.dsh/sessions/ (zstd; subagent sessions left out) |
| OpenCode | ~/.local/share/opencode/opencode.db |
Want another? Adding an agent is one reader and one test, or ask for it.
Privacy
- Local. Sessions are read on your machine. Text leaves it only in the model call a recap needs: your agent's (MCP, plugins) or the one you configured (CLI, viewer). No telemetry.
- Secrets removed first. Keys, tokens, private keys, credentials in URLs and
PASSWORD=…-style assignments are replaced with[REDACTED:<kind>]before any text reaches a model.--dry-runshows how many. It is pattern matching, so it cannot know every format: see SECURITY.md. - What is sent is a condensed transcript: your prompts, each turn's final reply, commits and PRs, the files edited. Tool output and intermediate replies are left out.
Token use
Listing never calls a model. On a real 179 MB Claude Code session (220 prompts), a first recap sends about 195k characters (~96k tokens); when the session continues, an update reads only the new prompts. Long sessions are condensed in parts of ≤75k characters, each part's notes cached, and a cheaper model can condense the parts (partModel).
How it works
saved sessions (Claude Code · Codex · dsh · OpenCode)
│
hooks/digest.py one reader per agent → turns (prompt, actions, final reply, edits) → secrets removed
│
core/recap.mjs parts → notes (parallel, cached) → one call writes the recap and its map, or updates it
│
MCP server · viewer · CLI · Claude Code pane · dsh tool and /recap (one cache: ~/.cache/session-recap)
Output is versioned: see docs/data-format.md and schema/recap-v1.schema.json to build your own viewer or exporter.
Contributing
Agents, recap formats, translations and viewers are all welcome. Start with CONTRIBUTING.md; adding an agent and adding a format (one entry in core/formats.mjs) are the easiest first contributions.
License
session-recap MCP questions
How do I add session-recap MCP to Claude Code?
Run claude mcp add session-recap -- npx -y session-recap in your terminal. Add --scope user to make it available in every project.
How do I add session-recap MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does session-recap require an API key?
No API key is needed for the MCP server because the agent you are talking to writes the recap using its own model.
How does the tool handle sensitive information?
The tool removes secrets like keys, tokens, and credentials using pattern matching before any text is sent to a model.