Quick Start

From local inbox to published dataset.

1. Install

pipx install opentraces

2. Authenticate

opentraces login --token

Paste a HuggingFace access token with write scope from huggingface.co/settings/tokens. Use HF_TOKEN instead if you are running headless.

3. Initialize the Project

opentraces init --review-policy review --start-fresh

This creates .opentraces/config.json, .opentraces/staging/, the agent session hook, and installs the opentraces skill into .agents/skills/opentraces/. If you omit the flags, opentraces init will prompt for the same choices interactively.

If your agent already has session logs for this repo, pass --import-existing to pull that backlog into the inbox now. Use --start-fresh if you only want capture from your next connected session onward.

4. Open the Inbox

Web inbox

opentraces web

The browser inbox shows a timeline of each session's steps, tool calls, and reasoning. Switch to the review view to see context items grouped by source.

Terminal inbox

opentraces tui

The TUI shows sessions, summary, and detail in a three-panel layout. Use keyboard shortcuts to navigate, commit, reject, or discard traces.

Use session list, session commit, session reject, and session redact if you prefer direct CLI control.

5. Commit and Push

opentraces commit --all
opentraces push

commit moves inbox traces to the committed stage. push uploads committed traces to {username}/opentraces on Hugging Face Hub as sharded JSONL and updates the dataset card.

What Happens Next

Your traces are available as a Hugging Face dataset:

from datasets import load_dataset

ds = load_dataset("your-name/opentraces")

Next Steps

• Security Modes - Review policy and security pipeline
• CLI Reference - Full command reference
• Schema Overview - What is stored in a trace record