.agents / traces
Append-only JSONL session traces.
One daily file. Assemble rebuilds the chat payload for one request.
Quickstart
pip install agents-traces && agents-traces init
Creates ~/.agents/traces/, copies skills, and merges MCP into host configs whose directories already exist.
Source checkouts can also be installed and managed with vand.
What it does
Each UTC day is one append-only file: ~/.agents/traces/YYYY-MM-DD.jsonl (override AGENTS_TRACES_DIR). No daemon, no database. Append is a file write.
Inspect. MCP reads the same files an agent just wrote: timeline, recent errors, token and cost totals, per-model failure rates.
Assemble. agents-traces assemble --session <id> rebuilds chat-completions messages for that session from the JSONL. Tool bodies can be dropped; user turns stay.
Session text. session_snap, session_grep, and session_tail search message text in this store. They do not read agents-memory.
Ingest. ingest copies IDE transcripts (Antigravity, Cursor, Claude, Cline) into the daily files. Live sessions already on disk are not duplicated.
Retention. cleanup deletes files older than --keep-days (default 30). --compress gzips them instead.
Bare agents-traces (no subcommand) prints today's stats. The MCP server is serve or mcp, not the default.
Where it runs
Floor: any MCP client or a terminal. python -m agents_traces serve is enough.
init autowires hosts it finds. It does not install an IDE.
| Layer | What you get | Who |
|---|---|---|
| JSONL + MCP/CLI | Record, inspect, stats, assemble | Any MCP host / any shell |
| Autowire on init | Merge agents-traces into the host MCP file when that config directory already exists; copy trace-inspect and trace-stats |
Cursor, Claude Desktop, Zed (context_servers), Antigravity / Gemini, Windsurf, Codex, Roo, Cline. Skills land in ~/.agents/skills, ~/.cursor/skills, ~/.gemini/config/skills |
MCP without autowire: point the host at python -m agents_traces serve.
MCP tools
Primary surface. Agents diagnose a failed loop here.
| Tool | What it does |
|---|---|
get_last_session_trace |
Timeline for one session, or the latest. Optional trace: prefix on the id |
get_recent_errors |
Failed tool calls with args and stack |
get_session_stats |
Tokens, estimated cost, tool success for the last N days |
get_model_stats |
Same window, split by model, with failure rates |
record_trace |
Append one event |
ingest_traces |
Pull IDE transcripts into the daily files |
session_snap |
Recent user messages in the traces store |
session_grep |
Search those messages |
session_tail |
Last lines for one session, or the latest |
trace_seal |
Cryptographically seal tool calls into a SHA-256 hash chain |
trace_verify |
Verify cryptographic integrity of a sealed hash chain |
trace_audit |
Audit for non-determinism, redundant calls, and scope violations |
Twelve tools. Full contract: abi/MCP.md.
CLI
Ops / install / batch. Machine-readable catalog: python -m agents_traces --help-json (do not scrape --help).
| Command | Purpose |
|---|---|
agents-traces init |
Traces dir, skills, MCP merge |
agents-traces stats [--date YYYY-MM-DD | --days N] [--by-model] [--json] |
Tokens, cost, tool rates. No flags = today |
agents-traces analyze-models [--days N] |
Stats split by model (default 7 days) |
agents-traces inspect [session-id] |
Terminal timeline. No id = latest session |
agents-traces sessions [--days N] [--limit N] |
Recent sessions with token and cost totals |
agents-traces tail [-n N] [-f] [--raw] |
End of today's file. -f follows |
agents-traces record … |
Append one event from a shell |
agents-traces assemble --session ID [--limit N] [--days N] [--include-tools] |
Rebuild chat messages for that session |
agents-traces ingest |
IDE transcripts → daily JSONL |
agents-traces cleanup [--keep-days N] [--compress] |
Delete old files, or gzip them |
agents-traces seal [session|file] [-o out] |
Seal tool calls into SHA-256 hash chain |
agents-traces verify <file> |
Verify cryptographic hash chain integrity |
agents-traces audit [session|file] [--scope file] |
Replay audit for non-determinism & redundancy |
agents-traces serve / mcp |
stdio MCP. Not the default command |
agents-traces skills / sync-mcp |
Re-copy skills, or re-merge MCP |
ABI
Layout and contracts in abi/:
WHY.md— JSONL instead of a tracing stackLAYOUT.md— daily filesSCHEMA.md— event fieldsMCP.md— tool surfaceCLI.md— commands
Tests
python tests/run_all_tests.py
License
MIT. See LICENSE.
Release files for agents-traces 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| agents_traces-0.1.0.tar.gz | 64.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agents_traces-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 125.4 kB
Release files / agents_traces-0.1.0.tar.gz
| Download URL | agents_traces-0.1.0.tar.gz |
|---|---|
| Size | 64.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
279089d69c96fcc1d49d31ca4776954e002c4caab6d25b6dccf4770c80333608
|
|
BLAKE2b-256 checksum How to use checksums |
c88555ff0e603ac0d0e6c4c7aada6b217b6e4f63803d13e5aa90320dd665e677
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / agents_traces-0.1.0-py3-none-any.whl
| Download URL | agents_traces-0.1.0-py3-none-any.whl |
|---|---|
| Size | 60.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
12c64fb2a67f827947b82c56a0dfe890c2b1aaa7831fa96cfa21ff896d55c002
|
|
BLAKE2b-256 checksum How to use checksums |
a1fa0c6dbe4c949008f80601cbbf59c798a1d79220a5ef3fadf43eb8915f716b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
