Metadata-Version: 2.4
Name: clawtrace
Version: 0.1.3
Summary: Review, score, and curate your coding agent conversation traces locally
Author: kaiaiagent
License-Expression: MIT
Keywords: claude-code,codex,gemini-cli,opencode,openclaw,dataset,conversations
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# 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:

```bash
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/`

<details>
<summary><b>Install manually (without an agent)</b></summary>

```bash
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:**

```bash
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`

</details>

<details>
<summary><b>Terminal workflow (works on remote VMs — no browser needed)</b></summary>

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

```bash
# 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).

</details>

<details>
<summary><b>All commands</b></summary>

### 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 |

</details>

<details>
<summary><b>What gets exported & data schema</b></summary>

| 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:

```json
{
  "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
  }
}
```

</details>

<details>
<summary><b>Gotchas</b></summary>

- **`--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.

</details>

## License

MIT
