Skip to content

qita Guide

Goal

Use qita as your default run inspection tool: board, view, replay, and export.

UI Snapshot

qita board

qita board

qita trajectory view

qita trajectory view

0) First create at least one run

Run any example with trace enabled (default):

python examples/patterns/react.py --workspace ./playground

This usually creates run artifacts under ./runs/<run_id>/ with:

  • manifest.json
  • events.jsonl
  • steps.jsonl

1) Start board

qita board --logdir runs

Open URL printed by CLI (default: http://127.0.0.1:8765/).

Board provides:

  1. run list and search/filter
  2. run-level metrics and status
  3. quick buttons: view, replay, export raw, export html

2) View one run (readable cards)

From board click view, or open directly:

http://127.0.0.1:8765/run/<run_id>

In view page:

  1. Traj tab for step-by-step cards
  2. Manifest tab for run metadata
  3. timeline and event sections
  4. font scaling and fold/unfold controls

3) Replay one run in browser

CLI mode:

qita replay --run runs/<run_id>

This opens focused replay mode at:

/replay/<run_id>

Use replay when you need to inspect temporal order of events and failures.

4) Export run artifacts

Export raw JSON bundle

From board/view click export raw, or open:

http://127.0.0.1:8765/export/raw/<run_id>

Export standalone HTML

From board/view click export html, or CLI:

qita export --run runs/<run_id> --html ./report/<run_id>.html

Use this to share one run snapshot without requiring a live server.

  1. run agent once
  2. open board and locate failed run by stop_reason
  3. open view and find first abnormal phase/event
  4. use replay to confirm event ordering
  5. export HTML for issue discussion or PR evidence

6) Common problems

  1. board shows no runs
  2. ensure --logdir points to the directory containing run subfolders

  3. ensure each run folder has manifest.json

  4. replay reports run not found

  5. pass full path to --run, e.g. runs/<run_id>

  6. malformed event line

  7. parser tolerates invalid lines, but fix upstream event writer if this repeats

If qita command is not found

If you installed QitOS without editable install, or your shell can't find console scripts, use:

python -m qitos.qita board --logdir runs

Source Index