Claude Session Summary

A Claude Code plugin that automatically generates running session summaries when Claude Code stops. Summaries are stored per-project under `~/.local/share/claude-sessions/{PROJECT_NAME}/` and can be viewed via tmux popup (`prefix + S`) using glow for markdown rendering.

What This Skill Does

This plugin hooks into Claude Code's Stop event to automatically generate a comprehensive markdown summary of your coding session. The summary includes what was accomplished, changes made, and context for future sessions. Each summary is stored with a unique session ID and a `latest.md` symlink always points to the most recent summary for quick access.

Instructions

When implementing this plugin, follow these steps:

1. **Create the plugin structure:**

- Create `.claude-plugin/plugin.json` with a Stop hook registration (5-second timeout)

- Create `.claude-plugin/marketplace.json` with plugin metadata

- Create `scripts/session-summary.zsh` containing all plugin logic

2. **Implement the Stop hook handler (`session-summary.zsh`):**

- Read hook JSON input (session_id, cwd) from stdin with 0.5s timeout

- Immediately fork to background using `&!` (zsh disown) to survive the 5s hook timeout

- Call `claude --continue --model haiku --output-format=json --disableAllHooks` to generate the summary

- Use `--disableAllHooks` to prevent recursive hook invocation

- Parse the JSON response using Python with `strict=False` to handle control characters in Claude's output (jq cannot handle unescaped control chars)

- Extract the summary text from the JSON response

- Write the summary to `~/.local/share/claude-sessions/{PROJECT_NAME}/{SESSION_ID}.md`

- Update the `latest.md` symlink to point to this new summary

- Log cost and token usage data to `summary.log`

- Return 0 immediately from the hook regardless of background work outcome

3. **Key design considerations:**

- The background fork (`&!`) is CRITICAL - without it, the 5-second hook timeout will kill the Claude API call

- Use Python instead of jq for JSON parsing because Claude's output may contain unescaped control characters that break jq

- The `--disableAllHooks` flag prevents the summary generation from triggering another Stop hook recursively

- Create the session directory if it doesn't exist

- Handle both successful and failed API calls gracefully

4. **Create installation tooling:**

- Makefile with targets: `install`, `uninstall`, `clean`, `reinstall`

- `make install` should add the marketplace and install via `claude` CLI

- `make uninstall` should remove the plugin and marketplace

- `make clean` should be like uninstall but suppress errors

- `make reinstall` should run clean then install

5. **Add tmux integration (optional but recommended):**

- Add tmux keybinding (e.g., `prefix + S`) to display latest summary in popup

- Use glow for markdown rendering if available, fall back to cat

- Popup should show `~/.local/share/claude-sessions/{PROJECT_NAME}/latest.md`

6. **Runtime dependencies:**

- zsh (for the hook script)

- jq (for JSON manipulation)

- python3 (for JSON parsing with control character handling)

- Claude Code CLI (claude command)

- glow (optional, for markdown rendering in tmux)

Example Usage

After installation:

```bash

Install the plugin

make install

Work in Claude Code as normal

When you stop Claude Code, a summary is automatically generated

View latest summary via tmux (if configured)

Press: prefix + S

Or view manually

cat ~/.local/share/claude-sessions/my-project/latest.md

Reinstall after updates

make reinstall

```

File Structure

```

.claude-plugin/

plugin.json # Hook registration

marketplace.json # Marketplace metadata

scripts/

session-summary.zsh # Main plugin logic (~96 lines)

Makefile # Installation commands

.github/workflows/

validate.yml # CI validation

```

Important Notes