Trajectory viewer

caw ships a small web UI for browsing saved trajectories — turns, content blocks, tool calls, and nested subagent trajectories — plus a terminal inspector for agents.

Web viewer

Start the server from the CLI:

caw viewer                 # auto host/port
caw viewer --port 8080     # fixed port

…or programmatically with start_viewer_server(), which returns a ViewerServer handle:

from caw.viewer import start_viewer_server

server = start_viewer_server()          # auto host/port
print(server.url)                       # http://localhost:<port>
server.check_status()                   # True / False
server.stop()

The viewer loads a trajectory JSON file by absolute path, passed as a query parameter:

http://localhost:<port>?path=/abs/path/to/trajectory.json

Full example — examples/traj_viewer.py runs a short session, saves the trajectory, and opens it in the viewer:

"""Trajectory viewer: save a session trajectory and view it in the browser."""

import os
import tempfile

os.environ["CAW_LOG"] = "full"

from caw import Agent
from caw.viewer import start_viewer_server


def main():
    agent = Agent(data_dir="caw_data")

    # Run a short session and save the trajectory to a temp file
    traj_path = os.path.join(tempfile.gettempdir(), "caw_example_traj.json")

    with agent.start_session(traj_path=traj_path) as session:
        session.send("What is 2 + 2? Answer in one sentence.")

    print(f"\nTrajectory saved to {traj_path}")

    # Start the viewer server and print the URL
    server = start_viewer_server()
    print(f"Open in browser: {server.url}?path={traj_path}")

    print("Press Ctrl+C to stop the viewer.")
    try:
        import signal

        signal.pause()
    except KeyboardInterrupt:
        pass
    finally:
        server.stop()


if __name__ == "__main__":
    main()

Terminal inspector

For a quick, scriptable look (or to let another agent read a trajectory), use the caw-traj CLI or the caw traj subcommand. It prints a compact, step-indexed view and can expand specific steps:

caw-traj run.json                 # compact, step-indexed overview
caw-traj run.json --recursive     # include nested subagent steps
caw-traj run.json --step 7        # full detail for step 7
caw-traj run.json --step 7-10     # a range
caw-traj run.json --step 12/3     # a nested step under step 12

See the CLI reference for every option.