Replayable execution debugging for non-deterministic and agentic workflows.
Wrap an existing command, capture execution traces, and turn them into actionable insight.
Current public release line: v0.3.x.
AI workflows are inherently non-deterministic.
When something breaks, logs rarely explain:
- why the system chose a different path
- why behavior changed between runs
- how to reproduce the failure
HiveOS Trace captures execution and turns it into a replayable execution model.
Instead of just logs, it derives execution anchors — boundaries where a workflow safely closed — allowing developers to inspect runs, compare behavior, and replay execution from meaningful points.
pipx install hiveos-trace
Fallback:
python -m pip install hiveos-trace
hive quickstart
No-browser variant:
hive quickstart --no-open
hive trace run --no-open -- python -c "print('hello trace')"
hive trace ls --limit 5
hive trace insight explain <run_id>
Inspect replay anchors:
hive trace anchors <run_id>
Generate a replay plan:
hive trace replay-plan <run_id> --recommended --explain
# validate event payloads before ingest
hive trace tei validate --file docs/examples/tei_batch.json --json
# ingest structured step/tool lineage events
hive trace tei ingest --file docs/examples/tei_batch.json --jsonNotes:
hive trace tei ingestrequiresHIVE_TRACE_TEI_INGEST_ENABLED=true.- This is optional. Wrapper mode works without emitter integration.
- Primitives:
hive trace ... - Insight macros:
hive trace insight ... - Ops lifecycle:
hive trace ops ... - TEI utilities:
hive trace tei ...
| Integration level | What works |
|---|---|
| Zero instrumentation (wrapper only) | trace run, trace ls, trace show, trace summary, trace diff, trace diagnose, trace insight explain/drift/health |
| OpenAI-compatible provider path | trace run --proxy ... request/response envelope capture plus normal run primitives |
| Instrumented workflow (step/checkpoint emitters) | TEI validation/ingest (trace tei validate/ingest), anchor discovery (trace anchors), anchored replay (--from-step-id, --from-checkpoint-id), replay planning (trace replay-plan), richer flow lineage (trace flow ...) |
- Local-first: no required cloud account
- Works immediately as a wrapper
- Deeper value when instrumented (lineage + anchors)
- Replay, comparison, and diff for debugging non-deterministic behavior
- Macro insights (
explain,drift,health) with provenance
hive trace run --no-open -- python -c "print('demo-success')"
hive trace run --no-open -- python -c "import sys; sys.stderr.write('demo-fail\n'); raise SystemExit(2)"
hive trace ls --limit 5
# pick run IDs from ls output
hive trace insight explain <run_id>
hive trace insight health --window 24h
hive trace insight drift <run_id_a> <run_id_b>
- Anchors require emitted
step_id/checkpoint_idevents. insight healthis heuristic, not a policy-enforced SRE gate.- Autonomous self-repair loops are a roadmap direction, not current default behavior.
