Query
Session
An immutable windowed view of a session’s turns.
Usage
Session(
turns,
path=None,
attachments=(),
)Every slicing operation returns another Session; turns at a window boundary are trimmed copies, so mid-turn slices stay event-precise.
Unslotted, unlike its neighbours: the window is immutable, so every derivation over it — tool_calls, commands(), command_lines() — memoizes per instance, and a predicate that queries one window repeatedly pays each derivation once.
Attributes
turns: tuple[Turn, …]-
The turns in the window.
path: Path | None-
The transcript file the session was loaded from, when known — required for sidechain (subagent) lookups.
attachments: tuple[Path, …]- External transcript files (e.g. codex rollouts) registered with this session; walk() and deep fold them in at depth 1. Empty for a session loaded straight from disk.
Example
>>> session.prior().after(tool="Write", file=str(fp)).has_tool("ExitPlanMode")Attributes
| Name | Description |
|---|---|
| current_turn | The one-turn view of the window’s last turn. |
| deep | The recursive union view over this session and every transcript it reaches. |
| edited_files | The files modified by edit-shaped calls in the window, one entry per edited file. |
| events | Every event in the window, in order. |
| files_touched | The files targeted by any tool call in the window, one entry per call. |
| first_prompt | The first user prompt in the window, or None when there is none. |
| notifications | The harness notification-delivery queue replayed over the window’s events. |
| predicate_inputs |
What the has_* predicates read from this window.
|
| subagents | The window’s Task dispatches whose sidechain transcripts exist on disk. |
| tool_calls | The window’s tool calls as a chainable query. |
| user_text | The prompt that opened the window’s last turn. |
current_turn
The one-turn view of the window’s last turn.
current_turn: Session
deep
The recursive union view over this session and every transcript it reaches.
deep: DeepView
edited_files
The files modified by edit-shaped calls in the window, one entry per edited file.
edited_files: tuple[FileRef, …]
events
Every event in the window, in order.
events: tuple[TranscriptEvent, …]
files_touched
The files targeted by any tool call in the window, one entry per call.
files_touched: tuple[FileRef, …]
first_prompt
The first user prompt in the window, or None when there is none.
first_prompt: str | None
notifications
The harness notification-delivery queue replayed over the window’s events.
notifications: Notifications
predicate_inputs
What the has_* predicates read from this window.
predicate_inputs: PredicateInputs
subagents
The window’s Task dispatches whose sidechain transcripts exist on disk.
subagents: SubagentIndex
tool_calls
The window’s tool calls as a chainable query.
tool_calls: ToolCallQuery
user_text
The prompt that opened the window’s last turn.
user_text: str
Methods
| Name | Description |
|---|---|
| after() |
The window strictly after the last call matching tool.
|
| assistant_text() |
The window’s last n assistant texts, each capped at max_per_msg chars.
|
| before() |
The window strictly before the last call matching tool.
|
| command_lines() |
The window’s Bash commands parsed into ~cc_transcript.command.CommandLine objects.
|
| commands() | The shell command strings of the window’s Bash calls. |
| count_failures() | The number of calls in the window whose result errored. |
| deep_inputs() | This window’s PredicateInputs, then those of every transcript walk() reaches. |
| from_activity() |
Views activity’s full turn range as a session.
|
| from_id() |
Discovers, parses, and lifts session_id’s transcript from disk.
|
| from_path() |
Parses and lifts the transcript at path.
|
| has_command() |
Whether any Bash command in the window runs argv.
|
| has_edit_to() | Whether any edit-shaped call in the window targets a file matching any glob. |
| has_override() |
Whether token appears in the window without a later invalidating call.
|
| has_read() |
Whether any Read in the window targets a path containing pattern.
|
| has_skill() |
Whether any Skill invocation in the window names one of names.
|
| has_tool() |
Whether any call in the window matches the pipe spec name.
|
| prior() | The window without its last user or assistant event. |
| recent() |
The window’s last n events.
|
| user_said() | Whether any prompt in the window contains any keyword, case-insensitively. |
| walk() | Every transcript reachable from this session, lazily and depth-first. |
after()
The window strictly after the last call matching tool.
Usage
after(*, tool, file=None)file narrows the match to calls whose target path contains it as a substring. With no matching call the result is the empty window.
assistant_text()
The window’s last n assistant texts, each capped at max_per_msg chars.
Usage
assistant_text(n=10, max_per_msg=500)before()
The window strictly before the last call matching tool.
Usage
before(*, tool)With no matching call the whole window is returned.
command_lines()
The window’s Bash commands parsed into ~cc_transcript.command.CommandLine objects.
Usage
command_lines()commands()
The shell command strings of the window’s Bash calls.
Usage
commands()count_failures()
The number of calls in the window whose result errored.
Usage
count_failures()deep_inputs()
This window’s PredicateInputs, then those of every transcript walk() reaches.
Usage
deep_inputs()from_activity()
Views activity’s full turn range as a session.
Usage
from_activity(activity, *, path=None, attachments=())from_id()
Discovers, parses, and lifts session_id’s transcript from disk.
Usage
from_id(session_id, *, user_classifier=native_user_classifier, root=None)Raises
TranscriptExpiredError-
When no transcript for
session_idexists on disk.
from_path()
Parses and lifts the transcript at path.
Usage
from_path(path, *, user_classifier=native_user_classifier)has_command()
Whether any Bash command in the window runs argv.
Usage
has_command(*argv, subagents=True)Matches when argv is a leading-token prefix of any parsed command’s unwrapped argv, so has_command("git", "push") matches sudo git push -f and cd x && git push but not echo "git push".
has_edit_to()
Whether any edit-shaped call in the window targets a file matching any glob.
Usage
has_edit_to(*globs, subagents=True)has_override()
Whether token appears in the window without a later invalidating call.
Usage
has_override(token, *, invalidated_by=("Edit", "Write"))The token counts wherever it last appears — user or assistant text, system content, or a tool result. Any call after that point matching invalidated_by (aliases honored, errored calls included) cancels the override.
has_read()
Whether any Read in the window targets a path containing pattern.
Usage
has_read(pattern, *, subagents=True)has_skill()
Whether any Skill invocation in the window names one of names.
Usage
has_skill(*names, subagents=True)has_tool()
Whether any call in the window matches the pipe spec name.
Usage
has_tool(name, *, subagents=True)prior()
The window without its last user or assistant event.
Usage
prior()recent()
The window’s last n events.
Usage
recent(n)user_said()
Whether any prompt in the window contains any keyword, case-insensitively.
Usage
user_said(*keywords)walk()
Every transcript reachable from this session, lazily and depth-first.
Usage
walk()Yields each descendant sidechain (subagent/teammate) transcript at every depth in DFS path order, then each registered attachment at depth 1 — never this session itself. A resolved-path seen-set (seeded with path) dedupes: the first occurrence of a path wins, so a tree-discovered sidechain outranks an equal attachment, and symlink cycles terminate. An unreadable transcript is skipped but its children are still walked; a structurally malformed line raises, as subagents does.
Each reached transcript is parsed and lifted once per (size, mtime) stamp and memoized across walks, so a predicate that walks repeatedly — or a resident process that re-walks per event — reparses only what grew.
ToolCallQuery
A chainable filter over a window’s tool calls.
Usage
ToolCallQuery(all_items, include_errors=False)Calls whose result errored are hidden by default; with_errors widens the view and failed() inverts it. Filters narrow, terminals extract.
Parameter Attributes
all_items: tuple[ToolUse, …]include_errors: bool = False
Example
>>> session.tool_calls.named("Edit|Write").files()Attributes
| Name | Description |
|---|---|
| items | The effective view: every call, or only those that did not error. |
| with_errors | The same query with errored calls included. |
items
The effective view: every call, or only those that did not error.
items: tuple[ToolUse, …]
with_errors
The same query with errored calls included.
with_errors: ToolCallQuery
Methods
| Name | Description |
|---|---|
| any() | Whether any call matches. |
| count() | The number of matching calls. |
| edited_files() | The files edited by the matching calls, one entry per edited file (every file |
| failed() | Only the calls whose result errored. |
| files() | The files the matching calls target, one entry per targeted file (every file |
| first() | The earliest matching call, or None. |
| in_turns() | Calls fired in any of the given session turn indices. |
| last() | The latest matching call, or None. |
| named() | Calls whose tool name matches a pipe spec, honoring aliases and MCP suffixes. |
| touching() | Calls targeting a file that matches any glob. |
| under() | Calls targeting a file under any prefix. |
| where() |
Calls satisfying predicate.
|
| where_input() | Calls whose raw input carries every key, each matching its rule. |
any()
Whether any call matches.
Usage
any()count()
The number of matching calls.
Usage
count()edited_files()
The files edited by the matching calls, one entry per edited file (every file
Usage
edited_files()of an apply_patch), in order.
failed()
Only the calls whose result errored.
Usage
failed()files()
The files the matching calls target, one entry per targeted file (every file
Usage
files()of an apply_patch), in order.
first()
The earliest matching call, or None.
Usage
first()in_turns()
Calls fired in any of the given session turn indices.
Usage
in_turns(*indices)last()
The latest matching call, or None.
Usage
last()named()
Calls whose tool name matches a pipe spec, honoring aliases and MCP suffixes.
Usage
named(spec)touching()
Calls targeting a file that matches any glob.
Usage
touching(*globs)under()
Calls targeting a file under any prefix.
Usage
under(*prefixes)where()
Calls satisfying predicate.
Usage
where(predicate)where_input()
Calls whose raw input carries every key, each matching its rule.
Usage
where_input(**rules)A rule is a compiled regex (searched against str(value)), a callable predicate, or a value compared for equality.
FileRef
A file path carried by a tool call, with glob and prefix matching.
Usage
FileRef(path)Attributes
path: str- The path exactly as the tool call carried it.
Example
>>> FileRef("/repo/tests/test_app.py").is_testTrue
Attributes
| Name | Description |
|---|---|
| is_test | Whether the path names a Python test file. |
| suffix |
The file extension including the leading dot (e.g. .py), or "".
|
is_test
Whether the path names a Python test file.
is_test: bool
suffix
The file extension including the leading dot (e.g. .py), or "".
suffix: str
Methods
| Name | Description |
|---|---|
| matches() | Whether the full path or the basename matches any glob. |
| under() |
Whether the path starts with, or contains a /-anchored, prefix.
|
matches()
Whether the full path or the basename matches any glob.
Usage
matches(*globs)under()
Whether the path starts with, or contains a /-anchored, prefix.
Usage
under(*prefixes)SubagentSession
One Task dispatch joined to its sidechain transcript.
Usage
SubagentSession(id, type, session, parent)Attributes
Attributes
| Name | Description |
|---|---|
| failed | Whether the dispatch’s result errored or any sidechain call failed. |
| tool_calls | The sidechain session’s tool calls. |
failed
Whether the dispatch’s result errored or any sidechain call failed.
failed: bool
tool_calls
The sidechain session’s tool calls.
tool_calls: ToolCallQuery
SubagentIndex
The subagent dispatches of a session window.
Usage
SubagentIndex(items)Parameter Attributes
items: tuple[SubagentSession, …]
Example
>>> session.subagents.with_type("test-runner")Methods
| Name | Description |
|---|---|
| with_type() |
The dispatches whose type is named in the pipe spec pattern.
|
with_type()
The dispatches whose type is named in the pipe spec pattern.
Usage
with_type(pattern)DeepView
The recursive union of a session and every transcript reachable from it.
Usage
DeepView(root)Sidechain (subagent/teammate) transcripts at every depth and registered attachments contribute their tool calls and events to one window-spanning view. The root axis respects the session’s window; descendants and attachments are window-invariant, mirroring how has_tool already scans the whole sidechain tree.
Parameter Attributes
root: Session
Example
>>> session.deep.tool_calls.named("Edit|Write").files()Attributes
| Name | Description |
|---|---|
| events | Every event across the root window and every reached transcript, in walk order. |
| sessions | Every reached DeepSession, materialized once: DFS, then attachments. |
| tool_calls | The root window’s calls, then every descendant’s and attachment’s calls. |
events
Every event across the root window and every reached transcript, in walk order.
events: tuple[TranscriptEvent, …]
sessions
Every reached DeepSession, materialized once: DFS, then attachments.
sessions: tuple[DeepSession, …]
tool_calls
The root window’s calls, then every descendant’s and attachment’s calls.
tool_calls: ToolCallQuery
Positional, not chronological: root-window order, then DFS path order, then attachment registration order — so ToolCallQuery.first() and ToolCallQuery.last() read positionally.
DeepSession
One transcript reached by Session.walk().
Usage
DeepSession(session, path, provider, depth, spawned_by)Attributes
session: Session-
The whole-session view of the reached transcript.
path: Path-
The transcript file it was loaded from.
provider: str-
Its source provider,
"claude"or"codex". depth: int-
Distance from the root;
1is a direct sidechain or attachment. spawned_by: ToolUseId | None-
The dispatching tool-use id parsed from an
agent-<id>sidechain stem, or None for an attachment.
PredicateInputs
The slice of one transcript window that the has_* predicates read.
Usage
PredicateInputs(calls, commands, edited_files, skills, answers=dict())Small enough to hold for every transcript in a tree of thousands, where a lifted Session is not. Calls whose result errored are left out, as ToolCallQuery hides them by default. Answers that do not depend on the MCP tool registry are memoized, up to MAX_ANSWERS per instance.
Attributes
calls: tuple[tuple[str, tuple[str, …]], …]-
Each call’s tool name and the file paths it targets, in order.
commands: tuple[str, …]-
The command string of every Bash call.
edited_files: tuple[FileRef, …]-
The files modified by edit-shaped calls, one entry per edited file.
skills: tuple[str, …]- The skill named by every Skill call.
Attributes
| Name | Description |
|---|---|
| command_lines |
commands parsed into ~cc_transcript.command.CommandLine objects.
|
| tool_names |
The distinct names in calls.
|
command_lines
commands parsed into ~cc_transcript.command.CommandLine objects.
command_lines: tuple[CommandLine, …]
tool_names
The distinct names in calls.
tool_names: frozenset[str]
Methods
| Name | Description |
|---|---|
| files() |
The files targeted by calls matching the pipe spec spec, one entry per path.
|
| of() |
Extracts the predicate inputs from session’s window.
|
files()
The files targeted by calls matching the pipe spec spec, one entry per path.
Usage
files(spec)of()
Extracts the predicate inputs from session’s window.
Usage
of(session)