trajectoriz

Library and CLI to search, browse, and analyze past agent trajectory files. Supports Claude Code, Codex, OpenCode, Copilot, Hermes and more.

Installation

pip install trajectoriz

Search

trajectoriz-cli search lets you find past agent sessions by content — what was discussed, what commands were run, what files were edited.

# AND semantics: all words must appear in a step
trajectoriz-cli search "salary KTH overhead"
trajectoriz-cli search "telegram send_message bot_token"
trajectoriz-cli search "deploy dokku researchers webapp"

# OR semantics: use \| between alternatives
trajectoriz-cli search "pytest\|unittest"

# Restrict to the current project
trajectoriz-cli search "fix login bug" --local

# Fast metadata-only search (first message only, no parsing)
trajectoriz-cli search "refactor auth" --fast

Results are returned as a paginated Markdown table with trajectory ID, agent, date, step number, and a context snippet:

## Search: `salary KTH overhead` — 8 match(es)

| ID           | Agent  | Date       | Step | Snippet                                              |
|---|---|---|---|---|
| `cl-4d72f7b5`| claude | 2026-05-15 | 73   | …kth_salary = ws["E8"].value  # KTH  Direkt lön…   |
| `cl-4ef313e6`| claude | 2026-05-04 | 93   | …Organization: KTH Royal Institute of Technology…  |

Then inspect any result:

trajectoriz-cli show cl-4d72f7b5 --step 73

Search backends

Backend	Setup	Semantics
`grep` (default)	none	substring, in-process
`sqlite`	`trajectoriz-cli refresh --no-recoll`	whole-word FTS5
`recoll`	`trajectoriz-cli refresh --no-sqlite`	full Xapian index

trajectoriz-cli search "openssl handshake" --backend sqlite
trajectoriz-cli search "openssl handshake" --backend recoll

CLI

# List trajectories in the current directory
trajectoriz-cli list

# Show a trajectory (markdown, paginated)
trajectoriz-cli show cl-1234abcd
trajectoriz-cli show cl-1234abcd --last         # jump to the last page
trajectoriz-cli show cl-1234abcd --step 42      # jump to the page containing step 42
trajectoriz-cli show cl-1234abcd --html > out.html   # self-contained HTML export

# Trajectory metadata (JSON)
trajectoriz-cli info cl-1234abcd

# Blame a file — every agent edit in chronological order with line deltas
trajectoriz-cli blame src/main.py

# Aggregate statistics across all trajectories
trajectoriz-cli stats --all

# Aggregate shell-invoked programs across a repo
trajectoriz-cli advanced tools --dir /path/to/repo

Features

Full-content search — three backends (grep / sqlite / recoll); space-separated words are AND, \| is OR; matches at step level across message, tool calls, and results
Unified record API — iterate and parse sessions from Claude Code, Codex, Copilot, OpenCode, Hermes and more through a single iter_records() / parse_record() interface
Blame — trace every agent edit to a file across all trajectory sources, with line/char deltas
HTML export — trajectoriz-cli show <id> --html renders a trajectory as a self-contained HTML page
ATIF export — trajectoriz.atif translates parsed trajectories to ATIF v1.7 (Claude Code, Codex, Copilot, agentknit, or any iter_records()/parse_record() result)

Python API

from trajectoriz import iter_records, parse_record

# Iterate sessions across all supported agents (Claude, Codex, Copilot, OpenCode, …)
for record in iter_records():
    print(record.agent, record.timestamp[:10], record.first_msg[:60])

# Iterate sessions for the current project only
for record in iter_records(cwd="/path/to/repo"):
    trajectory = parse_record(record)
    if trajectory is not None:
        print(f"{record.agent}: {len(trajectory.steps)} steps, {trajectory.total_tokens} tokens")

License

MIT

Metadata

Release files for trajectoriz 0.47.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for trajectoriz 0.47.0
File	Interpreter	ABI	Platform	Reset
trajectoriz-0.47.0-py3-none-any.whl 40.9 kB Sep 3, 2026	Python 3	none	any	Details

Release files / trajectoriz-0.47.0-py3-none-any.whl

Download URL	trajectoriz-0.47.0-py3-none-any.whl
Size	40.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6eac4caabd7c9e424344a77385debadfdad3d67bd06f063c0afb698afcfc76dd`
BLAKE2b-256 checksum How to use checksums	`d24d55791efcd5d507641fa3e3a6de866377fe6413b2d9471080b631ecc39e23`
Upload date	Sep 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/monperrus/trajectoriz
Publishing commit: github.com/monperrus/trajectoriz/tree/08ab2b55d8ccf7d2351d74083924792f43ff46d7

Workflow

Publishing configuration: github.com/monperrus/trajectoriz/blob/08ab2b55d8ccf7d2351d74083924792f43ff46d7/.github/workflows/pypi-publish.yml
Publishing logs: github.com/monperrus/trajectoriz/actions/runs/33788641875/attempts/1

Artifact

Subject: trajectoriz-0.47.0-py3-none-any.whl
SHA-256 checksum: 6eac4caabd7c9e424344a77385debadfdad3d67bd06f063c0afb698afcfc76dd Verifying attestations