Crate claude_storage 

claude_storage

CLI tool for exploring and analyzing Claude Code’s filesystem-based conversation storage.

Files

File / Directory	Responsibility
Cargo.toml	Crate manifest: deps, features, build script
build.rs	Transforms YAML command definitions to static PHF registry
unilang.commands.yaml	Command definitions (9 commands)
src/	CLI pipeline, command routines, binary entry points
tests/	Integration and parameter validation tests (242 tests)
docs/	Behavioral requirements: features, CLI reference, operation docs
task/	Crate-level task tracking
examples/	Usage examples for storage API
changelog.md	Notable changes by version

overview

This crate provides a command-line interface for querying Claude Code’s conversation storage at ~/.claude/. It wraps the claude_storage_core library with an interactive REPL and one-shot command interface.

v1.0 Status: Core library (claude_storage_core) is production-ready with comprehensive validation (122 tests, production session parsing). CLI wrapper commands .status, .list, and .count are fully validated. For programmatic access or advanced usage, we recommend using the claude_storage_core library API directly (see “library api” section below).

Extraction context: This is the CLI-focused crate after extracting core library functionality to claude_storage_core (2025-11-29).

installation

cargo install --path . --features cli

Or run directly:

cargo run --features cli

usage

repl mode (interactive)

cargo run --features cli

claude_storage> .status
Storage: "/home/user/.claude"
Projects: 230 (UUID: 14, Path: 216)
Sessions: 7546 (Main: 1061, Agent: 6485)
Entries: 323231

claude_storage> .list target::projects
UUID projects: 14
Path projects: 216

claude_storage> .count target::sessions
Total sessions: 7546

claude_storage> exit

one-shot mode (scripting)

# Get storage statistics
cargo run --features cli -- .status

# Count projects
cargo run --features cli -- .count target::projects

# List projects with filtering
cargo run --features cli -- .list target::projects filter::path

# Show session details
cargo run --features cli -- .show session::abc123 verbosity::2

commands

.status

Show storage statistics (projects, sessions, entries, tokens).

Parameters:

• verbosity::N (0-5, default 1) - Detail level

Example:

.status verbosity::2

.list

List projects or sessions with optional filtering.

Parameters:

• type::{uuid|path|all} (optional, default: all) - Filter by project type
• verbosity::N (0-5, default: 1) - Output detail level
• sessions::{0|1} (optional, auto-detected) - Show sessions (auto-enabled when session filters provided)
• path::{value} (optional) - Filter projects by path (supports smart resolution, see below)
• agent::{0|1} (optional) - Filter sessions by type (auto-enables session display)
• min_entries::N (optional) - Filter sessions by minimum entry count (auto-enables session display)
• session::{substring} (optional) - Filter sessions by ID substring (auto-enables session display)

Path Parameter - Smart Resolution:

The path:: parameter supports both shell-style path resolution and pattern matching:

• Special paths (resolved to absolute paths):

  • path::. → Current working directory
  • path::.. → Parent directory
  • path::~ → Home directory
  • path::~/subdir → Home directory + relative path

• Patterns (substring matching):

  • path::assistant → Match any path containing “assistant”
  • path::storage → Match any path containing “storage”

Examples:

# List all projects
.list

# List path-based projects only
.list type::path

# Path resolution (current directory)
cd /home/user/project
.list path::.

# Path resolution (parent directory)
.list path::..

# Path resolution (home directory)
.list path::~

# Pattern matching (backward compatible)
.list path::assistant

# Filter sessions with auto-enable
.list session::commit          # Auto-enables session display
.list agent::1 min_entries::10 # Agent sessions with 10+ entries

# Combine filters
.list path::claude_storage session::default

.show

Display session or project details with conversation content by default (REQ-011: Content-First Display).

Smart Behavior (adapts to parameters):

• No parameters → Shows current directory project (all sessions)
• session_id only → Shows that session in current project with conversation content
• project only → Shows that project (all sessions)
• Both parameters → Shows that session in that project with conversation content

Parameters:

• session_id::{uuid-or-agent-id} (optional) - Session UUID or agent-{hex}
• project::{path-or-id} (optional) - Project path or UUID (default: current directory)
• verbosity::N (0-5, default 1) - Output detail level
• entries::1 (optional) - Show all entries (backward compat with old UUID list format)
• metadata::1 (optional) - Show metadata only (old behavior, no conversation content)

Default Behavior (NEW): Shows actual conversation content in readable chat-log format. No parameters needed to read messages.

Examples:

# Show current directory project (all sessions)
cd /home/user/project
.show

# Show session with conversation content (default)
.show session_id::abc123

# Show session in different project
.show session_id::abc123 project::/home/user/project

# Metadata only (old behavior)
.show session_id::abc123 metadata::1

# Increase verbosity for metadata footer
.show session_id::abc123 verbosity::2

Content Format:

Session: 79f86582... (2893 entries)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[2025-12-02 09:57] User:
last 3 biig tasks solved in this context?

[2025-12-02 09:57] Assistant:
I'll analyze the recent conversation history...

**Recent Major Tasks Completed:**
1. **tree_fmt Standardization**
2. **Path Filter Bug Investigation**
3. **Test Suite Fixes**

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

.count

Fast counting operations (projects, sessions, entries).

Parameters:

• target::projects|sessions|entries (required)
• project::{id} (for sessions/entries)
• session::{id} (for entries)

Examples:

.count target::projects
.count target::sessions project::-home-user-pro
.count target::entries session::abc123

.search

Search session content for query string.

Parameters:

• query::{text} (required) - Search query (case-insensitive by default)
• project::{id} (optional) - Limit search to specific project
• session::{id} (optional) - Limit search to specific session
• case_sensitive::1 (optional) - Enable case-sensitive matching
• entry_type::user|assistant (optional) - Filter by entry type
• verbosity::N (0-5, default 1) - Detail level

Examples:

.search query::error
.search query::"session management" case_sensitive::1
.search query::implement project::-home-user-pro

.export

Export session to file (markdown, JSON, or text).

Parameters:

• session_id::{id} (required) - Session ID to export
• output::{path} (required) - Output file path
• format::markdown|json|text (optional, default: markdown) - Export format
• project::{id} (optional) - Project ID if not in current directory

Formats:

• markdown (.md) - Human-readable with metadata and formatted entries
• json (.json) - Machine-readable structured format
• text (.txt) - Simple conversation transcript

Examples:

.export session_id::-default_topic output::conversation.md
.export session_id::abc123 format::json output::session.json
.export session_id::xyz789 format::text output::transcript.txt project::-home-user-pro

Note: Sessions may contain non-conversation metadata entries (queue-operation, summary) which are automatically skipped during export. Only conversation entries (user/assistant messages) are included in the exported output.

.session

Check if a directory has Claude Code conversation history.

Parameters:

• path::{value} (optional, default: current directory) - Directory to check

Examples:

# Check current directory
.session

# Check specific directory
.session path::/home/user/project

.sessions

Show active-session summary by default, or list sessions with scope control when any explicit parameter is given (session-first view).

Scope semantics:

Scope	Project qualifies when
local	project path == base path
relevant	base path is under the project path (ancestor)
under	project path is under the base path (subtree) (default)
global	all projects regardless of path

Parameters:

• scope::{local|relevant|under|global} (optional, default: under) - Discovery scope
• path::{value} (optional, default: cwd) - Base path for scope resolution
• session::{substring} (optional) - Filter by session ID substring
• agent::{0|1} (optional) - Filter by type (0=main only, 1=agent only)
• min_entries::N (optional) - Minimum entry count threshold
• verbosity::N (0-5, default: 1) - Output detail level

Default output (summary mode):

Active session  {8-char-id}  {age}  {N} entries
Project  {rel-path}

Last message:
  {text or first30...last30 if > 50 chars}

No active session found. when scope has no sessions.

List output (any explicit parameter given):

• verbosity 0: raw session IDs (one per line)
• verbosity 1: family-grouped list with path headers (default); agents shown as [N agents: N×Type] per root
• verbosity 2+: full UUIDs, agents tree-indented under their parent session

Examples:

# Active session summary (default — no args)
.sessions

# Sessions for all projects under ~/pro
.sessions scope::under path::~/pro

# All sessions across entire storage
.sessions scope::global

# All agent sessions with 50+ entries
.sessions scope::global agent::1 min_entries::50

scripting integration

Exit codes:

• 0: Success
• 1: Error

Examples:

# Get project count
PROJECT_COUNT=$(cargo run --features cli -- .count target::projects | grep -oP '\d+')

# Check if session exists
if cargo run --features cli -- .show session::abc123 &>/dev/null; then
  echo "Session exists"
fi

# Export statistics
cargo run --features cli -- .status verbosity::3 > storage_stats.txt

library api

For programmatic access to Claude Code storage, use claude_storage_core directly:

[dependencies]
claude_storage_core = "1.0.0"
# Or for local development:
# claude_storage_core = { path = "../claude_storage_core" }

use claude_storage_core::{ Storage, ProjectId };

fn main() -> claude_storage_core::Result< () >
{
  let storage = Storage::new()?;
  for project in storage.list_projects()?
  {
    println!( "Project: {:?}", project.id() );
  }
  Ok( () )
}

architecture

Dependencies:

• claude_storage_core - Core library for all storage operations
• unilang - CLI framework for command parsing
• phf - Perfect hash functions for static command registry

Build system:

• build.rs - Transforms YAML command definitions to static PHF registry
• unilang.commands.yaml - Command definitions (9 commands)
• Generated code: Static command map with O(1) lookup

Command routines (src/cli/mod.rs):

• status_routine - Global statistics aggregation
• list_routine - Filtered listing
• show_routine - Session detail display
• show_project_routine - Project detail display
• count_routine - Fast counting
• search_routine - Content search
• export_routine - Session export
• session_routine - Directory session check
• sessions_routine - Scoped session listing

documentation

• Documentation: docs/ - Behavioral requirements, CLI reference, feature docs (see docs/entities.md for index)
• Migration guide: docs/MIGRATION.md - Migration from monolithic crate
• Format docs: docs/ - Storage organization, file formats, advanced topics
• Integration guide: docs/integration_guide.md - Library integration examples

testing

Core library tests: 105 tests in claude_storage_core crate

• Entry parsing and validation
• Path encoding/decoding
• JSON parser
• Filtering system
• Content search
• Export functionality (markdown, JSON, text)
• Statistics aggregation
• Bug reproducers with comprehensive documentation

CLI tests: 17 integration tests

• Storage operations tests (global stats, project listing)
• Session operations tests (show, stats, entry counts)
• Counting operations tests (projects, sessions, entries)
• Full workflow integration test
• CLI sanity tests (build, features)

license

MIT

claude_storage - CLI Tool for Claude Code Storage

Command-line interface for exploring and analyzing Claude Code’s filesystem-based storage.

Overview

This crate provides a CLI tool for querying Claude Code’s conversation storage at ~/.claude/. It wraps the claude_storage_core library with an interactive REPL and one-shot command interface.

Extraction context: This is the CLI-focused crate after extracting core library functionality to claude_storage_core (2025-11-29). All storage access logic now lives in the core library; this crate provides the command-line interface.

Usage

REPL mode (interactive):

cargo run --features cli
> .status
> .list target::projects
> exit

One-shot mode (scripting):

cargo run --features cli -- .status
cargo run --features cli -- .count target::projects

CLI Commands

• .status - Show storage statistics (projects, sessions, entries, tokens)
• .list - List projects or sessions with optional filtering
• .show - Display details about a specific session
• .count - Fast counting of entries, sessions, or projects

Library API

For programmatic access to Claude Code storage, use the claude_storage_core crate directly:

use claude_storage_core::{ Storage, ProjectId };

fn main() -> claude_storage_core::Result< () >
{
  let storage = Storage::new()?;
  for project in storage.list_projects()?
  {
    println!( "Project: {:?}", project.id() );
  }
  Ok( () )
}

Re-exports

pub use cli::parse_project_parameter;

Modules

cli

CLI command routines for claude_storage

cli_main

Binary entry point logic shared by the claude_storage and clg targets.

stats

Statistics types for Claude Code storage

Structs

AssistantMessage

Assistant message content

Entry

A single conversation entry (one line in a JSONL file)

GlobalStats

Global statistics across all projects and sessions

Project

A project (directory containing session JSONL files)

ProjectStats

Statistics for a single project

Session

A conversation session (one JSONL file)

SessionStats

Statistics for a single session

Storage

Main storage interface for Claude Code’s filesystem database

ThinkingMetadata

Metadata about thinking/reasoning process

UserMessage

User message content

Enums

ContentBlock

Content block in assistant message

EntryType

Type of conversation entry

Error

Error type for claude_storage operations

JsonValue

JSON value types

MessageContent

Message content (user or assistant)

ProjectId

Identifier for a project (UUID or filesystem path)

Constants

COMMANDS_YAML

Absolute path to this crate’s command definitions YAML.

Functions

decode_path

Decode a storage directory name to a filesystem path

encode_path

Encode a filesystem path to a storage directory name

parse_json

Parse JSON string to JsonValue

register_commands

Register claude_storage commands into an existing registry.

Type Aliases

Result

Result type used throughout claude_storage