Skip to main content
All models are defined in src.models and use Python’s standard dataclasses module. Frozen dataclasses (frozen=True) are immutable after construction. 
from src.models import (
    Subsystem,
    PortingModule,
    PortingBacklog,
    PermissionDenial,
    UsageSummary,
)

​
Subsystem

A frozen dataclass describing a logical subsystem within the Claude Code source tree that Claw Code mirrors.

​
Fields

​
name
string
required
Human-readable subsystem name (e.g. "query_engine", "tools").
​
path
string
required
Relative path to the subsystem within the source tree.
​
file_count
number
required
Number of source files in this subsystem.
​
notes
string
required
Free-text notes about porting status or design decisions.
from src.models import Subsystem

sub = Subsystem(
    name="query_engine",
    path="src/query_engine",
    file_count=3,
    notes="Core conversation loop; session persistence implemented.",
)

print(sub.name)        # "query_engine"
print(sub.file_count)  # 3

​
PortingModule

A frozen dataclass representing a single command or tool that has been mirrored from the Claude Code TypeScript source into the Python port.

​
Fields

​
name
string
required
Module name as it appears in Claude Code (e.g. "BashTool", "compact").
​
responsibility
string
required
Short description of what this module does.
​
source_hint
string
required
Path or identifier in the upstream source that this module mirrors (e.g. "src/tools/BashTool.ts").
​
status
string
default:"\"planned\""
Current porting status. Common values: "planned", "mirrored", "complete".
from src.models import PortingModule

module = PortingModule(
    name="FileReadTool",
    responsibility="Read file contents from the workspace",
    source_hint="src/tools/FileReadTool.ts",
    status="mirrored",
)

print(module.name)    # "FileReadTool"
print(module.status)  # "mirrored"
PortingModule is the element type of PORTED_COMMANDS and PORTED_TOOLS, and is returned by functions such as get_tool, get_command, find_tools, and find_commands.

​
PortingBacklog

A mutable dataclass grouping a set of PortingModule entries under a named backlog. Used to render the command and tool surfaces in QueryEnginePort.render_summary.

​
Fields

​
title
string
required
Display title for this backlog (e.g. "Command surface", "Tool surface").
​
modules
list[PortingModule]
default:"[]"
The list of modules in this backlog.

​
Methods

​
summary_lines

def summary_lines(self) -> list[str]
Returns one formatted string per module: 
- {name} [{status}] — {responsibility} (from {source_hint})

from src.models import PortingBacklog, PortingModule

backlog = PortingBacklog(
    title="Tool surface",
    modules=[
        PortingModule("FileReadTool", "Read files", "src/tools/FileReadTool.ts", "mirrored"),
        PortingModule("BashTool", "Run shell commands", "src/tools/BashTool.ts", "planned"),
    ],
)

for line in backlog.summary_lines():
    print(line)
# - FileReadTool [mirrored] — Read files (from src/tools/FileReadTool.ts)
# - BashTool [planned] — Run shell commands (from src/tools/BashTool.ts)

​
PermissionDenial

A frozen dataclass recorded when a tool is blocked by a ToolPermissionContext. Appears in TurnResult.permission_denials. See ToolPermissionContext for the full permission gating reference.

​
Fields

​
tool_name
string
required
The name of the tool that was blocked.
​
reason
string
required
Human-readable explanation for why the tool was blocked.
from src.models import PermissionDenial

denial = PermissionDenial(
    tool_name="BashTool",
    reason="destructive shell execution remains gated in the Python port",
)

print(denial.tool_name)  # "BashTool"
print(denial.reason)

​
UsageSummary

A frozen dataclass that tracks cumulative token usage across turns. QueryEnginePort maintains one instance and replaces it after each turn via add_turn.
Token counts are approximated using word counts (str.split()), not a tokeniser. Treat the values as order-of-magnitude estimates rather than precise token counts.

​
Fields

​
input_tokens
number
default:"0"
Cumulative word count of all prompts submitted to the engine.
​
output_tokens
number
default:"0"
Cumulative word count of all outputs produced by the engine.

​
Methods

​
add_turn

def add_turn(self, prompt: str, output: str) -> UsageSummary
Returns a new UsageSummary instance with the word counts of prompt and output added to the current totals. The original instance is not mutated.
​
prompt
string
required
The prompt submitted for this turn.
​
output
string
required
The output produced for this turn.
from src.models import UsageSummary

usage = UsageSummary()
print(usage.input_tokens, usage.output_tokens)  # 0 0

usage = usage.add_turn(
    prompt="explain the routing algorithm",
    output="The routing algorithm tokenises the prompt and scores each module...",
)

print(usage.input_tokens)   # 4  (words in prompt)
print(usage.output_tokens)  # 9  (words in output)

# Chain multiple turns
usage = usage.add_turn("follow up question", "Here is the answer...")
print(usage.input_tokens)   # 7

Build docs developers (and LLMs) love

Get started for freeTalk to us