Dependencies

Injectable dependencies for hook handlers.

Transcript

Access to the conversation history and statistics. See Transcript API for full documentation.

Transcript

Mutable collection of entries backed by a JSONL file.

Usage

Standalone

transcript = Transcript("/path/to/transcript.jsonl") transcript.load()

Query

for msg in transcript.user_messages: print(msg.text)

stats property

stats: 'TranscriptStats'

Calculate transcript statistics.

entries instance-attribute

entries: list[TranscriptEntry] = []

user_messages property

user_messages: list[UserMessage]

All user messages (uses default include_archived setting).

assistant_messages property

assistant_messages: list[AssistantMessage]

All assistant messages (uses default include_archived setting).

tool_uses property

tool_uses: list[ToolUseBlock]

All tool use blocks across all messages.

tool_results property

tool_results: list[ToolResultBlock]

All tool result blocks.

__init__

__init__(
    path: str | Path | None = None,
    validate: Literal["strict", "warn", "none"] = "warn",
    safety: Literal["strict", "warn", "none"] = "warn",
    auto_load: bool = True,
)

query

query(
    include_archived: bool | None = None,
    include_meta: bool | None = None,
) -> TranscriptQuery

Start a fluent query on transcript entries.

Returns a TranscriptQuery that supports chaining

transcript.query().filter(type="assistant").first() transcript.query().assistants().with_tools().count()

Parameters:

Name	Type	Description	Default
include_archived	bool | None	Include archived entries. Defaults to self.include_archived.	None
include_meta	bool | None	Include meta entries. Defaults to self.include_meta.	None

Returns:

Type	Description
TranscriptQuery	TranscriptQuery for fluent chaining

TranscriptStats

Statistics extracted from a transcript.

input_tokens instance-attribute

input_tokens = input_tokens

output_tokens instance-attribute

output_tokens = output_tokens

cache_read_tokens instance-attribute

cache_read_tokens = cache_read_tokens

cache_creation_tokens instance-attribute

cache_creation_tokens = cache_creation_tokens

tool_calls instance-attribute

tool_calls = tool_calls or {}

error_count instance-attribute

error_count = error_count

message_count instance-attribute

message_count = message_count

turn_count instance-attribute

turn_count = turn_count

compact_count instance-attribute

compact_count = compact_count

duration_seconds instance-attribute

duration_seconds = duration_seconds

slug instance-attribute

slug = slug

State

Persistent session-scoped storage.

State

Bases: dict[str, Any]

Persistent dict backed by JSON file.

Behaves like a regular dict but can save/load from file. Use as context manager for auto-save on exit.

for_session classmethod

for_session(
    session_id: str, state_dir: Path | str
) -> State

Create state scoped to a session.

Parameters:

Name	Type	Description	Default
session_id	str	Session identifier	required
state_dir	Path | str	Directory for state files	required

Returns:

Type	Description
State	State instance for this session

save

save() -> None

Save state to file.