OpenTokenMini
Get the code →Get our help →
For agents
04-auto-analysis/orch-ux/AGENTS.md · raw · GitHub

orch-ux

UX of the orchestrator (the main Claude Code agent talking to the human), so it can calibrate how much it reports and nudge itself. Per human turn: user words, words of the final visible reply (text after the last tool use), tool calls, subagents launched, duration, and how the human reacted next: correction, more, neutral, interrupt or reject. Derives a target reply length from the data and rule-based nudges. Specs: METHOD.md (U-*).

  • Input: main transcripts ~/.claude/projects/*/<sid>.jsonl (or config readers.paths.claude-code, or --root); worker transcripts <sid>/subagents/agent-<id>.jsonl only for their peak context. Optional: local decision model d1 at D1_URL to refine correction / more / neutral.
  • Output: orch_ux.json in the data dir (or --out): generated, window_days, classifier, overall, calibration, nudges, sessions (20 newest), turns (last 40), workers (worker -> orchestrator reports: size, partial, over budget, missing hash/tests, follow-up calls; nudge ids workers_*). Snippets of user text and reply (80 chars) are written. The pipeline copies readout(r) to readout.json section orch_ux.
  • CLI: python3 04-auto-analysis/orch-ux/orch_ux.py [--days N] [--root DIR] [--config PATH] [--out DIR] [--d1] [--no-d1] [--eval [PATH] | --holdout | --test2] (--eval: baseline vs heuristic vs d1 vs combined accuracy on tests/data/classify_eval.jsonl; --test2 is the untouched test set; --d1 lets d1 flip neutral -> more in the scan)
  • Pipeline stage orch_ux (local, optional) in 03-analyze/pipeline.py, after context. Tests: tests/test_orch_ux.py.
  • Live use: the UserPromptSubmit hook ../../06-optional/hooks/orch-nudge.py reuses parse / heuristic on the current session.

Reconfigure

Constants at the top of orch_ux.py: keyword lists VISIBLE_THEME, LENGTH_THEME, CORRECTION(+_RX), MORE(+_RX), SHORT_Q_WORDS; d1 (opt-in --d1) D1_URL, D1_TIMEOUT, D1_MORE_CONF, D1_MAX_CALLS; calibration TARGET_PRIOR_WORDS, PRIOR_N, TOLERANCE, MIN_REPLY_WORDS; nudge thresholds LONG_REPLY_SHARE, VISIBLE_REPEAT_MIN, LENGTH_COMPLAINTS_MIN, LONG_CHAIN_TOOLS, LONG_CHAIN_MIN, ASK_BACK_SHARE, ASK_BACK_MIN, MORE_SHARE; workers PARTIAL_RX, COMMIT_RX, TESTS_RX, BUDGET_RX, FOLLOWUP_MANY, *_RATE_MAX, FOLLOWUP_P50_MAX, WORKER_MIN.

Trade-offs, decisions for the human

  • Keyword heuristics are ES+EN and substring based: a new request that happens to contain "por qué" counts as a correction. d1 (when up) decides only messages without an explicit visible/length theme.
  • Reply words count only the text after the last tool use, so progress text between tools is not counted.
  • Decisions for the human: the prior target (TARGET_PRIOR_WORDS) and whether to install the hook.