Agent work should feel reviewable, not mysterious. tooltrace is the little flight recorder for agent apps: calm, readable, and built to show the receipts.
A local-first activity timeline and proof-of-work layer for agent apps. ToolTrace turns raw runtime/tool events into a grouped review timeline, copyable proof summary, and embeddable React UI.
- Turn noisy JSONL/tool logs into proof a human can scan.
- Embed a polished React timeline without adopting a cloud observability stack.
- Generate copyable completion summaries for PRs, handoffs, and incident notes.
- Keep sensitive data local, redacted, and under your control.
npm install tooltraceReact is an optional peer dependency for tooltrace/react. Import tooltrace/styles.css if you want the default dark review timeline styling.
import { createTimeline, createProofSummary } from 'tooltrace';
const timeline = createTimeline(events, { includeRaw: false });
console.log(createProofSummary(timeline));Supported proof categories include messages, commands, tool calls, file changes, checks, approvals, errors/retries, blockers, PR/commit links, and completion proof.
import { ToolTrace } from 'tooltrace/react';
<ToolTrace
events={events}
mode="review"
showProofSummary
onOpenFile={(path) => openInEditor(path)}
/>;The component supports compact, grouped, and review/proof presentation via CSS classes and accessible keyboard-focusable groups/events.
tooltrace summary ./demo/crewcmd-run.jsonl
tooltrace render ./demo/crewcmd-run.jsonl --out TOOLTRACE.mdThe CLI accepts generic JSONL: one JSON event object per line.
import { agentPulseToToolTraceEvents, jsonlToToolTraceEvents } from 'tooltrace';
const fromAgentPulse = agentPulseToToolTraceEvents(agentPulseEvents);
const fromJsonl = jsonlToToolTraceEvents(jsonlText);Adapters preserve source metadata, apply safe defaults, and redact common credentials/tokens before generating UI-ready proof.
examples/node-summary.mjsrenders a proof summary from a local JSONL file.examples/react-embed.jsxshows a review panel with checklist and proof summary.tests/fixtures/contains success, blocked, and AgentPulse-style fixtures.
demo/crewcmd-run.jsonl simulates a CrewCmd-style task with a failed check, retry, file change, approval, commit, PR link, and final proof summary.
- Proof timeline information architecture
- Integration recipes
- Safety and privacy model
- Contributing guide
- Security policy
Run the local validation script before opening a pull request:
bash scripts/validate.shscripts/validate.sh runs package checks when present and skips optional agent-qc if it is not installed.
ToolTrace is local-first and does not perform network calls in core. Use custom redaction patterns for application-specific sensitive data.
MIT