claude-session-logger

Session logging, command history, and auto-naming for Claude Code

A hook-based extension for Claude Code that provides persistent session logging, automatic session naming from your working directory, and transcript discovery via symlinks.

Features

• Session Logging - Log all tool calls to session-specific files in ~/.claude/sesslogs/
• Auto-Naming - Sessions automatically named from working directory (e.g., c--code or my-project)
• Transcript Symlinks - Easy access to transcript files via transcript.jsonl in sesslog directories
• Run Tracking - Track multiple runs within a session with run markers
• Task Logging - Dedicated logging for TaskCreate/TaskUpdate/TaskList operations
• AI Rename - /renameAI command for AI-assisted session naming
• Session Info - /sessioninfo command to inspect current session state

Quick Start

Option 1: From GitHub (Recommended)

# Add the DazzleML marketplace (one-time)
claude plugin marketplace add "DazzleML/claude-session-logger"

# Install the plugin
claude plugin install session-logger@dazzle-claude-plugins

Option 2: From Local Clone

# Clone the repository
git clone https://github.com/DazzleML/claude-session-logger.git
cd claude-session-logger

# Install Python dependencies
pip install -r requirements.txt

# Add as local marketplace and install
claude plugin marketplace add "./"
claude plugin install session-logger@dazzle-claude-plugins

For more options and troubleshooting, see the Installation Guide.

Usage

Automatic Session Logging

Once installed, all Claude Code sessions are automatically logged to:

~/.claude/sesslogs/{session-name}__{session-id}_{user}/
├── .sesslog_*.log          # Session log (tool calls, timestamps)
├── .shell_*.log            # Shell command output
├── .tasks_*.log            # Task operations log
└── transcript.jsonl        # Symlink to transcript file

Auto-Naming Examples

Sessions are automatically named based on your working directory:

Generic folder names (code, project, local, src, etc.) trigger path-based naming with parent context.

Commands

/renameAI

AI-assisted session renaming. Analyzes your conversation and suggests a descriptive name.

> /renameAI
Analyzing conversation...
Suggested name: "AuthRefactorAndTests"

/sessioninfo

Display current session state including ID, name, run number, and log paths.

> /sessioninfo
Session ID: 833a100e-d959-47aa-9db2-d22fdb6d7659
Session Name: my-project
Run Number: 2
Sesslog Directory: ~/.claude/sesslogs/my-project__833a100e-..._User/

Tips

• First-time /rename: The built-in /rename command may fail on first use in a new session (before any tools run). Just run it again or use any tool first. See Known Quirks.

Configuration

The hook creates these directories automatically:

• ~/.claude/sesslogs/ - Session log files
• ~/.claude/session-states/ - Session state persistence
• ~/.claude/logs/ - Debug logs (when enabled)

Debug Logging

To enable debug logging, the hook writes to ~/.claude/logs/hook-debug.log. Check this file if hooks aren't working as expected.

Platform Support

Project Structure

This project follows the Claude Code plugin architecture:

claude-session-logger/
├── .claude-plugin/           # Plugin metadata
│   ├── plugin.json
│   └── marketplace.json
├── hooks/                    # Plugin hooks (for Claude Code)
│   ├── hooks.json
│   └── scripts/
│       ├── log-command.py
│       └── rename_session.py
├── commands/                 # Plugin commands
│   ├── renameAI.md
│   └── sessioninfo.md
├── scripts-repo/             # Development/repo scripts (not part of plugin)
│   ├── hooks/                # Git hooks (pre-commit, etc.)
│   ├── install-hooks.sh
│   ├── sync-versions.py      # Version synchronization tool
│   └── update-version.sh     # Git version string updater
├── version.py
└── ...

How It Works

1. SessionStart Hook - On session start:

   • Creates sesslog directory
   • Auto-names session from working directory (if unnamed)
   • Creates transcript symlink
   • Initializes run tracking

2. PostToolUse Hook - After each tool call:

   • Logs tool name, timestamp, and context to sesslog
   • Tracks task operations separately
   • Updates session state

3. Session State - Persisted in ~/.claude/session-states/:

   • {session-id}.json - Full session state
   • {session-id}.name-cache - Cached session name
   • {session-id}.run - Current run number
   • {session-id}.started - Session start flag

Comparison with cchistory

cchistory is a great tool that extracts shell commands from Claude Code's transcript files after the fact.

claude-session-logger takes a different approach:

When to use which:

• cchistory: Quick extraction of shell commands from past sessions
• claude-session-logger: Real-time structured session management — watch commands as they happen, copy-paste on the fly, spot-check Claude's actions live

These tools are complementary — you might use cchistory for quick historical lookups and claude-session-logger for real-time monitoring and session organization.

Contributing

Contributions welcome! Please open an issue or submit a pull request.

See Developer Guide for:

• Local plugin testing workflow
• Version management with sync-versions.py
• Debugging tips and session state files
• Pull request checklist

Like the project?

Related Projects

• cchistory - Extract shell commands from Claude Code transcripts
• dazzle-filekit - Cross-platform file operations toolkit
• Claude Code - Anthropic's CLI for Claude

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.