Session activity

SessionActivity

A session’s transcript lifted into turns, tool uses, and edits.

Usage

SessionActivity(
    session_id,
    turns,
)

Attributes

session_id: SessionId: The Claude session UUID, the only session key.
turns: tuple[Turn, …]: The session’s turns, indexed by position.

Example

>>> activity = SessionActivity.from_session(session_id)
>>> activity.edits_before(anchor, lookback_turns=40)

Attributes

Name	Description
edits	Every edit in the session, in chronological order.

edits

Every edit in the session, in chronological order.

edits: tuple[Edit, …]

Methods

Name	Description
edits_after()	Edits to file_path after `anchor`, oldest-first.
edits_before()	Edits in the lookback window before `anchor`, newest-first.
from_events()	Lifts parsed events into turns.
from_session()	Discovers, parses, and lifts `session_id`’s transcript from disk.
turn_of()	The turn containing `ref`’s event.

edits_after()

Edits to file_path after anchor, oldest-first.

Usage

Source

edits_after(anchor, *, file_path, lookahead_turns)

Covers the rest of the anchor turn plus the lookahead_turns turns after it. A compacted-away anchor yields ().

edits_before()

Edits in the lookback window before anchor, newest-first.

Usage

Source

edits_before(anchor, *, lookback_turns)

Covers the lookback_turns turns strictly before the anchor’s turn plus edits earlier in the anchor turn itself. A compacted-away anchor yields ().

from_events()

Lifts parsed events into turns.

Usage

Source

from_events(session_id, events, *, user_classifier=native_user_classifier)

Each event for which user_classifier returns True opens a new turn; everything else folds into the current one. Events before the first qualifying prompt form turn 0 with prompt "".

from_session()

Discovers, parses, and lifts session_id’s transcript from disk.

Usage

Source

from_session(session_id, *, user_classifier=native_user_classifier, root=None)

Parameters

session_id: SessionId: The session to load.
user_classifier: UserClassifier = native_user_classifier: Decides which user events open turns.
root: Path | None = None: The projects directory to search; defaults to ~/.claude/projects.

Raises

TranscriptExpiredError: When no transcript for session_id exists on disk — Claude Code prunes them after roughly thirty days.

turn_of()

The turn containing ref’s event.

Usage

Source

turn_of(ref)

Returns

Turn | None: The turn, or None when the event is gone — a reference compacted
away inside a still-living transcript. Never raises for a miss.

Turn

One prompt-to-prompt span of a session.

Usage

Source

Turn(index, prompt, started_at, ended_at, events, tool_uses)

Attributes

index: int: The turn’s position in the session, starting at 0. Events before the first qualifying prompt form turn 0 with prompt "".
prompt: str: The user text that opened the turn.
started_at: datetime | None: The first timestamp among the turn’s events, or None when no event carries one.
ended_at: datetime | None: The last timestamp among the turn’s events, or None when no event carries one.
events: tuple[TranscriptEvent, …]: Every transcript event in the turn, in file order.
tool_uses: tuple[ToolUse, …]: Every tool invocation lifted from the turn’s assistant events, in order.

Attributes

Name	Description
edits	The turn’s file modifications: one entry per edited file (every file of an

edits

The turn’s file modifications: one entry per edited file (every file of an

edits: tuple[Edit, …]

apply_patch), in order.

ToolUse

One tool invocation lifted from a turn’s assistant events.

Usage

Source

ToolUse(ref, call, result, result_ts, edits, turn_index, ts)

Attributes

ref: EventRef: The resolvable reference to the tool-use block.
call: ToolCall | FallbackCall: The typed tool call, constructed once at lift time.
result: ToolResultBlock | None: The matching result block, or None when none ever arrived.
result_ts: datetime | None: The timestamp of the user entry carrying the result, or None when no result ever arrived.
edits: tuple[tuple[str, tuple[Hunk, …]], …]: The call’s lowered (file_path, hunks) entries, one per edited file.
turn_index: int: The index of the turn the call fired in.
ts: datetime: The timestamp of the assistant entry carrying the call.

Attributes

Name	Description
duration_ms	Milliseconds from the call to its result, or None without a result.
typed_result	The result parsed into the typed result hierarchy, or None without a result.

duration_ms

Milliseconds from the call to its result, or None without a result.

duration_ms: int | None

typed_result

The result parsed into the typed result hierarchy, or None without a result.

typed_result: ToolResult | FallbackResult | None

The join point for ~cc_transcript.tools.parse_tool_result(): pairs this use’s tool name with its result block’s tool_use_result payload, degrading to ~cc_transcript.tools.OtherResult on any shape drift.

Edit

A file modification lowered from an edit-shaped tool call.

Usage

Source

Edit(file_path, hunks, tool, ref, turn_index, ts)

Attributes

file_path: str: The file the call targeted.
hunks: tuple[Hunk, …]: The before/after content pairs, in application order.
tool: str: The tool name exactly as invoked.
ref: EventRef: The resolvable reference to the originating tool use.
turn_index: int: The index of the turn the edit happened in.
ts: datetime: The timestamp of the assistant entry carrying the call.

UserClassifier

Decides which ~cc_transcript.models.UserEvent objects open a turn.

UserClassifier=Callable[["UserEvent"], bool]

native_user_classifier()

Whether a user event is a real prompt under native Claude Code semantics.

Usage

Source

native_user_classifier(event)

A prompt is non-meta, non-sidechain, not a compact summary, not an interruption marker, not an agent-injected relay banner, and not tool-result-only — it must carry real text.

hunk_overlap()

The fraction of a.new’s non-empty lines present in b.old.

Usage

Source

hunk_overlap(a, b)

Lines are whitespace-normalized — stripped, internal runs collapsed — before comparison, and lines empty after normalization are ignored.

Returns

float: A value in [0.0, 1.0]; 0.0 when a.new has no non-empty lines.

result_index()

Indexes tool results by the id of the tool use they answer.

Usage

Source

result_index(events)

Pairs each ~cc_transcript.models.ToolResultBlock with the timestamp of the UserEvent carrying it, keyed by the block’s tool_use_id — the single source for joining a call to its result and deriving the call’s duration.

Returns

dict[ToolUseId, tuple[ToolResultBlock, datetime | None]]: A mapping from tool-use id to a (result block, result timestamp)
pair.