clawtrace 0.1.3

Review, score, and curate your coding agent conversation traces locally

ClawTrace

Review and curate your coding agent conversation traces — 100% locally. ClawTrace scans session logs from Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Kimi CLI, and Cline, automatically anonymizes secrets and personal information, and gives you a browser workbench to review everything before it ever leaves your machine.

Requires Python 3.10+.

Your data stays local

• Nothing leaves your machine unless you explicitly choose to share.
• Secrets and PII are auto-redacted — API keys, tokens, passwords, and personal info are replaced with [REDACTED] before any export.
• Preview before sharing — clawtrace share --preview shows exactly what would be uploaded. No surprises.
• You choose what's included — approve, block, or exclude sessions and projects at every step.

What gets anonymized

Every export passes through multiple layers of automatic protection:

What	How it's protected
File paths	Stripped to project-relative paths. Your home directory and username are removed.
Your username	Replaced with an anonymous hash (e.g., user_a1b2c3d4), consistent across exports.
API keys & tokens	Auto-detected and redacted: Anthropic, OpenAI, GitHub, AWS, Slack, Discord, HuggingFace, PyPI, NPM, and more.
Passwords & database URLs	Connection strings and secrets in environment variables are caught and redacted.
Private keys	SSH, RSA, EC, and OpenSSH private keys are detected and removed.
Email addresses	Personal email addresses are replaced with [REDACTED].
Suspicious strings	Long random-looking strings (potential secrets) are flagged using entropy analysis.
Timestamps	Coarsened to hour-level in exports — exact times are not shared.
Custom strings	Add your own company names, domains, or project names to always redact.

Automated redaction catches the vast majority of secrets. For extra protection, add AI-assisted PII detection on top:

clawtrace export --pii-review --pii-provider hybrid

Get started

Already using a coding agent? Paste this into Claude Code, Codex, OpenClaw, Gemini CLI, or any coding agent:

Help me review and curate my coding agent traces using ClawTrace.
Everything runs 100% locally — nothing is uploaded without my approval.
Install it, set up the skill, then walk me through the process.

STEP 1 — INSTALL
  pip install clawtrace
  If pip fails, try: python3 -m pip install clawtrace
  If Python is missing, tell the user:
    macOS: "Open Terminal and run: brew install python && python3 -m pip install clawtrace"
    Windows: "Download Python from python.org/downloads — check 'Add to PATH' — then run: pip install clawtrace"
    Linux: "Run: sudo apt install python3-pip && python3 -m pip install clawtrace"
  If all else fails, ask the user where the clawtrace source directory is and run: pip install -e .

STEP 2 — INSTALL SKILL
  clawtrace update-skill claude

STEP 3 — SCAN & SCORE
  clawtrace scan
  clawtrace score --batch --auto-triage

STEP 4 — REVIEW
  clawtrace serve

Tell the user: "Your workbench is open at localhost:8384. Everything is 100% local.
Use the Inbox to triage traces, Search to find sessions, and Bundles to assemble exports."

Or just send your agent this link: https://pypi.org/project/clawtrace/

Install manually (without an agent)

pip install clawtrace
clawtrace scan          # Find all your local sessions
clawtrace serve         # Open review UI at localhost:8384

Everything runs locally. Browse sessions, see redacted content highlighted, approve or block traces, export when ready.

Optional — AI-assisted quality scoring:

clawtrace score --batch --auto-triage

New to Python? ClawTrace needs Python 3.10+.

• macOS: Open Terminal → python3 --version. If missing: brew install python && python3 -m pip install clawtrace
• Windows: Download from python.org/downloads (check "Add to PATH") → pip install clawtrace
• Linux: python3 -m pip install clawtrace. If pip missing: sudo apt install python3-pip

Terminal workflow (works on remote VMs — no browser needed)

The entire review-and-share workflow runs in your terminal. Your coding agent drives these commands for you.

# 1. Scan — discover and index sessions
clawtrace scan

# 2. Review — browse and triage
clawtrace inbox --json --limit 20
clawtrace search "refactor auth" --json

# 3. Triage — approve or block
clawtrace approve <session_id> --reason "clean trace"
clawtrace block <session_id> --reason "proprietary code"

# 4. Score (optional) — AI-assisted quality scoring
clawtrace score --batch --auto-triage

# 5. Preview — review what will be shared (shows summaries + risk flags)
clawtrace share --status approved --preview

# 6. Share — after user confirms
clawtrace share --status approved --note "week 12 traces"

For a visual review experience: clawtrace serve (local) or clawtrace serve --remote (prints SSH tunnel command for remote VMs).

All commands

Essential

Command	Description
clawtrace scan	Index local sessions into workbench DB
clawtrace serve	Open workbench UI at localhost:8384
clawtrace score --batch --auto-triage	AI-score sessions, auto-approve 4–5 and block 1–2
clawtrace share --status approved	One-step: bundle + export + share
clawtrace config --source all	Select source scope (claude, codex, gemini, opencode, openclaw, kimi, or all)

Review & triage

Command	Description
clawtrace inbox --json --limit 20	List sessions as JSON (for agent parsing)
clawtrace search <query> --json	Full-text search across sessions
clawtrace approve <id> [id ...]	Approve sessions by ID
clawtrace block <id> [id ...]	Block sessions by ID
clawtrace shortlist <id> [id ...]	Shortlist sessions for review
clawtrace score --batch --limit 20	AI-score up to 20 sessions without triage
clawtrace score-view <id>	View score details for a session
clawtrace set-score <id> <1-5>	Manually set a quality score

Bundles

Command	Description
clawtrace bundle-create --status approved	Create bundle from all approved sessions
clawtrace bundle-list	List all bundles
clawtrace bundle-view <bundle_id>	View bundle details and sessions
clawtrace bundle-export <bundle_id>	Export bundle to disk (JSONL + manifest)
clawtrace bundle-share <bundle_id>	Upload bundle to ClawTrace ingest service

Export & PII

Command	Description
clawtrace export	Export to local JSONL
clawtrace export --no-thinking	Exclude extended thinking blocks
clawtrace export --pii-review --pii-apply	Export, generate PII findings, and produce sanitized JSONL
clawtrace pii-review <file>	Run PII detection on an exported file
clawtrace pii-apply <file>	Apply PII redactions to an exported file
clawtrace pii-rubric	Show PII entity types and detection rules

Configuration

Command	Description
clawtrace config --exclude "a,b"	Add excluded projects (appends)
clawtrace config --redact "str1,str2"	Add strings to always redact (appends)
clawtrace config --redact-usernames "u1,u2"	Add usernames to anonymize (appends)
clawtrace list	List all projects with exclusion status
clawtrace status	Show current stage and next steps (JSON)
clawtrace update-skill claude	Install/update the clawtrace skill for Claude Code
clawtrace serve --remote	Print SSH tunnel command for remote VM access

What gets exported & data schema

Data	Included	Notes
User messages	Yes	Full text (including voice transcripts)
Assistant responses	Yes	Full text output
Extended thinking	Yes	Claude's reasoning (opt out with --no-thinking)
Tool calls	Yes	Tool name + inputs + outputs
Token usage	Yes	Input/output tokens per session
Model & metadata	Yes	Model name, git branch, timestamps

Each line in the exported JSONL is one session:

{
  "session_id": "abc-123",
  "project": "my-project",
  "model": "claude-opus-4-6",
  "git_branch": "main",
  "start_time": "2025-06-15T10:00:00+00:00",
  "end_time": "2025-06-15T10:30:00+00:00",
  "messages": [
    {"role": "user", "content": "Fix the login bug", "timestamp": "..."},
    {
      "role": "assistant",
      "content": "I'll investigate the login flow.",
      "thinking": "The user wants me to look at...",
      "tool_uses": [
          {
            "tool": "bash",
            "input": {"command": "grep -r 'login' src/"},
            "output": {"text": "src/auth.py:42: def login(user, password):"},
            "status": "success"
          }
        ],
      "timestamp": "..."
    }
  ],
  "stats": {
    "user_messages": 5, "assistant_messages": 8,
    "tool_uses": 20, "input_tokens": 50000, "output_tokens": 3000
  }
}

Gotchas

• --exclude, --redact, --redact-usernames APPEND — they never overwrite. Safe to call repeatedly.
• Source selection is REQUIRED before export — set clawtrace config --source claude|codex|gemini|opencode|openclaw|all.
• PII audit is critical — automated redaction is not foolproof.
• Large exports take time — 500+ sessions may take 1-3 minutes.

License

MIT