Struct HistoryRoot 

pub struct HistoryRoot { /* private fields */ }

Root directory of Claude Code’s on-disk history. Defaults to ~/.claude/projects; override with HistoryRoot::at for tests or non-default installs.

Implementations

impl HistoryRoot

pub fn home() -> Result<Self>

Resolve the default ~/.claude/projects. Errors if $HOME (or the platform-specific user home) cannot be determined.

pub fn at(path: impl Into<PathBuf>) -> Self

Use a specific path as the projects root. Useful for tests (point at a tempdir) and for non-default installs.

pub fn path(&self) -> &Path

The configured root directory.

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

List every project directory at the root, sorted by slug.

Convenience wrapper around Self::list_projects_with with ListOptions::default (no limit, no offset, name-ascending sort, includes empty projects). Existing callers keep their behavior; new callers wanting pagination or recency sort should use Self::list_projects_with.

Returns an empty vec if the root directory doesn’t exist.

pub fn list_projects_with( &self, opts: &ListOptions, ) -> Result<Vec<ProjectSummary>>

List project directories with filter / sort / pagination.

Reads every direct child directory of the root, summarizes each, then applies (in order):

1. Filter out empty projects (session_count == 0) when opts.include_empty is false.
2. Sort by opts.sort (ListSort::NameAsc by default, ListSort::RecencyDesc for “most recent first”).
3. Skip the first opts.offset items.
4. Truncate to opts.limit items.

Returns an empty vec if the root directory doesn’t exist.

pub fn list_sessions(&self, slug: Option<&str>) -> Result<Vec<SessionSummary>>

List sessions, optionally filtered to one project’s slug, sorted by session id.

Convenience wrapper around Self::list_sessions_with with ListOptions::default.

pub fn list_sessions_with( &self, slug: Option<&str>, opts: &ListOptions, ) -> Result<Vec<SessionSummary>>

List sessions with filter / sort / pagination.

When slug is Some, only that project is walked. When None, every project directory is unioned. The options pipeline is the same as Self::list_projects_with: filter empty (message_count == 0) sessions unless opts.include_empty, sort, then offset + limit.

pub fn project_slug(path: impl AsRef<Path>) -> String

Derive claude’s project-directory slug for a filesystem path, matching the CLI exactly: the path is canonicalized (resolving symlinks – e.g. /var -> /private/var on macOS, /tmp on Linux) and then every / and . is encoded as -.

This is the forward complement of ProjectSummary::decoded_path and the reliable way to locate the project directory for a working directory – see Self::sessions_for_path. Without the canonicalization and the .-encoding, a cwd under a symlinked root, or containing a . in a path segment, derives a slug that doesn’t match what claude wrote, so enumeration finds nothing.

Falls back to the path as given when it cannot be canonicalized (e.g. it does not exist on disk).

pub fn sessions_for_path( &self, cwd: impl AsRef<Path>, ) -> Result<Vec<SessionSummary>>

List sessions for a specific working directory, deriving its project slug via Self::project_slug.

This is the current-project enumeration entry point: it canonicalizes and encodes the cwd exactly as claude does, so sessions written from symlinked roots (/tmp, /var) or dotted path segments are found. Convenience over list_sessions(Some(&HistoryRoot::project_slug(cwd))).

pub fn sessions_for_path_with( &self, cwd: impl AsRef<Path>, opts: &ListOptions, ) -> Result<Vec<SessionSummary>>

Self::sessions_for_path with explicit ListOptions.

pub fn read_session(&self, session_id: &str) -> Result<SessionLog>

Read one session’s full entry log.

Walks every project directory looking for <session_id>.jsonl. Errors with Error::History if no session file matches. Malformed lines are skipped with a tracing warning.

pub fn find_session( &self, session_id: &str, ) -> Result<Option<(PathBuf, String)>>

Locate the on-disk path for a session id, plus its project slug. Returns Ok(None) if no such session exists. Useful when a caller wants to read with non-default semantics (streaming, tailing, etc.) without going through Self::read_session.

Trait Implementations

impl Clone for HistoryRoot

fn clone(&self) -> HistoryRoot

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for HistoryRoot

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

Formats the value using the given formatter.