🔍 TraceLog
Record, replay, and debug every step your AI coding agent takes.
The open-source observability layer for AI-assisted development.

---

What is TraceLog

TraceLog is a transparent activity recorder for AI coding agents. It intercepts every action — file reads/writes, shell commands, API calls, MCP tool invocations — and stores them in a local SQLite database. You can then replay, search, export, and debug the entire session.

Think of it as Sentry for AI agents. When Claude Code deletes your secrets.yml or runs rm -rf in the wrong directory, you can rewind and understand exactly what happened — in 30 seconds.

---

Why TraceLog / Why Now

AI coding agents are black boxes. Claude Code, Codex CLI, Cursor Agent, Aider — they operate through rapid sequences of tool calls, file modifications, and reasoning steps. When something goes wrong, you're left guessing:

• Which file did it read before making that decision?
• What was the exact shell command it ran?
• Why did it choose that approach?
• Which tool call produced the error?

Industry tools (LangSmith, Helicone, Arize) only see API calls. They miss the filesystem, shell, and MCP actions. TraceLog fills that gap.

---

Quick Demo

$ tl demo
🎬 TraceLog Demo Mode
情境：開發者叫 Claude Code 整理 config/ 目錄，Agent 誤刪了 secrets.yml...
✅ sess_6a9ac1d...  claude-code  10 steps ⚠️2

$ tl inspect sess_6a9ac1d... --anomalies-only
⚠️ [2] 📂 列出 config/ 目錄 [sensitive-secrets-file]
⚠️ [8] 🖥️ rm config/secrets.yml [destructive-rm]

---

Install

From source (recommended for now)

git clone https://github.com/lunkerchen/tracelog.git
cd tracelog
cargo build --release
sudo cp target/release/tl /usr/local/bin/
tl demo   # Verify it works

Requirements: Rust 1.80+, macOS 14+ or Linux. ~60MB of disk for build artifacts (binary is ~6MB).

Homebrew

brew install tracelog-dev/tap/tracelog

Cargo

cargo install tracelog

---

Quickstart

tl start --agent claude-code              # Start recording
# ... use Claude Code normally ...
tl stop                                    # Stop recording
tl sessions                                # List sessions
tl inspect <session> --anomalies-only      # See flagged steps
tl timeline <session>                      # ASCII timeline
tl export <session> --pretty -o trace.json # Export JSON
tl view --port 9876                        # Open local Web UI

Web UI

🌐 TraceLog Web UI → http://127.0.0.1:9876

# Open a specific session directly:
tl view --session sess_abc123...

# Custom port:
tl view --port 8080

Dark-themed local single-page app: session list → click to timeline → click step to expand detail.

---

How It Works

┌──────────────────────────────────────┐
│          AI Coding Agent             │
│  (Claude Code / Codex / Cursor)      │
└──────────────┬───────────────────────┘
               │ file I/O, shell, HTTP, MCP
               ▼
┌──────────────────────────────────────┐
│         TraceLog Interceptor         │
│  ┌──────────┐ ┌────────┐ ┌───────┐  │
│  │ File I/O │ │ Shell  │ │ HTTP  │  │
│  │  Hook    │ │ Hook   │ │ Proxy │  │
│  └────┬─────┘ └───┬────┘ └───┬───┘  │
│       └───────────┴──────────┘      │
│         Unix Domain Socket          │
└──────────────────┬───────────────────┘
                   ▼
┌──────────────────────────────────────┐
│      Daemon + Anomaly Engine          │
│  15 built-in security rules          │
└──────────────┬───────────────────────┘
               ▼
┌──────────────────────────────────────┐
│  SQLite (~/.tracelog/tracelog.db)    │
│  All data stays on your machine.     │
└──────────────────────────────────────┘

---

Commands

Command	Description
tl start --agent <name>	Start recording agent activity
tl stop	Stop the active session
tl status	Show recording status
tl sessions [--limit N] [--agent <name>] [--anomalies-only]	List all sessions
tl inspect <session> [--anomalies-only] [--type <event>]	Inspect session steps
tl timeline <session> [--from N] [--to N]	ASCII timeline viewer
tl export <session> [--pretty] [-o <path>]	Export as JSON trace
tl view [--port 9876] [--session <id>]	Launch local Web UI
tl demo	Built-in demo

---

Anomaly Detection (15 Rules)

Rule	Pattern	Risk	Description
dangerous-rm-rf	rm -rf	🛑	Recursive force delete
dangerous-sudo	sudo	⚠️	Privileged execution
dangerous-chmod-777	chmod 777	🛑	World-writable permissions
dangerous-curl-pipe-sh	curl | sh	🛑	Remote code execution
dangerous-git-push-force	git push --force	⚠️	Force push
dangerous-git-reset-hard	git reset --hard	🛑	Destructive reset
destructive-rm	any rm	⚠️	File deletion
sensitive-env-file	.env	⚠️	Environment variables
sensitive-pem-key	*.pem	🛑	Private keys
sensitive-ssh-dir	~/.ssh/	🛑	SSH credentials
sensitive-aws-dir	~/.aws/	🛑	AWS credentials
sensitive-secrets-file	file with "secret"	⚠️	Secrets exposure
sensitive-credentials	"credential"	⚠️	Credentials exposure
long-running	> 30s	ℹ️	Slow operations

---

Event Types (17)

Category	Events
Session	SESSION_START, SESSION_END
Filesystem	FILE_READ, FILE_WRITE, FILE_DELETE, FILE_CHMOD, FILE_CHOWN, FILE_RENAME, FILE_READDIR
Shell	SHELL_EXEC, SHELL_STDOUT, SHELL_STDERR
Network	HTTP_REQUEST, HTTP_RESPONSE
MCP	MCP_TOOL_CALL, MCP_TOOL_RESULT
Agent	AGENT_THINK, AGENT_ACT
User	USER_INPUT

---

JSON Trace Format

{
  "format_version": "1.0",
  "session": {
    "id": "sess_abc...",
    "agent": "claude-code",
    "total_steps": 10,
    "total_anomalies": 2
  },
  "events": [{
    "seq": 8,
    "event_type": "SHELL_EXEC",
    "summary": "rm config/secrets.yml",
    "risk_level": "danger",
    "duration_ms": 17
  }]
}

---

Security Model

• All data stays on your machine. SQLite at ~/.tracelog/. No cloud, no telemetry.
• Sensitive data masking. API keys, tokens, private keys are auto-redacted.
• Open source. Every line of interception code is visible.
• You control exports. Nothing leaves your machine unless you run tl export.

---

Project Structure

tracelog/
├── core/               # Event model, SQLite, anomaly engine (library)
├── cli/                # `tl` command — 9 subcommands + Web UI
├── daemon/             # Background daemon (WIP — future real-time recorder)
├── Cargo.toml          # Workspace root
├── LICENSE             # MIT
└── README.md

---

Roadmap

Phase	Timeline	Highlights
MVP ✅	Now	CLI + SQLite + 15 anomaly rules + JSON export + Web UI
v1	Q3 2026	Token cost analysis, Windows support, custom rules
v2	Q4 2026	Cloud sync (optional), CI/CD plugins, plugin ecosystem
Enterprise	2027	SSO, RBAC, compliance audit log, on-premise

---

Contributing

TraceLog is in early MVP stage. Contributions welcome:

1. Bug reports: Open an issue with your tl status output
2. Feature requests: Describe your agent debugging workflow
3. Code: Fork, make changes, submit a PR

git clone https://github.com/lunkerchen/tracelog.git
cd tracelog
cargo test
cargo build --release

---

License

MIT — see LICENSE.

---

_{Built with Rust. macOS & Linux. No cloud. Your data stays yours.}