ClaudeAgentSDK.Session.History (claude_agent_sdk v0.16.0)

Copy Markdown View Source

Read Claude CLI transcript history from on-disk JSONL files.

This module mirrors the upstream Agent SDK session-history behavior: it reads ~/.claude/projects/<sanitized-cwd>/<session-id>.jsonl, reconstructs the canonical conversation chain, and returns history metadata or visible user/assistant messages.

Summary

Functions

get_session_messages(session_id, opts \\ [])

Reads visible conversation messages from a CLI transcript.

list_sessions(opts \\ [])

Lists CLI transcript sessions.

sanitize_path(path)

Sanitizes a project path to the directory format used by Claude CLI.

simple_hash(input)

Produces the same base-36 hash used by the upstream session-storage logic.

Functions

get_session_messages(session_id, opts \\ [])

@spec get_session_messages(
  String.t(),
  keyword()
) :: [ClaudeAgentSDK.Session.SessionMessage.t()]

Reads visible conversation messages from a CLI transcript.

Options:

  • :directory - project path to search in
  • :limit - max number of messages to return
  • :offset - number of messages to skip from the start
  • :projects_dir - override the Claude projects directory (primarily for tests)

list_sessions(opts \\ [])

@spec list_sessions(keyword()) :: [ClaudeAgentSDK.Session.SessionInfo.t()]

Lists CLI transcript sessions.

Options:

  • :directory - project path to scan
  • :limit - max number of sessions to return
  • :include_worktrees - include git worktree transcript directories (default: true)
  • :projects_dir - override the Claude projects directory (primarily for tests)

sanitize_path(path)

@spec sanitize_path(String.t()) :: String.t()

Sanitizes a project path to the directory format used by Claude CLI.

simple_hash(input)

@spec simple_hash(String.t()) :: String.t()

Produces the same base-36 hash used by the upstream session-storage logic.