Crate claude_storage_core

Expand description

§claude_storage_core

Pure library for Claude Code’s filesystem-based storage access (zero dependencies).

§Responsibility Table

File	Responsibility
`Cargo.toml`	Crate manifest and dependency configuration
`src/`	Core library implementation (13 modules)
`tests/`	Test suite for storage access logic
`docs/`	Behavioral requirements: features, invariants, API, algorithms, data structures
`examples/`	Usage examples for the storage API
`verb/`	Shell scripts for each `do` protocol verb.

§overview

This is the core library extracted from the monolithic claude_storage crate (2025-11-29). It provides safe, structured read/write access to Claude Code’s conversation storage at ~/.claude/ with zero runtime dependencies.

§features

Zero dependencies: No runtime dependencies for fast compilation and minimal attack surface
Hand-written JSON parser: ~690 lines, supports all JSON types, Unicode escaping
Path encoding/decoding: Filesystem path encoding for storage directories
Statistics aggregation: Fast counting and analytics without full parsing
Format validation: JSONL structure validation with detailed error messages
Safety guarantees: Append-only operations, atomic writes, graceful error handling

§usage

[dependencies]
claude_storage_core = { workspace = true }

use claude_storage_core::{ Storage, ProjectId };

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

    // List sessions within project
    for mut session in project.sessions()?
    {
      println!( "  Session: {}", session.id() );
      println!( "  Entries: {}", session.count_entries()? );
    }
  }
  Ok( () )
}

§architecture

Storage model: Claude Code uses filesystem-native storage at ~/.claude/

~/.claude/
├── projects/
│   ├── {uuid}/           # UUID projects (web/IDE sessions)
│   └── -{path-encoded}/  # Path projects (CLI sessions)
├── history.jsonl
└── .credentials.json

Core types:

Storage - Entry point for all operations
Project - Directory containing sessions (UUID or path-based)
Session - Single conversation (JSONL file)
Entry - Individual message (user or assistant)

Path encoding: /home/user/pro → -home-user-pro

§performance

Lazy loading: Entries loaded on-demand, not at construction
Fast counting: 100x speedup (~5ms vs 500ms for 1000 entries)
Selective parsing: Statistics without loading all data
JSON parser: ~80ns per operation

§testing

51 tests total (45 unit + 3 bug + 3 doc):

cargo nextest run --all-features  # 48 tests
cargo test --doc --all-features   # 3 doc tests
cargo clippy --all-targets --all-features -- -D warnings

claude_storage: CLI tool wrapping this library for command-line storage exploration
claude_profile: Account and token management (uses this for session detection)

§migration

From monolithic claude_storage:

[dependencies]
- claude_storage = { path = "../claude_storage" }
+ claude_storage_core = { workspace = true }

- use claude_storage::{ Storage, ProjectId };
+ use claude_storage_core::{ Storage, ProjectId };

See ../claude_storage/docs/MIGRATION.md for complete migration guide.

§documentation

Documentation: docs/ - Behavioral requirements, API contracts, algorithms, invariants
Format docs: ../claude_storage/docs/ - JSONL format, storage organization, advanced features
Examples: examples/ - Usage examples and integration patterns

§license

MIT

§`claude_storage_core` - Claude Code Storage Access Library

Pure library for structured read/write access to Claude Code’s filesystem-based storage.

§Overview

Claude Code stores conversations in a filesystem-based “database” at ~/.claude/, using JSONL (JSON Lines) files for conversation history and directory hierarchies for project organization. This crate provides safe, structured access to that storage.

Zero dependencies: This library has no runtime dependencies for fast compilation and minimal attack surface. All parsing is hand-written using std only.

§Architecture

Claude Code’s storage is filesystem-native:

Projects: Directories in ~/.claude/projects/
Sessions: JSONL files within project directories
Entries: Individual JSON objects (one per line in JSONL files)

§Core Types

Storage: Entry point for all storage operations
Project: Represents a project (UUID or path-based)
Session: Represents a conversation session (JSONL file)
Entry: Individual conversation entry (user or assistant message)

§Safety Guarantees

Append-only: Write operations only append to JSONL files (no modification/deletion)
Atomic writes: Uses temp file + rename pattern
Format validation: All reads validate JSONL structure
Path encoding: Automatic encoding/decoding of filesystem paths

§Quick Start

use claude_storage_core::{ Storage, ProjectId };

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

    // List sessions within project
    for mut session in project.sessions()?
    {
      println!( "  Session: {}", session.id() );
      println!( "  Entries: {}", session.entries()?.len() );
    }
  }
  Ok( () )
}

§Extraction Context

This is the core library extracted from the monolithic claude_storage crate (2025-11-29). The CLI functionality remains in the claude_storage crate, which depends on this core library.

Re-exports§

pub use continuation::check_continuation;
pub use continuation::to_storage_path_for;
pub use stats::SessionStats;
pub use stats::GlobalStats;
pub use stats::ProjectStats;

Modules§

continuation: Continuation detection for Claude Code sessions.
stats: Statistics types for Claude Code storage

Structs§

AssistantMessage: Assistant message content
Entry: A single conversation entry (one line in a JSONL file)
Project: A project (directory containing session JSONL files)
ProjectFilter: Project-level filtering
SearchFilter: Search filter for session content
SearchMatch: Search match result with context
Session: A conversation session (one JSONL file)
SessionFilter: Session-level filtering
Storage: Main storage interface for Claude Code’s filesystem database
StringMatcher: Zero-dependency case-insensitive substring matcher
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
ExportFormat: Export format specification
JsonValue: JSON value types
MessageContent: Message content (user or assistant)
ProjectId: Identifier for a project (UUID or filesystem path)

Functions§

decode_path: Decode a storage directory name to a filesystem path
encode_path: Encode a filesystem path to a storage directory name
export_session: Export a session to a writer
export_session_to_file: Export a session to a file
parse_json: Parse JSON string to JsonValue

Type Aliases§

Result: Result type used throughout claude_storage