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