convez.ai
Hook
akihiko-shimura

claude-session-md

akihiko-shimura/claude-session-md

Ver no GitHub
InicialPluginScore · de 0 a 100

Claude Code plugin: auto-archive each session's transcript to readable Markdown (SessionEnd hook)

Instalação

$npx convez-ai akihiko-shimura/claude-session-md

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
—
Issues abertas
0
Contribuidores
1

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 .txt output (the post-compaction view) into the same folder.
  • Pure standard-library Python (python3). No external dependencies.

Why

  • Claude Code's /export only 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 after cleanupPeriodDays (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> then claude 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-archiver is the plugin name, claude-session-md is the marketplace name.
  • If you toggle mid-session, run /reload-plugins to 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 reads transcript_path from 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

Ver o original no GitHub

Bom para

Relacionados