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.
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. |
| 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
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. |
| 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()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.
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.