ClaudeAgentSDK.Session.History (claude_agent_sdk v0.18.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

delete_session(session_id, opts \\ [])

Deletes a transcript and its sibling subagent transcript directory.

fork_session(session_id, opts \\ [])

Forks a transcript into a new session file.

get_session_info(session_id, opts \\ [])

Looks up metadata for a single CLI transcript session.

get_session_messages(session_id, opts \\ [])

Reads visible conversation messages from a CLI transcript.

get_subagent_messages(session_id, agent_id, opts \\ [])

Reads visible messages from a subagent transcript.

list_sessions(opts \\ [])

Lists CLI transcript sessions.

list_subagents(session_id, opts \\ [])

Lists subagent IDs for a session.

rename_session(session_id, title, opts \\ [])

Appends a custom title entry to a transcript.

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.

tag_session(session_id, tag, opts \\ [])

Appends a tag entry to a transcript. Passing nil clears the tag.

Functions

delete_session(session_id, opts \\ [])

@spec delete_session(
  String.t(),
  keyword()
) :: :ok

Deletes a transcript and its sibling subagent transcript directory.

fork_session(session_id, opts \\ [])

@spec fork_session(
  String.t(),
  keyword()
) :: ClaudeAgentSDK.Session.ForkResult.t()

Forks a transcript into a new session file.

get_session_info(session_id, opts \\ [])

@spec get_session_info(
  String.t(),
  keyword()
) :: ClaudeAgentSDK.Session.SessionInfo.t() | nil

Looks up metadata for a single CLI transcript session.

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)

get_subagent_messages(session_id, agent_id, opts \\ [])

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

Reads visible messages from a subagent transcript.

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)

list_subagents(session_id, opts \\ [])

@spec list_subagents(
  String.t(),
  keyword()
) :: [String.t()]

Lists subagent IDs for a session.

rename_session(session_id, title, opts \\ [])

@spec rename_session(String.t(), String.t(), keyword()) :: :ok

Appends a custom title entry to a transcript.

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.

tag_session(session_id, tag, opts \\ [])

@spec tag_session(String.t(), String.t() | nil, keyword()) :: :ok

Appends a tag entry to a transcript. Passing nil clears the tag.