jayfarei/opentraces/skill

opentraces

OpenTraces captures local agent traces, links them to Git evidence with Trace Trails, lets workflows turn one or more traces into local datasets, and then publishes reviewed dataset rows to HuggingFace remotes.

Current Command Model

v7 CLI spine (PR #174, issues #160-#165): one command surface, progressively disclosed. Hidden never means removed — every demoted verb below stays fully callable and --json-scriptable; --help just stops advertising it.

• Global setup: opentraces setup, opentraces auth login, opentraces bucket connect (was setup bucket), opentraces setup skill, opentraces upgrade (root peer verb, was setup upgrade), opentraces uninstall (root peer verb, the symmetric reverse-of-install), opentraces auth
• Project setup: opentraces init, opentraces status (now the fleet bucket-safety dashboard), opentraces doctor, opentraces remove
• Trace retrieval and search (8 -> 4 collapse): opentraces trace query, opentraces trace get, opentraces trace map, opentraces trace slice. Hidden-but-callable: trace discover, trace skills (folded into trace query --skill), trace index (folded into query/map/get's self-maintaining snapshot), trace partition (folded into trace slice --by), trace compare, trace teleport.
• Trace Intelligence: opentraces trace map|get --waste, opentraces trace map|get --run-intel, opentraces trace compare (hidden-but-callable)
• Trace slicing: opentraces trace slice <target> --by user-turn|change-burst|milestone|subgoal --json decomposes a trace into a tiling array of trajectories (opentraces.slicing.v1); absorbs the former trace partition --by s1|s2|s3|s4 (which stays hidden-but-callable under its old spelling). user-turn + change-burst are deterministic; milestone + subgoal are cheap-LLM. With --by milestone|subgoal and the default --judge agent, if judgments are needed the command exits rc=10 printing JudgmentRequests — answer them, write {"answers": [{"id","decision","confidence"}]} to a file, and re-run with --answers <file> for the final tiling at rc=0.
• Trace Trails (visible surface): opentraces trail blame commit <sha> (also bare opentraces trail blame <sha>), opentraces trail pr render|create|update (lifted to a top-level sibling of blame; trail blame pr ... stays hidden-but-callable), opentraces trail graph, opentraces trail track, plus the bare address opentraces trail <trace_id>[:step]
• Context Tree: the bare-noun read opentraces ctx <trace_id>, opentraces ctx <trace_id>:<step>, opentraces ctx <trace_id>:last (--layer system|messages|tools|runtime, --full, --with-dropped); the old subcommand surface (tree/show/step/reads/writes/diff/compactions/prune/resume/resolve/anchor-for-step, plus list/info) stays callable, hidden from --help
• Bucket (portable capture store): opentraces bucket list, opentraces bucket verify, opentraces bucket repair, opentraces bucket reclaim, opentraces bucket sync push/pull/diff/status, opentraces bucket connect. Hidden-but-callable: bucket status, bucket manifest, bucket remote push/pull/diff/status, bucket replay, bucket rebuild, bucket prune, bucket prefetch
• Dataset workflows: opentraces workflow create, opentraces workflow list, opentraces workflow templates, opentraces workflow remove, plus the internal opentraces workflow skill-intelligence eval over skill episodes
• Datasets: opentraces dataset list/new/run/verify/review/publish/remote/schedule/status/remove/security. Review transitions are opentraces dataset review approve|reject|reset <name> [row_id...]. Per-dataset egress security is opentraces dataset security <name> [--tool <t> --enable|--disable] [--unsafe-override --reason <text>]. dataset verify <name> replays the bound workflow against the bucket and classifies the result reproduces/bucket-advanced/integrity-failure.
• Capsules (the seal-family's other seal, ADR-0008): opentraces capsule create <ref>, capsule get <ref> (read-only, stateless), capsule import <ref> (the explicit opt-in write), capsule preview <trace_id>, capsule share [--publish], capsule issue, capsule replay --against <ref>, capsule test <ref>, capsule verdict <issue_ref> --state <state>, capsule watch <issue_ref>. Hidden-but-callable legacy spellings: capsule export (-> create), capsule open (-> get).
• Skill verifier (trace-grounded reward for SkillOpt): opentraces skill-verifier status/autoverify/align/score
• Security tools: opentraces security tools list/info, opentraces security sanitize --tools <names> or --use-config
• OTLP capture source: opentraces setup capture-otlp, opentraces capture-otlp start|stop|status|restart|flush

Old flat inbox commands such as opentraces list, add, reject, push, pull, web, and tui are not part of the public command tree. Several Trace Trails substrate commands (trail explain, sync, timeline, teleport, resolve, attach, rebuild, diff, resume, snapshots, snapshot checkout) remain callable for scripting and debugging but are hidden from --help after the CLI spine simplification.

Addressing and the agent contract

opentraces <trace-id>[:step | :last | :A-B] root-dispatches to trace get; the same trace:step join key resolves across trace get, ctx, and trail — the "resume triple" of action, context, and world. Each substrate honors as much of the grammar as it has materialized: trace get the full [:step | :last | :A-B], ctx [:step | :last], and trail [:step] only (its :last/:A-B slots are reserved for v1.1). A bare token at the root only ever dispatches when no existing command name matches it, so no verb, hidden or visible, can be shadowed by a trace id.

Under explicit --json, stdout is pure JSON — no ---OPENTRACES_JSON--- sentinel and no leading human text — so opentraces --json <cmd> | jq is always valid JSON (piped stdout without --json keeps the sentinel preamble for legacy consumers). A command that would otherwise drop into an interactive prompt refuses to do so under --json or on a non-interactive terminal: it emits a structured INTERACTIVE_REQUIRED error and exits 2, with zero prompt bytes.

Setup

opentraces setup
opentraces auth login
opentraces bucket connect        # configure remote-by-default private bucket sync (was `setup bucket`)
opentraces setup codex-cli       # install terminal Codex CLI hooks in ~/.codex/hooks.json
opentraces setup pi              # check/install the Pi package entry
opentraces setup skill           # install the opentraces skill into agent harnesses
opentraces setup skill --harness codex-cli
opentraces setup skill --harness pi
opentraces upgrade                # upgrade CLI + re-render installed integration glue + refresh project skill file (root peer verb, was `setup upgrade`)
opentraces upgrade --integrations-only  # re-render installed hooks/watchers without a CLI bump
opentraces upgrade --skill-only         # refresh only the skill file + hook, skip the CLI upgrade
opentraces uninstall --dry-run   # reverse-of-install plan (recommended first); root peer verb, was `setup uninstall`
opentraces uninstall --integrations-only  # default: reverse install-time patches + daemons, PRESERVE captured data
opentraces uninstall --purge --yes        # also DELETE captured data + git refs (unrecoverable)
opentraces config tracking-mode  # show; pass global|manual to set
opentraces config get <key>      # single-key config read (opentraces.config.get.v1)
opentraces auth whoami
opentraces init
opentraces init --agent codex-cli
opentraces init --agent pi
opentraces status
opentraces status --short
opentraces doctor

opentraces status is the O(1) fleet bucket-safety dashboard (envelope opentraces.bucket.status.v1): scanned/unscanned trace counts across every registered project, with a "safe to sync" verdict that is structurally impossible while any trace is still unscanned. --short prints a stable one-line porcelain summary (status=... traces=... unscanned=... not_cleared=... stale=...), --full adds the per-project debugger detail, --project <slug> scopes every count and the verdict to one project. The former per-project capture inbox (stage counts, active remote, most recent traces) is now the hidden opentraces status-inbox.

opentraces --json doctor exposes the agent-readable CLI freshness fields at doctor.cli: {installed_version, latest_version, upgrade_available}. When upgrade_available is true, run opentraces upgrade; when doctor reports integration drift, run opentraces upgrade --integrations-only to re-render already-installed glue without enabling new integrations. You do not need to inspect doctor.cli yourself: when an upgrade or repair is warranted, opentraces --json doctor also surfaces the action at the top-level next_command / next_steps fields (the standard agent contract) — run that next_command.

setup is machine-global: tracking mode, hooks, auth, watcher, TruffleHog, LLM review, and supporting binaries. Tracking mode (opentraces config tracking-mode) controls enrollment: global (default) auto-enrolls every agent — Claude, Codex, and Pi — git or not, private + review-required the first time a capture hook or the Pi extension fires there, so init is optional; manual keeps the explicit per-project opentraces init opt-in. Capture is opt-out: switch to manual, or set a per-project excluded marker / opentraces remove, to turn it off (raw provider bodies stay default-off regardless). init is project enrollment only; dataset remotes and review policy belong under opentraces dataset .... Private bucket configuration belongs under opentraces bucket connect (the rename of setup bucket, which stays callable, hidden) and opentraces bucket sync (the rename of bucket remote).

opentraces setup skill writes one canonical skill copy under ~/.agents/skills/opentraces/ and symlinks supported harnesses to it. Current harness targets are claude-code, codex-cli, and pi; pass --harness <name> to refresh only one link.

Codex support is for terminal Codex CLI, not Codex Desktop. Install and authenticate Codex first, then run opentraces setup codex-cli once and opentraces init --agent codex-cli in each repo. Hooks are passive observers: they record sidecars under .opentraces/codex-cli/hooks/ and must not approve or deny permission prompts. Codex capture starts with future sessions; --import-existing is a Claude Code backfill path.

Pi support is extension-backed. Install with pi install npm:opentraces-pi, use /ot-setup or opentraces setup pi --dry-run --json for the local checklist; under global tracking (default) capture is automatic once the opentraces CLI is present, or run opentraces init --agent pi to enroll a repo explicitly. Pi sidecars land under .opentraces/pi/events/ and flow through the same TraceRecord, Trace Trails, Context Tree, and bucket v2 pipeline. Raw provider bodies stay default-off.

Inside Pi, use slash commands for quick private-bucket retrieval and setup: /ot-capture-status, /ot-setup, /ot-search <query>, /ot-trace <trace-id>, /ot-standup, /ot-capsule [trace-id], and /ot-dataset. Model-facing tools are ot_capture_status, ot_search, ot_trace, ot_standup, ot_capsule, and ot_dataset. Prefer /ot-search/ot_search first, then /ot-trace or ot_trace for a selected bucket trace. Direct slash commands are TUI actions; model-invoked ot_* tools are captured as read-only opentraces_retrieval tool calls.

Trace Retrieval

Use trace commands when an agent needs compact evidence before loading full transcripts.