Skip to content

UX/DX review 2026-11-17: command surface, status, toggles, animations (tracking, v0.2.2) #863

Open

Description

@n0rpan

Owner-requested UX / UI / DX review of oxa (O-375 round, 2026-11-17), done read-only against main by a reviewer model; nothing was built or run, so every claim must be verified against current main before implementing. Owner decision O-382 (supersedes O-381 for item 1): item 1 is a small v0.2.1 fix with no after-0.2.1 label; items 2–10 go in v0.2.2 with after-0.2.1. Each item gets its own issue (linked below as they are filed); good candidate work for the DeepSeek-on-Go helper lanes.

Verified task checklist (O-382)

Verified against main 69a81515ad3ce39dbf048112fd0cfad476f4b73f by source/docs inspection; each child records files, implementation contract, behavioral acceptance and boundaries. Runtime validation is not claimed for the static review. Corrections: stall-timeout/output-schema already have prose docs; CLEAR already includes tool count. #861 is a separate UX-owned terminal-loss bug, not an eleventh review item.


oxa UX / DX review (2026-11-17)

Read-only review of main, open issues and PRs. Nothing was built or run; claims come from source and docs.

1. Command surface

What exists

Group Items
Subcommands install, remove (uninstall), update, list (packages); login chatgpt --experimental [--paste] [--replace], logout chatgpt; config [-l]; mcp add|remove|list|login|logout; identity [--refresh] [--offline]; report-issue draft|submit; wipe --session|--all [--yes] [--engine]; send <id> "text"; status <id|file>; work <taskfile> | --issue N --model M [--rerun], work status [--json]; share key add|list|revoke (build feature)
Model/output flags --provider, --model, --models, --api-key, --list-models, --thinking, --mode text|json|rpc, -p, --output-schema, --max-time, --max-tokens, --stall-timeout, --export, --tui-mode, --verbose
Session flags --continue/-c [id], --resume/-r, --session, --session-id, --fork, --session-dir, --no-session, --name/-n
Tool flags --tools/-t, --exclude-tools/-xt, --no-builtin-tools/-nbt, --no-tools/-nt, --no-mcp, --no-web-search
Permission flags --permission-mode, --standard, --auto, --yolo, --approve/-a, --no-approve/-na, --offline
Resource flags --extension/-e, --skill, --prompt-template, --theme, --use-theme, --system-prompt, --append-system-prompt, and --no-extensions/-ne, --no-skills/-ns, --no-prompt-templates/-np, --no-themes, --no-context-files/-nc
Slash commands /settings /model /scoped-models /thinking /mode /auto /yolo /theme /compact /new /resume /tree /fork /clone /name /session /usage /export /copy /hotkeys /help /mcp /trust /engine /reload /debug /bug /quit /exit, plus /web-search (hook), /skill:name, templates, extension commands

Verdict

Problems, most confusing first:

  1. "mode" means five things: --mode (output format), --permission-mode, --tui-mode, /mode (permissions) and the oxa.mode setting (table mode), next to permissions.defaultMode.
  2. A message that is no longer true, and a name collision. /login answers "oxa has no provider login", yet oxa login chatgpt exists (usage.md repeats it). "share" means two things: /share is pi's session upload (omitted), oxa share key manages guest keys.
  3. Docs and help drift. cli.md has no oxa work and no oxa share; status and send are in prose but not in the Commands table; --stall-timeout and --output-schema are missing from the option tables. --help omits update --extensions and identity --offline. usage.md omits /help and /usage. tools.md does not mention bash background jobs.
  4. Persistence differs per command. /theme x saves, /mode x needs --save, /model and /thinking need Ctrl+S, and no save path was found for /yolo.
  5. Three ways to set one permission mode: /mode auto, /auto, /yolo [on|off]. Only /yolo takes on/off.
  6. Names that mislead. --approve means "trust the project", not "approve tool calls". --theme loads a file while --use-theme selects one. oxa list lists packages, --list-models lists models. -v is version while --verbose has no short form. /session and /usage are the same. /engine load is /model under another name.
  7. Flag style. Multi-letter single-dash shorts (-nt, -nbt, -xt, -na) read as clustered flags. Package verbs are top level, MCP verbs nested.
  8. --experimental is a required flag on one subcommand, not a system.
  9. Discoverability gaps. No per-subcommand --help found (usage only on error) and no shell completion command.

2. Agents and subagents

Feature State Turn on/off See it Stop it
subagent tool main model heuristic, oxa.subagent.enabled, defaultTools, --tools / --exclude-tools; no slash tool block only Esc on parent kills the child
Bash background jobs (background: true, job, kill) main, undocumented always on nothing for the user; only the model can read a job only the model can kill
Steering and follow-up (Enter, Alt+Enter, oxa send) main; late admission in PR #830 always on Steering: / Follow-up: lines Alt+Up, Esc
oxa status, --stall-timeout main flag per-session JSON snapshot n/a
oxa work main (#333) command oxa work status [--json] no stop command found
Goal mode and wait open PR #747, print mode only (-p --goal FILE); /goal is a follow-up (#709) flag planned in /goal planned pause|resume|clear
oxa lead, /status /asks /hold /decide open PRs #764, #776, #759; docs/lead.md says pending — — —
Agent-to-agent messaging oxa-a2a crate on main, no user surface found; #813, #258 are issues only — — —
Share feature-gated oxa share key build feature share key list share key revoke
ChatGPT login main, --experimental command no status command found logout chatgpt
Local engine /engine status, /engine load <model> oxa.engine.inProcessLocal (user file) /engine no unload found; wipe --engine clears session state only

Where it confuses:

Proposal: one vocabulary for everything that runs, status | pause | resume | stop, and one /status view (also oxa status with no argument) that lists the turn, children, jobs, the queue, the goal, the engine and the budget. Later features (#709, #629, #813) add rows to that view, not new commands.

3. Settings on/off

Today a feature can be toggled through four channels with different rules:

  • Settings use three idioms: plain bool, "unset is on" bool, and on/off strings (oxa.sandbox.net, codemode.mode).
  • Flags mostly exist only as --no-x. Tools are switched by a second mechanism (defaultTools, --tools, --exclude-tools) that overlaps oxa.subagent.enabled, oxa.webSearch.enabled and codemode.enabled.
  • Env booleans each accept a different set: OXA_OFFLINE takes 1/true/yes; OXA_WEB_SEARCH takes 0/false/no/off; OXA_REDUCED_MOTION takes anything but empty or 0; OXA_CLEAR_ON_SHRINK takes only 1.
  • Slash commands persist inconsistently (section 1, item 4).

Proposed model, one rule per layer:

  1. The settings file is the truth. Every switch is <area>.<feature>.enabled: bool. Old spellings stay as accepted aliases with a start-up note.
  2. One run: every switch gets --<feature> and --no-<feature>, generated from the schema. For tools these are sugar over the tool list, so each tool has one effective switch and oxa config shows why it is on or off.
  3. Env: OXA_<FEATURE> with one shared parser (1/true/yes/on, 0/false/no/off).
  4. Session: /<feature> [on|off]; no argument shows the state and where it comes from. Session-only unless --save, and every setter prints "this session only, add --save to keep". /theme follows the same rule.
  5. Precedence: defaults < user < project < env < flag < slash. oxa config already prints the source; add oxa config get|set|unset <key> so nobody hand-edits JSON.
  6. Experimental: experimental.<name>: true or --experimental <name>; oxa config lists them in their own group.

Security-widening keys stay user-file only, as now.

4. Animations and personality

What exists (skin/mod.rs, skin/arcade.rs, skin/chrome.rs): four six-cell sprites at 8 fps (Think: bouncing pixel; Write: running ink; Work: walking ox; Fire: YOLO flames). The arcade scenes (stack, stars, charge, pixel graphics) already tell states apart: the ox butts a crate labelled with the tool's icon, one coin per tool call, prefill pushes a block along the track, compaction presses the context into SAVE, and CLEAR / FAILED shows for 1.5 s. Text badges: THINKING WRITING TOOL PREFILL COMPACTING RETRY WAITING QUEUED. The rules are right: one row, no layout change, no sound, readable as plain text under NO_COLOR.

The gaps: in minimal the Work sprite covers tool, prefill, compaction, retry and queue; Activity (oxa-interactive/src/model.rs) has no variant for subagent, wait, model load or goal; the window title carries no state.

State Motion (arcade / minimal) Text that must stand alone Change
Subagent spawned a calf per child trots behind the ox, gold when done (today: a crate with the & icon) AGENTS 2/3 scout new Activity::Subagent { done, total, name }
Background job a small crate parked at the right edge, ticking HUD chip JOBS 2 HUD part from JobRegistry::running
Waiting (goal wait) ox lies down, a z drifts every second SLEEP 4:12 ci run new Activity::Waiting { until, reason } (with #747)
Goal progress flag at the right edge; ox position is budget used HUD GOAL 62% 38m left HUD part (with #709)
Local model loading ox pulls a weight sled along a filling meter LOADING ornith 71% new Activity::ModelLoad { done, total }
Rate limited / retry ox paws the ground behind a gate; gate opens at retry RETRY 2/3 in 8s (429) add a reason to Retrying
Budget near cap coin row drains; steady warning colour at 80 %, error at 95 % HUD $ 8.10/10 HUD meter beside CTX and CACHE
Done CLEAR plus coins and elapsed time; FAILED on error CLEAR 14 tools 2m10s add the two numbers

Accessibility rules to keep and extend:

  • Motion never carries a fact alone: every row above has a text badge and a number, and that is exactly what ui.reducedMotion, NO_COLOR, TERM=dumb and ui.animation: off show.
  • Warnings never flash; a colour change holds steady. Colour is always paired with a word.
  • Screen readers: add the state word to the window title (oxa_title_text shows only the name today) and announce transitions only (start, blocked, done) through ui.notify, never per frame. The pi skin stays a fully static fallback.

5. Top 10, by delight per effort

Paths are under oxa/.

# Change Files Spec When
1 Truthful /login notice oxa-interactive/src/slash.rs, docs/pages/usage.md Replace "no provider login" with "run oxa login chatgpt --experimental in a terminal"; /share says it is session upload, not oxa share key. v0.2.2
2 /jobs: see and stop background work oxa-tools/src/jobs.rs (needs a list call; only running() and read(id) exist), oxa-interactive/src/slash.rs, oxa-core/src/commands.rs, oxa-interactive/src/skin/chrome.rs, docs/pages/tools.md List bash jobs with age and last output line; /jobs stop <id>; HUD chip JOBS n; document the job arguments. Subagent children (oxa-cli/src/child.rs, separate processes) join later. v0.2.2 (jobs), later (children)
3 Docs match help, enforced docs/pages/cli.md, docs/pages/usage.md, oxa-cli/src/args.rs, a parity test Add work, share, status, send, --stall-timeout, --output-schema, /help, /usage; a test fails when a COMMANDS or OPTIONS entry is missing from cli.md. v0.2.2
4 oxa <command> --help oxa-cli/src/dispatch.rs, work_cmd.rs, status.rs, wipe_cmd.rs, mcp_cmd.rs, config_cmd.rs Every subcommand answers --help with usage, one example and exit 0; oxa help <command> is the same. v0.2.2
5 One boolean parser, paired flags oxa-config/src/env.rs, oxa-cli/src/args.rs All OXA_* booleans accept the same eight words; --no-<tool> becomes sugar for --exclude-tools <tool>; add --animation <mode>. v0.2.2
6 Say where a change was saved oxa-interactive/src/slash.rs, selectors/*.rs, oxa-cli/src/config_cmd.rs Every setter ends with "this session" or "saved to user settings"; --save works on /model, /thinking, /theme, /yolo; add oxa config get|set|unset. v0.2.2 (notice), later (config set)
7 Informative sprites oxa-interactive/src/model.rs, skin/mod.rs, skin/arcade.rs, skin/chrome.rs Add Activity::Subagent and a retry reason with their own sprites and badges; CLEAR shows tool count and time. v0.2.2 (these two), later (wait, goal, load)
8 One /status view and one verb set oxa-interactive/src/slash.rs, oxa-cli/src/status.rs, work_cmd.rs /status and bare oxa status show turn, children, jobs, queue, goal, engine, budget; add oxa work stop; goal and lead add rows here. later (with #709, #629)
9 Budget meter in the HUD skin/chrome.rs, oxa-interactive/src/model.rs, oxc-gateway budget rows $ used/cap meter for daily_budget_usd, --max-tokens and goal budgets; steady warning at 80 %. later (needs #627)
10 Name clean-up through aliases oxa-cli/src/args.rs, pkg_cmd.rs, slash.rs --trust for --approve; --output-format for --mode; oxa pkg <verb>; /permissions for /mode; /engine unload; oxa completions <shell>. Old names keep working. later

The v0.2.2 milestone already holds 42 open issues; items 1 to 7 are each a few files with no engine or security surface.

Not verified

Activity

  1. added this to the v0.2.2 milestone on Nov 17, 2026
  2. added
    after-0.2.1Approved work held until v0.2.1 is branched; merges in one batch after
    on Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    after-0.2.1Approved work held until v0.2.1 is branched; merges in one batch after

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions