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.

pub fn list_subagents(&self, session_id: &str) -> Result<Vec<SubagentSummary>>

List the subagent (sidechain) transcripts recorded under a session’s subdirectory, sorted by agent id.

Returns an empty vector when the session has no subdirectory or no subagents/ entries – the common case. Errors with Error::History if the session id itself is unknown.

pub fn read_subagent( &self, session_id: &str, agent_id: &str, ) -> Result<Vec<HistoryEntry>>

Parse one subagent transcript into typed HistoryEntry values, with the same liberal line-level parsing as Self::read_session. Subagent records carry the extra fields agentId and isSidechain: true, reachable through HistoryEntry::field / HistoryEntry::is_sidechain.

Errors with Error::History if the session id or agent id is unknown.

pub fn list_tool_results( &self, session_id: &str, ) -> Result<Vec<ToolResultSummary>>

List the spilled tool-result files recorded under a session’s subdirectory, sorted by tool-use id.

Claude Code spills large tool outputs to tool-results/<tool_use_id>.txt and references them from the transcript. Returns an empty vector when there are none. Errors with Error::History if the session id is unknown.

pub fn read_tool_result( &self, session_id: &str, tool_use_id: &str, ) -> Result<String>

Read one spilled tool result’s content.

Errors with Error::History if the session id or tool-use id is unknown.

pub fn list_workflows(&self, session_id: &str) -> Result<Vec<WorkflowSummary>>

List the workflow journals recorded under a session’s subdirectory, sorted by workflow id.

Each journal is a workflows/wf_<id>.json file; when a matching script (workflows/scripts/<name>-wf_<id>.js) exists its path is included. Returns an empty vector when there are none. Errors with Error::History if the session id is unknown.

pub fn read_workflow( &self, session_id: &str, workflow_id: &str, ) -> Result<Value>

Read one workflow journal as raw JSON.

The journal shape is Claude Code internal state; it is returned as a serde_json::Value rather than typed. Errors with Error::History if the session id or workflow id is unknown.

pub fn prompt_history(&self) -> Result<Vec<PromptHistoryEntry>>

Read the global prompt history: one entry per typed prompt, across all projects, in file (chronological) order.

Claude Code appends to ~/.claude/history.jsonl, a sibling of the projects root, each time the user submits a typed prompt. Only typed prompts land there, so this is a pre-filtered human-input stream with project and session join keys. Retention differs from session transcripts, and transcripts remain the ground truth for attribution.

Returns an empty vector when the file does not exist.

pub fn prompt_history_with( &self, opts: &ListOptions, ) -> Result<Vec<PromptHistoryEntry>>

Self::prompt_history with pagination. Only offset and limit apply; the other ListOptions fields are ignored. Malformed lines are skipped with a tracing warning.

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.