improve-session

Session Improver

Analyze Claude Code session transcripts and generate actionable recommendations to reduce token waste, prevent linter loops, and automate repetitive workflows.

Usage

• /improve-session — Analyze the most recent session
• /improve-session <session-id> — Analyze a specific past session
• /improve-session --current — Analyze the current live session

Workflow

Phase 1: Parse the session

Run the parser script to extract a structured summary:

ruby "${CLAUDE_SKILL_DIR}/scripts/parse-session.rb" <session-id-or-path>

If CLAUDE_SKILL_DIR is not set, fall back to the skill's location relative to this file. You can detect it by looking at the directory containing this SKILL.md.

The argument is either:

• A session UUID (found in ~/.claude/history.jsonl)
• --current for the most recent session
• A direct path to a .jsonl file

The script outputs JSON with these sections:

• linter_loops — Linter smells that triggered multiple edit cycles
• tool_failures — Tools that failed and were retried
• repeated_sequences — Workflow patterns that repeated 3+ times
• large_reads — Files read 3+ times in the session
• hook_failures — Hooks that failed repeatedly
• permission_events — Tools that needed human approval

Phase 2: Read context

For each finding, read relevant project files to understand what's already configured:

• The project's CLAUDE.md (if the session had a project path)
• The project's .claude/settings.json and .claude/settings.local.json
• The project's .claude/hooks/ directory
• Any .reek.yml, .rubocop.yml, eslint.config.*, etc.
• The global ~/.claude/CLAUDE.md
• The global ~/.claude/settings.json

Phase 3: Generate recommendations

Read the reference files for patterns and templates (relative to this SKILL.md):

• references/analyzers.md — What each finding type means
• references/fix-templates.md — Templates for each fix type
• references/ruby-linter-patterns.md — Ruby-specific patterns