Session Recorder

Records all Claude Code session interactions using a hybrid approach: automated hooks capture user messages and tool calls, while explicit self-reporting captures summaries of completed work.

How It Works

The session recorder uses two complementary mechanisms:

Automated Recording (via Hooks)

Four hooks automatically capture events without any action required:

Hook	Event	What It Records
`SessionStart`	Session begins	Creates log file, records session ID and start time
`UserPromptSubmit`	User sends message	Records user message content and timestamp
`PostToolUse`	Tool completes	Records tool name, arguments, and result
`SessionEnd`	Session ends	Updates end timestamp, calculates statistics

Self-Reporting (Explicit)

Self-report summaries of completed work to capture reasoning and context that hooks cannot observe. This provides the "why" behind the "what" recorded by hooks.

Self-Reporting Instructions

When to Self-Report

Report after completing significant work:

Multi-step operations - After completing a sequence of related actions
Feature implementations - After implementing new functionality
Bug fixes - After identifying and resolving issues
Refactoring - After restructuring code
Configuration changes - After modifying settings or environment
Research conclusions - After investigating and reaching decisions

How to Self-Report

Execute the helper script with summary information:

bash ${CLAUDE_PLUGIN_ROOT}/skills/session-recorder/scripts/add_assistant_response.sh \
  --summary "Brief description of what was accomplished" \
  --actions "Specific actions taken" \
  --tools "Tool1,Tool2,Tool3"

Arguments

Argument	Required	Description
`--summary`	Recommended	Brief description of accomplishment (1-2 sentences)
`--actions`	Optional	Comma-separated list of specific actions taken
`--tools`	Optional	Comma-separated list of tools used

Examples

After implementing a feature:

bash ${CLAUDE_PLUGIN_ROOT}/skills/session-recorder/scripts/add_assistant_response.sh \
  --summary "Implemented user authentication with JWT tokens" \
  --actions "Created auth middleware, added token validation, updated routes" \
  --tools "Write,Edit,Bash"

After fixing a bug:

bash ${CLAUDE_PLUGIN_ROOT}/skills/session-recorder/scripts/add_assistant_response.sh \
  --summary "Fixed race condition in database connection pool" \
  --actions "Added mutex lock, implemented connection timeout" \
  --tools "Edit,Read"

After research and decision:

bash ${CLAUDE_PLUGIN_ROOT}/skills/session-recorder/scripts/add_assistant_response.sh \
  --summary "Analyzed performance bottleneck - recommending Redis caching" \
  --actions "Profiled application, identified database queries as bottleneck"

After configuration:

bash ${CLAUDE_PLUGIN_ROOT}/skills/session-recorder/scripts/add_assistant_response.sh \
  --summary "Configured CI/CD pipeline with GitHub Actions" \
  --actions "Created workflow file, added test and deploy stages" \
  --tools "Write"

Log File Structure

Logs are stored in .claude/session_logs/session_YYYY-MM-DD.json:

{
  "session_id": "UUID",
  "start_timestamp": "ISO-8601",
  "end_timestamp": "ISO-8601",
  "project_path": "/absolute/path",
  "interactions": [
    {
      "interaction_id": "UUID",
      "timestamp": "ISO-8601",
      "type": "user_message|tool_call|tool_result|assistant_summary",
      "content": "...",
      "metadata": {}
    }
  ]
}

Interaction Types

Type	Source	Content
`user_message`	UserPromptSubmit hook	User's message text
`tool_call`	PostToolUse hook	Tool name and arguments
`tool_result`	PostToolUse hook	Tool output (truncated if large)
`assistant_summary`	Self-reporting	Summary, actions, tools used

Best Practices

Effective Summaries

Write summaries that capture intent and context:

Good: "Refactored authentication to use middleware pattern for better separation of concerns"
Poor: "Changed some files"
Good: "Fixed XSS vulnerability by sanitizing user input in comment form"
Poor: "Fixed bug"

When NOT to Self-Report

Skip self-reporting for:

Simple file reads (already captured by hooks)
Single tool calls (already captured by hooks)
Trivial operations with no decision-making
Intermediate steps within a larger operation (report at completion)

Frequency

Self-report at natural completion points, not after every action. One summary per logical unit of work is ideal.

Troubleshooting

Logs Not Created

Verify jq is installed:

which jq

Check directory permissions:

ls -la .claude/session_logs/

Self-Report Fails

Ensure script is executable:

chmod +x ${CLAUDE_PLUGIN_ROOT}/skills/session-recorder/scripts/add_assistant_response.sh

Test manually:

bash ${CLAUDE_PLUGIN_ROOT}/skills/session-recorder/scripts/add_assistant_response.sh --summary "Test"

Dependencies

jq - JSON processing (required)
uuidgen - UUID generation (usually pre-installed)

Install on Ubuntu/Debian:

sudo apt-get install jq uuid-runtime

Install on macOS:

brew install jq

Additional Resources

Reference Files

references/log-analysis.md - Guide to analyzing session logs
references/integration.md - Integrating with external tools

Scripts

scripts/add_assistant_response.sh - Self-reporting helper
hooks/session_init.sh - Session initialization
hooks/record_user_prompt.sh - User message recording
hooks/record_tool_result.sh - Tool usage recording
hooks/session_finalize.sh - Session finalization