Struct ClaudeConvo 

pub struct ClaudeConvo { /* private fields */ }

High-level interface for reading Claude conversations.

This is the primary entry point for most use cases. It provides convenient methods for reading conversations, listing projects, and accessing conversation history.

Chain-default: read_conversation and list_conversations operate on logical conversations (merged session chains). Use read_segment and list_segments for single-file access.

Example

use toolpath_claude::ClaudeConvo;

let manager = ClaudeConvo::new();

// List all projects
let projects = manager.list_projects()?;

// Read a conversation (follows session chains automatically)
let convo = manager.read_conversation(
    "/Users/alex/project",
    "session-uuid"
)?;

println!("Conversation has {} messages", convo.message_count());

Implementations

impl ClaudeConvo

pub fn new() -> Self

Creates a new ClaudeConvo manager with default path resolution.

pub fn with_resolver(resolver: PathResolver) -> Self

Creates a ClaudeConvo manager with a custom path resolver.

This is useful for testing or when working with non-standard paths.

Example

use toolpath_claude::{ClaudeConvo, PathResolver};

let resolver = PathResolver::new()
    .with_home("/custom/home")
    .with_claude_dir("/custom/.claude");

let manager = ClaudeConvo::with_resolver(resolver);

pub fn io(&self) -> &ConvoIO

Returns a reference to the underlying ConvoIO.

pub fn resolver(&self) -> &PathResolver

Returns a reference to the path resolver.

pub fn read_conversation( &self, project_path: &str, session_id: &str, ) -> Result<Conversation>

Reads a conversation by project path and session ID.

Chain-aware: if this session is part of a chain (file rotation), all segments are merged into a single Conversation with bridge entries filtered out and session_ids populated.

Use Self::read_segment for single-file access.

pub fn read_conversation_metadata( &self, project_path: &str, session_id: &str, ) -> Result<ConversationMetadata>

Reads conversation metadata without loading the full content.

Chain-aware: aggregates message_count (sum), started_at (earliest), and last_activity (latest) across all segments.

pub fn list_conversations(&self, project_path: &str) -> Result<Vec<String>>

Lists logical conversation IDs for a project (chain heads only).

Chained sessions collapse to a single entry (the head). Use Self::list_segments for all file stems.

pub fn list_conversation_metadata( &self, project_path: &str, ) -> Result<Vec<ConversationMetadata>>

Lists metadata for all logical conversations in a project.

Chain heads only. Results are sorted by last activity (most recent first).

pub fn read_segment( &self, project_path: &str, session_id: &str, ) -> Result<Conversation>

Reads a single JSONL file without following chains.

pub fn list_segments(&self, project_path: &str) -> Result<Vec<String>>

Lists all file stems (including successor segments).

pub fn list_projects(&self) -> Result<Vec<String>>

Lists all projects that have conversations.

Returns the original project paths (e.g., “/Users/alex/project”).

pub fn read_history(&self) -> Result<Vec<HistoryEntry>>

Reads the global history file.

The history file contains a record of all queries across all projects.

pub fn exists(&self) -> bool

Checks if the Claude directory exists.

pub fn claude_dir_path(&self) -> Result<PathBuf>

Returns the path to the Claude directory.

pub fn conversation_exists( &self, project_path: &str, session_id: &str, ) -> Result<bool>

Checks if a specific conversation exists.

pub fn project_exists(&self, project_path: &str) -> bool

Checks if a project directory exists.

pub fn query<'a>(&self, conversation: &'a Conversation) -> ConversationQuery<'a>

Creates a query builder for a conversation.

pub fn query_history<'a>(&self, history: &'a [HistoryEntry]) -> HistoryQuery<'a>

Creates a query builder for history entries.

pub fn read_all_conversations( &self, project_path: &str, ) -> Result<Vec<Conversation>>

Reads all conversations for a project.

Returns a vector of conversations sorted by last activity.

pub fn most_recent_conversation( &self, project_path: &str, ) -> Result<Option<Conversation>>

Gets the most recent conversation for a project.

pub fn find_conversations_with_text( &self, project_path: &str, search_text: &str, ) -> Result<Vec<Conversation>>

Finds conversations that contain specific text.

Trait Implementations

impl Clone for ClaudeConvo

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ConversationProvider for ClaudeConvo

fn list_conversations(&self, project: &str) -> Result<Vec<String>>

List conversation IDs for a project/workspace.

fn load_conversation( &self, project: &str, conversation_id: &str, ) -> Result<ConversationView>

Load a full conversation as a ConversationView.

fn load_metadata( &self, project: &str, conversation_id: &str, ) -> Result<ConversationMeta>

Load metadata only (no turns).

fn list_metadata(&self, project: &str) -> Result<Vec<ConversationMeta>>

List metadata for all conversations in a project.

impl Debug for ClaudeConvo

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ClaudeConvo

fn default() -> Self

Returns the “default value” for a type.