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

Note: Requires the native Claude Code installer, not the npm version. See Troubleshooting if hooks don't run.

For more options and troubleshooting, see the Installation Guide.

Updating

claude plugin install does not update an already-installed plugin. It prints
already installed, exits 0, and leaves the version unchanged. That reads as
success, so it is easy to sit on a months-old version without realizing it.

Use claude plugin update:

# Refresh the marketplace clone, then update the plugin
claude plugin marketplace update dazzle-claude-plugins
claude plugin update session-logger@dazzle-claude-plugins

Restart Claude Code to load the new version. To check what you are running:

claude plugin list

If you run Claude Code as more than one OS user (for example root as well as your
own account), each has a separate ~/.claude/ tree and must be updated separately:

sudo -H claude plugin marketplace update dazzle-claude-plugins
sudo -H claude plugin update session-logger@dazzle-claude-plugins

The -H matters — it points HOME at the target user's home so you update the
intended config tree.

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
│       ├── run-hook.mjs          # Cross-platform Node.js launcher
│       └── rename_session.py
├── commands/                 # Plugin commands
│   ├── renameAI.md
│   └── sessioninfo.md
├── scripts-repo/             # Git subtree from DazzleTools/git-repokit-common
│   ├── hooks/                # Git hooks (pre-commit, etc.)
│   ├── install-hooks.sh
│   ├── sync-versions.py      # Version sync (configured via pyproject.toml)
│   ├── update-version.sh     # Legacy version string updater
│   └── local/                # Project-local tooling (not from upstream)
│       ├── audit_codebase.py    # git-commit function-diff tool
│       ├── dev-refresh.py       # Clear plugin cache during development
│       ├── diff-harness.py      # Differential test harness for sync-versions
│       └── hooks/pre-commit-basic
├── pyproject.toml            # Configures sync-versions.py extra-targets, etc.
├── 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.