Installation
pipx
pipx install opentraces
brew
brew install JayFarei/opentraces/opentraces
skills.sh
npx skills add jayfarei/opentraces
Installs the opentraces skill via skills.sh so your coding agent can drive the full workflow (init, review, push) conversationally. Works with Claude Code, Cursor, Codex, and any agent that supports skills. opentraces init also auto-installs the skill when you initialize a project.
Copy to your agent
Paste this into your coding agent (Claude Code, Cursor, Codex, etc.):
Set up opentraces in this project for trace collection.
Step 1 - Install or update:
Check if `opentraces --version` works.
If not installed, run: pipx install opentraces
If already installed, run: opentraces upgrade
Step 2 - Authenticate:
Run `opentraces auth status` to check if already logged in.
If not authenticated, ask the user to run `opentraces login` themselves
to authorize in the browser (this pushes to existing datasets).
If they want to create new datasets directly from opentraces,
they need a write-scope token: `opentraces login --token` with a
token from https://huggingface.co/settings/tokens.
Step 3 - Initialize:
Detect which agent you are (claude-code, cursor, etc.) and run:
`opentraces init --agent <agent> --review-policy review --import-existing`
This creates a private HuggingFace dataset, installs the session capture
hook, and installs the opentraces skill into this project.
Once initialized, read the skill at .agents/skills/opentraces/SKILL.md
for the full command reference and workflows.
The agent installs the CLI, authenticates, and initializes. init handles the skill installation automatically. After that the agent uses the skill file for everything else.
From Source
git clone https://github.com/jayfarei/opentraces
cd opentraces
python3 -m venv .venv
source .venv/bin/activate
pip install -e packages/opentraces-schema
pip install -e ".[dev]"
Verify Installation
opentraces --version
System Requirements
| Platform | Status |
|---|---|
| macOS (ARM64, x86_64) | Supported |
| Linux (x86_64, ARM64) | Supported |
| Windows (WSL) | Supported via Linux binary |
Python 3.10 or later is required.
Upgrading
The preferred in-project upgrade path is:
opentraces upgrade
Auto-detects whether you installed via pipx, brew, or pip and upgrades accordingly. Also refreshes the skill file and session hook in the current project.
If you are outside a project context, use the direct package manager command instead:
pip install --upgrade opentraces
Uninstalling
pip uninstall opentraces
To also remove local data and credentials:
rm -rf ~/.opentraces