Explicit capture · small alpha

From a reviewed batch
to your first trace.

You need Python 3, a terminal and a Supatrace sign-in. The scripts use Python's standard library; no package install is needed.

Traces may contain prompts, tool output, personal information and secrets. Review what you select and remove anything you do not intend to store. Nothing here scans your machine, installs hooks or uploads automatically. Automatic Codex capture is not available.

1. Download the three scripts

Save these together in a new folder, then open your terminal in that folder. Read the scripts before running them.

The connection and snapshot scripts import upload.py, so keep all three together.

2. Approve a write-only connection

Open Agents in your workspace. Copy its project-specific command, or replace YOUR_PROJECT_ID below with the project ID shown there.

python3 connect.py --project YOUR_PROJECT_ID --config ./supatrace-access.json

The script creates a key locally and shows a 12-character setup code. Approve only the code your own agent just showed you. Once approved, the script saves write-only credentials to your selected config file with owner-only permissions.

Keep that config private. Never commit it or paste it into chat. The key lasts 30 days, cannot read traces and can be revoked in API keys. Use the same sign-in provider to return: Google and GitHub accounts are separate.

3. Send the reviewed synthetic example

Download first-trace.json into that folder and inspect it. It contains three synthetic events and no real transcript data. Then explicitly upload it:

python3 upload.py ./first-trace.json --config ./supatrace-access.json

Wait for Accepted by server. The uploader keeps a local pending copy until the server returns the matching batch ID, byte hash and project ID. A failed or ambiguous response leaves it pending; rerun with the same unchanged file to retry. Repeating this exact example is idempotent, not a second run.

4. Inspect and export

Open Traces, select Refresh, then open hello-supatrace. Compare the event contents with your example. Export JSON includes every accepted batch. Original exports are not automatically redacted; review the complete file before sharing.

5. Try a selected Claude Code snapshot

When the example works, choose one finished transcript yourself. The converter never searches your disk. Use a unique run ID and a clean output folder for each snapshot:

python3 claude_snapshot.py /path/to/selected-transcript.jsonl --run-id my-reviewed-snapshot --out ./reviewed-batches

Inspect every generated batch before uploading. The summary counts unsupported blocks or rows rather than claiming they were captured. Oversized blocks fail instead of being silently truncated. Upload reviewed batches one at a time in numbered filename order:

python3 upload.py ./reviewed-batches/BATCH.json --config ./supatrace-access.json

Do not mix old and new conversions under a reused run ID. Events within batches preserve their order; batches are exported in server acceptance order. Upload source chunks in order when that sequence matters.

Current limits

• One project per account. No teams or linked sign-in accounts.
• 10 MiB cumulative reserved bytes per account, including accepted and pending uploads. It does not reset monthly.
• 100 accounts and 100 MiB reserved bytes across this alpha. Global capacity can stop an upload before your own quota is full.
• 1–100 events per batch; 512 KiB per batch; 32 KiB per event's JSON data; nesting depth 32.
• 60 API requests per minute per network; 30 uploads per minute per account. Shared networks may share the request limit.
• Up to 10 active write keys, expiring after 30 days. Setup codes expire after 10 minutes.
• Claude snapshot input at most 20 MiB. Finished explicit snapshots only, not a live tailer.
• The run list covers a bounded subset of up to 800 run IDs; filters and totals do not cover omitted IDs.
• Unbilled alpha. Paid plans, upgrades and automatic quota cleanup are not available.

When something goes wrong

• Sign-in failed or expired: start a fresh sign-in from the workspace with the same provider. Do not refresh or share an OAuth callback URL.
• Setup expired: no key is granted by that response. Remove only the pending config you selected, then start a new connection. Approved configs are not silently replaced.
• Key expired or revoked: explicitly make and approve a new connection. Do not overwrite another project's config.
• Rate limit: keep the local batch unchanged and wait for the retry window. Export can pause and retry; Cancel stops its download.
• Storage capacity: your pending batch remains local. Quota does not reset monthly; repeated uploads cannot add capacity. Pending server reservations also consume quota.
• Network loss: keep the original transcript and pending file until you verify the accepted trace. Local spooling survives process exit, not a lost machine or disk.

There is no self-service trace/account deletion or published retention guarantee in this alpha. Terms and privacy policy are not yet published. Use synthetic or deliberately reviewed data for evaluation.

Back to workspace →