---
name: clawtrace
description: >
  Review, curate, and export coding agent conversation traces. Use when the user asks to
  review their traces, curate sessions, manage their workbench, export conversations,
  configure ClawTrace, or review PII/secrets in exports.
allowed-tools: Bash(clawtrace *), Bash(pip install clawtrace*), Bash(grep *)
---

<!-- clawtrace-begin -->

# ClawTrace Skill

ClawTrace helps scientists review, curate, and share their coding agent traces from Claude Code, Codex, and OpenClaw.

## Prerequisite

```bash
command -v clawtrace >/dev/null 2>&1 && echo "clawtrace: installed" || pip install clawtrace
```

Always ensure clawtrace is installed before running any command.

## Communication Guidelines

**Adapt to the user's technical level.** Most OpenClaw users are non-technical. When interacting with non-technical users (especially via Telegram, Discord, or other messaging channels):

- **Never show raw commands, UUIDs, file paths, or CLI flags.** Run the commands yourself and present only the human-readable results.
- **Never expose infrastructure details.** Do not show GCS bucket addresses, ingest service URLs, Cloud Function endpoints, or any internal system identifiers. If the JSON output contains fields like `gcs_uri`, `bundle_hash`, or `device_id`, suppress them entirely.
- **Use simple, non-technical language.** Say "your sessions" not "indexed sessions in the workbench DB." Say "uploaded" not "shared via ingest service."
- **When asked "how to use clawtrace"** — don't write a reference manual. Instead, run the commands yourself and guide the user interactively step by step.

**Always show what was redacted.** When sharing data, the share result includes a `redaction_summary` with `total_redactions` and `by_type`. Always present this to the user to build trust:

> Your data has been cleaned before sharing:
> - 3 API keys redacted
> - 2 JWT tokens redacted
> - 1 database URL redacted
> - All file paths anonymized, usernames hashed
>
> 5 sessions uploaded successfully.

If `total_redactions` is 0, still reassure:

> Your data was scanned for secrets, API keys, tokens, and PII — nothing sensitive was found. All file paths were anonymized and usernames hashed. 5 sessions uploaded.

**Never skip the redaction report.** The user must always know their data was checked and what (if anything) was removed.

## Two Modes

ClawTrace has two workflows:

1. **Workbench Mode** — Review and curate traces (local-first, scientist-facing)
2. **Export Mode** — Bulk export to local JSONL

Default to **Workbench Mode** unless the user specifically asks about bulk export.

---

## Workbench Mode

When the user asks to review traces, curate sessions, look at their work history, or manage data:

### Quick Start

```bash
clawtrace scan                              # Index sessions into local DB
clawtrace inbox --json --limit 15           # Show trace cards (JSON for you to parse)
```

Parse the JSON output. Each session has: `index`, `session_id`, `display_title`, `source`, `model`, `messages`, `tokens`, `outcome_badge`, `value_badges`, `risk_badges`, `review_status`.

Present the traces to the user as a numbered list showing title, source, badges, and status. Then ask: **"Quick triage here, or open the full review UI?"**

**On a remote VM or OpenClaw session?** Skip the browser — do the full review right here in the terminal. Follow the Review & Share steps below.

### Review & Share (interactive — works via terminal, Telegram, Discord)

**Step 1 — Scan & score**

```bash
clawtrace scan
clawtrace score --batch --auto-triage
```

Present summary:

> Found 47 sessions. 23 auto-approved (quality 4-5), 8 auto-blocked (1-2), 16 need review.

If on a remote VM or the user is running OpenClaw, default to terminal review — skip the question and go straight to Step 2.

Otherwise, ask:
> How would you like to review?
> - **"review here"** — I'll show the session list and we'll triage together (works everywhere)
> - **"open UI"** — I'll launch the workbench in your browser

If user chooses the UI:

```bash
clawtrace serve
```

Tell user: "Workbench is open at localhost:8384. Triage sessions in the Inbox, then come back and say 'share' when ready."

For remote VMs: `clawtrace serve --remote` prints the SSH tunnel command.

When user returns, continue to Step 2.

**Step 2 — Show preview**

```bash
clawtrace share --status approved --preview --json
```

Parse the JSON. Present up to 10 sessions at a time with the AI summary:

> 23 approved sessions. Here are the first 10:
>
> 1. Fix auth bug (score 5) — Excellent debugging session with clear root cause analysis.
> 2. Refactor DB layer (score 4) — Clean refactor with good test coverage.
> 3. Add parser tests (score 4) — Solid test writing for edge cases.
> 4. Memory leak investigation (score 3) — Partial investigation, no resolution. [secrets_detected]
> ...10 more items...
>
> You can:
> - Remove sessions: "remove 4"
> - Inspect one: "show me 4"
> - See more: "next 10"
> - Add a comment: "note: my week 12 patent traces"
> - Confirm all: "looks good" or "share"

**Step 3 — Handle user feedback (loop until confirmed)**

If user says "remove 4, 7":

```bash
clawtrace block <id-for-4> <id-for-7> --reason "user excluded"
```

Then re-run preview and present updated list.

If user says "show me 4":

```bash
clawtrace score-view <id-for-4>
```

Present the condensed session transcript, then return to the preview.

If user adds a note, remember it for the `--note` flag.

If user says "looks good" / "share" / "yes" → proceed to Step 4.

**Step 4 — Share with confirmation**

Only after explicit user confirmation:

```bash
clawtrace share --status approved --note "<user's comment>" --json
```

Parse the JSON result. The `redaction_summary` field shows what was cleaned. **Always report the redaction summary to the user** (see Communication Guidelines above). Example:

> Uploaded 21 sessions successfully.
>
> Privacy report: 12 API keys, 3 JWT tokens, and 2 database URLs were automatically redacted. All file paths anonymized, usernames hashed.

For non-technical users, keep it simple and reassuring. Never show `bundle_id`, `bundle_hash`, `gcs_uri`, or other internal fields.

### Quick Triage (without scoring)

If the user wants manual triage without AI scoring:

```bash
clawtrace inbox --json --limit 15
```

Show numbered list. Take instructions like "approve 1,3,5" or "block 2":

```bash
clawtrace approve <session-id> [session-id ...] --reason "good debugging trace"
clawtrace block <session-id> [session-id ...] --reason "contains proprietary code"
```

Map the user's index numbers to session_ids from the inbox JSON output.

### Full Review (web UI)

When the user wants deeper review — reading full transcripts, searching across sessions, or assembling bundles:

```bash
clawtrace serve
```

This opens a browser at `localhost:8384` with:
- **Inbox**: Trace cards with value/risk/outcome badges and one-click triage
- **Search**: Full-text search across all session transcripts
- **Session Detail**: Three-pane view (timeline | transcript | metadata)
- **Bundles**: Assemble and export curated upload sets
- **Policies**: Manage redaction rules and project exclusions

Tell the user: "The workbench is open in your browser. Use the Inbox to triage traces, Search to find specific sessions, and Bundles to assemble what you want to share."

### Quick Share (via Telegram, Discord, or any messaging channel)

When the user wants to quickly share a trace — no approval workflow, no bundles, just send it.

**Step 1 — Show recent sessions**

```bash
clawtrace recent --source openclaw --json --limit 5
```

Parse the JSON. Present as a numbered list:

> Recent sessions:
>
> 1. Auth Middleware Fix — 23 min · 4/5 · Tests passed
> 2. Debug Memory Leak — 45 min · 3/5 · Tests failed
> 3. Add Parser Tests — 12 min · 5/5 · Tests passed
>
> Reply "share 1" to send a card, or "details 2" for more info.

**Step 2 — User picks a session**

If user says "share 1" or "share the first one":

```bash
clawtrace card <session-id-from-step-1> --depth summary --json
```

Parse the JSON. The `card_text` field is pre-formatted and ready to send. Send it via the messaging channel (Telegram reply tool, Discord webhook, etc.).

If user says "share 1 to team chat" — send the `card_text` to the specified destination.

**Depth options** (user can specify, or agent chooses based on context):
- `--depth workflow` — safe for public channels (no content, just tool sequence + stats)
- `--depth summary` — safe for team channels (task descriptions, no code) **← default**
- `--depth full` — for trusted recipients (full redacted content)

**Step 3 — Handle follow-ups**

- "share 2 as workflow" → `clawtrace card <id> --depth workflow --json`
- "details 2" → `clawtrace card <id> --depth full --json` and show in chat
- "show me this week" → `clawtrace recent --since "this week" --json --limit 15`

**Interaction cheat sheet:**

| User says | Agent does |
|-----------|-----------|
| "my recent sessions" / "what did I do?" | `clawtrace recent --json` → show list |
| "share 1" / "send 1" | `clawtrace card <id> --json` → send card |
| "share 1 as workflow" | `clawtrace card <id> --depth workflow --json` |
| "details 2" | `clawtrace card <id> --depth full --json` → show in chat |
| "share 1 to team chat" | `clawtrace card <id> --json` → send to other chat |

### Remote VM / OpenClaw (full triage workflow)

If you're on a remote VM (common with OpenClaw) and the user wants the full review + curated sharing workflow:

1. `clawtrace scan --source openclaw` — index your sessions
2. `clawtrace score --batch --auto-triage` — AI-score and auto-triage
3. `clawtrace inbox --json --limit 15` — show traces (present to user as numbered list)
4. Triage with user: `clawtrace approve <id>` / `clawtrace block <id>`
5. `clawtrace share --status approved --preview --json` — preview what will be shared
6. After user confirms: `clawtrace share --status approved --json` — parse the JSON and **always show the redaction summary**

**Important for OpenClaw users:** Most are non-technical. Do not show them raw commands, UUIDs, or internal details. Run the commands silently and present only the results in plain language. Always end with a privacy/redaction report so they know their data was cleaned.

For a browser UI via SSH tunnel: `clawtrace serve --remote`

### Workbench Commands

```bash
# Quick Share
clawtrace recent [--source openclaw] [--since today] [--limit 5] [--json]  # Recent sessions
clawtrace card <id> [--depth workflow|summary|full] [--json]               # Share card

# Triage & Review
clawtrace scan [--source claude|codex|openclaw]     # Index sessions into local DB
clawtrace inbox [--status new|shortlisted|approved|blocked] [--limit 20]  # Terminal view
clawtrace inbox --json [--status ...] [--limit 20]  # JSON output for agent parsing
clawtrace approve <id> [id ...] [--reason "..."]    # Approve sessions
clawtrace block <id> [id ...] [--reason "..."]      # Block sessions
clawtrace shortlist <id> [id ...]                    # Shortlist sessions
clawtrace search <query> [--json] [--limit 20]       # Full-text search
clawtrace share --status approved [--note "..."]      # One-step: bundle + export + share
clawtrace bundle-create [ids ...] [--status approved] # Create bundle
clawtrace bundle-list                                # List bundles
clawtrace bundle-view <bundle_id>                    # View bundle details
clawtrace bundle-export <bundle_id>                  # Export to disk
clawtrace bundle-share <bundle_id>                   # Upload bundle
clawtrace serve [--port 8384] [--no-browser] [--remote] # Launch web UI
```

---

## Export Mode

When the user asks to bulk export their conversations locally:

### THE RULE

**Every `clawtrace` command outputs `next_steps`. FOLLOW THEM.**

Do not memorize the flow. Do not skip steps. Do not improvise.
Run the command → read the output → follow `next_steps`. That's it.

### Getting Started

Run `clawtrace status` (or `clawtrace prep` for full details) and follow the `next_steps`.

### Output Format

- `clawtrace prep`, `clawtrace config`, `clawtrace status`, and `clawtrace confirm` output pure JSON
- `clawtrace export` outputs human-readable text followed by `---CLAWTRACE_JSON---` and a JSON block
- Always parse the JSON and act on `next_steps`

### PII Audit

After `clawtrace export --no-push`, follow the `next_steps` in the JSON output. The flow is:

1. **Ask the user their full name** — then grep the export for it
2. **Run the pii_commands** from the JSON output and review results with the user
3. **Ask the user what else to look for** — company names, client names, private URLs, other people's names, custom domains
4. **Deep manual scan** — sample ~20 sessions (beginning, middle, end) and look for anything sensitive the regex missed
5. **Fix and re-export** if anything found: `clawtrace config --redact "string"` then `clawtrace export --no-push`
6. **Run `clawtrace confirm` with text attestations** — pass `--full-name`, `--attest-full-name`, `--attest-sensitive`, and `--attest-manual-scan`. It runs PII scan, verifies attestations, and shows project breakdown.

### Export Commands

```bash
clawtrace status                            # Show current stage and next steps (JSON)
clawtrace prep [--source all|claude|codex|gemini|opencode|openclaw]  # Discover projects (JSON)
clawtrace list [--source ...]               # List all projects with exclusion status
clawtrace config --source all               # REQUIRED source scope
clawtrace config --exclude "a,b"            # Add excluded projects (appends)
clawtrace config --redact "str1,str2"       # Add strings to redact (appends)
clawtrace config --redact-usernames "u1,u2" # Add usernames to anonymize (appends)
clawtrace config --confirm-projects         # Mark project selection as confirmed
clawtrace export --no-push                  # Export locally
clawtrace confirm --full-name "NAME" --attest-full-name "..." --attest-sensitive "..." --attest-manual-scan "..."
```

---

## Install Skill for Other Agents

```bash
clawtrace update-skill claude               # Install to .claude/skills/clawtrace/
clawtrace update-skill openclaw             # Install to project root as CLAWTRACE_AGENTS.md
clawtrace update-skill codex                # Install to project root as CLAWTRACE_AGENTS.md
clawtrace update-skill cline                # Install to .cline/clawtrace/
```

## Gotchas

- **`--exclude`, `--redact`, `--redact-usernames` APPEND** — they never overwrite.
- **`clawtrace inbox --json`** is the preferred way for agents to read trace data.
- **`clawtrace approve/block/shortlist`** output JSON with results.
- **`clawtrace serve`** opens a browser automatically. Use `--no-browser` to suppress.

<!-- clawtrace-end -->
