What is claude-code:session?

A tool to view the active Claude Code session and search its conversation history using digest, search, stats, and errors, plus direct per-session inspection.

What output formats are supported?

Text by default; you can use --format json to get structured JSON for piping or automation.

Where are session logs stored?

Session logs live at ~/.claude/projects/ / .jsonl, with lines representing individual events like user messages, assistant replies, progress, and summaries.

claude-code:session

npx machina-cli add skill bendrucker/claude/session --openclaw

Files (1)

SKILL.md

2.4 KB

Session CLI

Search and analyze Claude Code conversation history.

Current Session ID: ${CLAUDE_SESSION_ID}

Commands

CLI=${CLAUDE_PLUGIN_ROOT}/skills/session/cli

digest

List recent sessions with summaries.

# Today's sessions
bun $CLI digest --after today

# View the current session
bun $CLI digest --session $CLAUDE_SESSION_ID

# JSON output for piping
bun $CLI digest --after today --format json | jq '.[].sessionId'

search

Search conversations by keyword.

bun $CLI search "error handling"
bun $CLI search "auth" --after yesterday

stats

Show tool usage statistics.

bun $CLI stats --after "last week"
bun $CLI stats --sort rate  # Sort by error rate

errors

List tool errors.

bun $CLI errors --after "last week"
bun $CLI errors --type failure  # Exclude user rejections
bun $CLI errors --aggregate     # Group by error message

Common Options

--after DATE - Filter by date (e.g., "today", "yesterday", "last week")
--before DATE - Filter by date
--project PATH - Filter by project path
--limit N - Maximum results
--format FORMAT - Output format: text (default) or json
--log-level LEVEL - Telemetry output: debug (logs) or trace (logs + spans)
--log-file PATH - Write traces and logs to a JSONL file

Direct Session Inspection

For deeper inspection of a single session, use jq directly:

# Session file path pattern
FILE=~/.claude/projects/-Users-ben-src-project/$CLAUDE_SESSION_ID.jsonl

# List all tool uses
jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | .name' < "$FILE"

# Get the session summary
jq -r 'select(.type == "summary") | .summary' < "$FILE"

# Count message types
jq -r '.type' < "$FILE" | sort | uniq -c

Session File Structure

Session logs are stored in ~/.claude/projects/<encoded-path>/<session-id>.jsonl where the encoded path replaces / with -.

Each line is a JSON object with a type field:

user - User messages (check isMeta for system messages)
assistant - Claude responses with message.content[] array
progress - Tool execution progress and hook events
summary - Conversation summaries

Source

git clone https://github.com/bendrucker/claude/blob/main/plugins/claude-code/skills/session/SKILL.mdView on GitHub

Overview

Claude-code:session lets you view the active session and search conversation history. It is essential for debugging sessions, auditing activity, and summarizing recent work from Claude Code conversations. The CLI exposes digest, search, stats, and errors, plus direct per-session inspection with jq.

How This Skill Works

The skill exposes a CLI at CLAUDE_PLUGIN_ROOT/skills/session/cli. Use commands like digest, search, stats, and errors to explore sessions; for deep inspection, jq parses per-session JSONL files stored under ~/.claude/projects/ with the encoded path and session ID.

When to Use It

Debug a failing tool usage by inspecting recent sessions
Review conversations to summarize work for a handoff or report
Find specific discussions or keywords across sessions
Audit user activity for compliance or governance
Compare activity and tool usage across multiple sessions

Quick Start

Step 1: Set CLI path to the session CLI: CLI=${CLAUDE_PLUGIN_ROOT}/skills/session/cli
Step 2: List today's sessions: bun $CLI digest --after today
Step 3: Inspect the current session: bun $CLI digest --session $CLAUDE_SESSION_ID

Best Practices

Use --after and --before to narrow the timeframe and --format json for machine parsing
Pipe outputs to jq to extract exact fields (e.g., sessionId, summary)
Verify the target session with --session $CLAUDE_SESSION_ID before deep inspection
Inspect the per-session JSONL file directly for a granular view of messages
Be mindful of sensitive data when exporting or sharing session logs

Example Use Cases

Debug an intermittent error by running digest --after today and inspecting the current session
Audit recent conversations for a project to prepare a retrospective
Retrieve a session summary and count of message types for a project sprint
Find all tool uses related to a keyword using search and then export results as json
Export session data to JSONL/JSON for compliance or archival review

Frequently Asked Questions

Add this skill to your agents