claude-session-manager — Claude Code skill: session export
claude-session-manager turns local Claude Code JSONL logs into readable Markdown files with conversation, digest, and tool call history.
MIT 207 installs ★ 140 updated 2026-10-19
npx skills add sugarforever/01coder-agent-skills --skill claude-session-manager -a claude-codeWhat claude-session-manager does
Claude Code writes each session to ~/.claude/projects/<project>/<id>.jsonl. The skill reads these files and exports them to structured Markdown: a digest (path, project, time, event count, first prompt), a clean conversation, and a separate file with full tool inputs and outputs. Commands, search results, and file contents go into a sidecar tool-details/<id>.tools.md so the main file stays lightweight.
Two modes. Full mode exports all matching sessions — use it for backups and archive search. Specific mode lists candidate sessions first (date, project, short id, cwd, first prompt), then exports the chosen one. Filters --project, --session, --since, and --limit narrow the list. No FFmpeg or external dependencies — Python 3 only.
Default output folder is ~/.claude/session-markdown. Each project folder gets an index.md, session files, and a tool-details subfolder. Original JSONL files stay untouched.
What it helps with
- export Claude Code logs to readable Markdown
- recover content from an old session without opening the IDE
- find a session by date, project, or prompt fragment
- parse tool call history from
.jsonltranscripts - back up all sessions for a project
Example prompts for the agent
- Show the last 20 Claude Code sessions
- Export session number 5 from the list
- Convert all sessions for project
my-reposince June 1
How to install claude-session-manager
1Skills CLI (Vercel)
npx skills add sugarforever/01coder-agent-skills --skill claude-session-manager -a claude-code2Manually: put the files in place
~/.claude/skills/claude-session-manager/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/claude-session-manager/
1Skills CLI (Vercel)
npx skills add sugarforever/01coder-agent-skills --skill claude-session-manager -a codex2Manually: put the files in place
.agents/skills/claude-session-manager/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add sugarforever/01coder-agent-skills --skill claude-session-manager -a cursor2Manually: put the files in place
.cursor/skills/claude-session-manager/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install sugarforever/01coder-agent-skills skills/claude-session-manager2Manually: put the files in place
.github/skills/claude-session-manager/SKILL.md1Skills CLI (Vercel)
npx skills add sugarforever/01coder-agent-skills --skill claude-session-manager -a gemini-cli2Platform CLI
gemini skills install https://github.com/sugarforever/01coder-agent-skills --path skills/claude-session-managerManually: put the files in place
.devin/skills/claude-session-manager/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add sugarforever/01coder-agent-skills --skill claude-session-manager -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about claude-session-manager
How do I install claude-session-manager in Claude Code?
Run npx skills add sugarforever/01coder-agent-skills --skill claude-session-manager -a claude-code, then read ~/.claude/skills/claude-session-manager/SKILL.md.
What does claude-session-manager do?
Reads Claude Code JSONL logs from ~/.claude/projects and converts them into structured Markdown files with conversation, digest, and detailed tool calls.
How do I pick one session from the archive?
Run the script with --mode specific --list-candidates --limit 20, choose a number from the table, then export with --pick N. Use the same set of filters in both commands.
Source text
SKILL.md · MIT
---
name: claude-session-manager
description: Manage Claude Code session transcripts from local JSONL storage, including listing candidate sessions, exporting full or selected sessions to organized Markdown, inspecting archives, and summarizing tool-call history. Use when the user asks to scan, parse, archive, inspect, recover, summarize, manage, or convert Claude Code sessions, `~/.claude/projects` data, `.jsonl` transcripts, tool-call history, or hard-to-read Claude Code conversation logs.
---
# Claude Session Manager
## Overview
Claude Code stores session transcripts as JSONL files under `~/.claude/projects/<project-key>/<session-id>.jsonl`. Use the bundled manager to list candidates or export sessions into project-organized Markdown transcripts with a digest, a clean user/Claude conversation, and linked tool-call details.
Default output folder: `~/.claude/session-markdown`. Tell the user before exporting there, and mention any custom output folder they requested.
## Quick Start
Let the user's wording choose the mode when it is clear; otherwise ask them to choose before exporting:
- Full mode: export all matching sessions. Use this for archive, backup, broad search, or "convert all sessions" requests.
- Specific mode: list candidate sessions first, ask the user to pick one, then export only that session.
Run from any directory:
```bash
python3 /path/to/claude-session-manager/scripts/manage_claude_sessions.py
```
Equivalent explicit form:
```bash
python3 /path/to/claude-session-manager/scripts/manage_claude_sessions.py \
--source ~/.claude/projects \
--output ~/.claude/session-markdown
```
Useful options:
- `--mode full`: export all matching sessions. This is the default.
- `--mode specific --list-candidates`: print a numbered candidate table and do not export.
- `--mode specific --pick N`: export the Nth candidate from the same filtered candidate list.
- `--project <text>`: only export project folders whose key contains this text.
- `--session <text>`: only export sessions whose id or filename contains this text.
- `--since YYYY-MM-DD`: only export sessions modified on or after this date.
- `--limit N`: export the N most recently modified matching sessions.
- `--include-tool-details-inline`: embed full tool inputs/results in the main session Markdown. By default, the main transcript keeps compact collapsible tool summaries and links full payloads through the sidecar file.
## Specific Mode Candidate Flow
Use this flow when the user wants one session, is unsure which session they need, or asks to inspect recent sessions before converting.
1. Run a candidate list command. Use `--limit 20` by default unless the user asks for a different count.
```bash
python3 /path/to/claude-session-manager/scripts/manage_claude_sessions.py \
--mode specific \
--list-candidates \
--limit 20
```
2. If the user gave a project hint, date, or session id fragment, pass it through the same filters:
```bash
python3 /path/to/claude-session-manager/scripts/manage_claude_sessions.py \
--mode specific \
--list-candidates \
--project my-repo \
--since 2026-06-01 \
--limit 20
```
3. Present the numbered candidate rows to the user. The candidate table includes modified time, project key, short session id, cwd, and first user prompt excerpt. These are the selection signals; do not ask the user to inspect raw JSONL paths.
4. After the user chooses a number, rerun with the exact same filters and `--pick N`:
```bash
python3 /path/to/claude-session-manager/scripts/manage_claude_sessions.py \
--mode specific \
--pick 3 \
--limit 20
```
If the user already gives an exact session id or unique fragment, use `--mode specific --session <id-or-fragment> --list-candidates` first when there is any ambiguity. Export with `--pick 1` only when the candidate list has exactly one match.
## Output Layout
The exporter writes:
```text
~/.claude/session-markdown/
├── index.md
└── <project-key>/
├── index.md
├── <session-id>.md
└── tool-details/
└── <session-id>.tools.md
```
Keep the original Claude project key as the folder name. It is stable and avoids guessing at path decoding.
Each session Markdown includes:
- Digest: source path, project key, session id, cwd, timestamps, event/message/tool counts, and first user prompt excerpt.
- Linked tool details file when tool calls or results exist.
- Timeline: all events are emitted under a `## Timeline` section as numbered third-level headers in ISO-8601 format: `### N. user - <ISO>` for user turns and `### N. assistant - <ISO>` for assistant turns.
- Message content in the main conversation should avoid Markdown heading syntax too; convert headings to bold lines outside code fences so regular Markdown readers do not render oversized headings inside the flow.
- Compact tool references such as `<tool_call_000001> Bash - command: npm test - result` inside the relevant assistant turn, with matching sections in the sidecar details file by default.
- Metadata and attachment events (`### N. attachment - <ISO>`, `### N. permission-mode`, `### N. file-history-snapshot`, `### N. last-prompt`, etc.) and `[thinking]` blobs in assistant turns are emitted as their own numbered events in the timeline. Readers should skip them as noise; they do not carry conversation content.
## Reading Exported Sessions
- Read the main session Markdown first. The conversation and compact tool references should be enough to understand the flow.
- Treat each `<tool_call_000001>` reference as a pointer into `tool-details/<session-id>.tools.md`.
- Only open the tool details file when exact command input, file content, search results, or full tool output matters.
- Do not load the whole sidecar by default for large sessions; search for the specific tool reference.
## Workflow
1. Confirm the source folder. Default to `~/.claude/projects`.
2. Ask the user to choose full mode or specific mode if they did not already make the choice.
3. Confirm or announce the output folder. Default to `~/.claude/session-markdown`.
4. For full mode, run the exporter script with any needed filters.
5. For specific mode, list candidates, get the user's chosen number, then export with `--pick`.
6. Report the number of sessions exported, output index path, and any parse warnings.
7. If the user wants a specific session explained, read the generated Markdown first; load the sidecar tool details only when exact tool inputs/results matter.
## Notes
- Treat transcript data as private. It can contain prompts, file contents, command output, secrets accidentally pasted into chat, and tool results.
- Do not delete or modify original `.jsonl` files.
- Prefer sidecar tool details for large sessions. Inline tool payloads can make Markdown hard to search and load.
© sugarforever · MIT · sugarforever/01coder-agent-skills