claude-session-md
akihiko-shimura/claude-session-md
Claude Code plugin: auto-archive each session's transcript to readable Markdown (SessionEnd hook)
Instalação
npx convez-ai akihiko-shimura/claude-session-md1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
claude-session-md
A Claude Code plugin — session-md-archiver.
At the end of every session (the SessionEnd hook) it automatically archives that
session's transcript (JSONL) into readable Markdown.
- Output goes to
<project>/claude-session-log/:<start-local>_session-<id>.md… the conversation (👤 User / 🤖 Assistant, local timestamps, compaction boundaries marked)<...>_blocks/*.md… full text of long tool I/O and thinking (the conversation keeps a preview + link)INDEX.md… a table of all archived sessions
- It also sweeps
/export.txtoutput (the post-compaction view) into the same folder. - Pure standard-library Python (
python3). No external dependencies.
Why
- Claude Code's
/exportonly produces the post-compaction view, so you can't get the full history of a long session from it. - The raw history lives in
~/.claude/projects/<enc>/<session>.jsonl, but those files are removed aftercleanupPeriodDays(default 30 days) and are not pleasant to read as JSONL. - → This plugin converts each session's JSONL into readable Markdown at session end and keeps it.
Install
# 1) Add this repo as a marketplace
claude plugin marketplace add https://github.com/akihiko-shimura/claude-session-md
# 2) Install the plugin (use user scope to enable it across all projects)
claude plugin install session-md-archiver --scope user
For team-wide, per-project sharing use --scope project (written to .claude/settings.json,
auto-applied for anyone who clones the repo).
After installing, claude-session-log/ is generated automatically at the end of each session.
On success you'll see a confirmation like:
📝 Archived session → claude-session-log/2026-06-11_2216_session-b71d954c.md (1948 msgs, 241 externalized, 3 compactions)
Local test (before publishing):
claude plugin marketplace add <absolute path to this dir>thenclaude plugin install session-md-archiver.
Enable / disable
You can toggle the plugin on and off at any time without uninstalling — handy when you want to pause archiving.
Interactive: run /plugin → Installed tab → select it → enable / disable / uninstall.
Commands (work as /plugin … or claude plugin …):
# Temporarily disable (stops the SessionEnd archive; config and script stay in place)
/plugin disable session-md-archiver@claude-session-md
# Re-enable
/plugin enable session-md-archiver@claude-session-md
# Check state (filter with --enabled / --disabled)
/plugin list
# Remove completely (unlike disable, this uninstalls it)
/plugin uninstall session-md-archiver@claude-session-md
session-md-archiveris the plugin name,claude-session-mdis the marketplace name.- If you toggle mid-session, run
/reload-pluginsto apply immediately. - Disable keeps it installed (re-enable restores it instantly); this differs from uninstalling.
Safety: never commit your session logs
Session transcripts can contain sensitive content, so committing them by accident is a real
risk. To prevent that, when the plugin writes to a project that is a git repository, it
automatically adds claude-session-log/ to that project's .gitignore (idempotently — it
won't duplicate an existing rule, and it leaves non-git directories untouched). When it adds the
rule you'll see · added claude-session-log/ to .gitignore in the confirmation message.
To opt out (e.g. you manage ignore rules yourself), set the environment variable:
export SESSION_MD_NO_GITIGNORE=1
Layout
.claude-plugin/
plugin.json # plugin manifest
marketplace.json # makes this repo installable as a marketplace
hooks/
hooks.json # SessionEnd hook (references the script via ${CLAUDE_PLUGIN_ROOT})
scripts/
session_to_md.py # JSONL → Markdown converter (pure standard library)
How it works
- The hook fires on
SessionEnd(once, when the session ends). The script readstranscript_pathfrom the hook JSON on stdin; if absent, it falls back to the newest*.jsonl(by mtime) under~/.claude/projects/<enc>/. - Timestamps are rendered in the machine's local timezone.
- Blocks longer than 1500 characters (tool input / result / thinking / long user messages) are moved
to
*_blocks/as full files; the conversation keeps a 600-character preview + link. - Idempotent (overwrites the same-named output, regenerates its own
*_blocks/). All exceptions are swallowed and it always exits 0, so it never breaks a session.
Prior art
There are several excellent manual Claude Code transcript → Markdown converters, e.g.
kiliman/claude-transcript,
daaain/claude-code-log, and
annenpolka/cclog.
This project's focus is different: it is a plugin that runs automatically at SessionEnd
(no manual step) and externalizes long blocks into linked files.
License
MIT