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:

1. Multi-step operations - After completing a sequence of related actions
2. Feature implementations - After implementing new functionality
3. Bug fixes - After identifying and resolving issues
4. Refactoring - After restructuring code
5. Configuration changes - After modifying settings or environment
6. 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