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> --htmlrenders a trajectory as a self-contained HTML page
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
No source distribution files available for this release.See tutorial on generating distribution archives.
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file trajectoriz-0.45.0-py3-none-any.whl.
File metadata
- Download URL: trajectoriz-0.45.0-py3-none-any.whl
- Upload date:
- Size: 37.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f0d8cb28d8272e215b36ef56c53255d3e52c5f7bfcc34ac975f8ea7abd229425
|
|
| MD5 |
fd7ca796ba6c0734e7d2d4ebba897d92
|
|
| BLAKE2b-256 |
87263ae76c5533688db9eb1c309f3056f9a711e304e8ae32000e5c72c1554ace
|
Provenance
The following attestation bundles were made for trajectoriz-0.45.0-py3-none-any.whl:
Publisher:
pypi-publish.yml on monperrus/trajectoriz
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
trajectoriz-0.45.0-py3-none-any.whl -
Subject digest:
f0d8cb28d8272e215b36ef56c53255d3e52c5f7bfcc34ac975f8ea7abd229425 - Sigstore transparency entry: 2501529739
- Sigstore integration time:
-
Permalink:
monperrus/trajectoriz@614a2e22bd92c755afbb22226ddff144dd79c8ba -
Branch / Tag:
refs/heads/main - Owner: https://github.com/monperrus
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
pypi-publish.yml@614a2e22bd92c755afbb22226ddff144dd79c8ba -
Trigger Event:
push
-
Statement type:
