Repository navigation
Description
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)
- 1. dogfood: slash login notice contradicts shipped ChatGPT login and share-key commands #862 — truthful
/loginand/shareguidance (v0.2.1, release exception). - 2. dogfood: Add /jobs listing, targeted stop and a running-job HUD count #865 — Add /jobs listing, targeted stop and a running-job HUD count (v0.2.2,
after-0.2.1). - 3. dogfood: Keep CLI and slash-command documentation aligned with shipped help #867 — Keep CLI and slash-command documentation aligned with shipped help (v0.2.2,
after-0.2.1). - 4. dogfood: Provide side-effect-free subcommand help and oxa help <command> #868 — Provide side-effect-free subcommand help and oxa help (v0.2.2,
after-0.2.1). - 5. dogfood: Unify user-facing boolean environment parsing and add consistent tool/animation flags #869 — Unify user-facing boolean environment parsing and add consistent tool/animation flags (v0.2.2,
after-0.2.1). - 6. dogfood: Make setter persistence explicit and consistent across slash commands #870 — Make setter persistence explicit and consistent across slash commands (v0.2.2,
after-0.2.1). - 7. dogfood: Differentiate subagent and retry activity with accessible text and elapsed completion time #871 — Differentiate subagent and retry activity with accessible text and elapsed completion time (v0.2.2,
after-0.2.1). - 8. dogfood: Design one status view for session work and a targeted work-stop operation #872 — Design one status view for session work and a targeted work-stop operation (v0.2.2,
after-0.2.1). - 9. dogfood: Add an evidence-based budget meter to the HUD #873 — Add an evidence-based budget meter to the HUD (v0.2.2,
after-0.2.1). - 10. dogfood: Add clearer command aliases while preserving existing spellings #874 — Add clearer command aliases while preserving existing spellings (v0.2.2,
after-0.2.1).
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:
- "mode" means five things:
--mode(output format),--permission-mode,--tui-mode,/mode(permissions) and theoxa.modesetting (table mode), next topermissions.defaultMode. - A message that is no longer true, and a name collision.
/loginanswers "oxa has no provider login", yetoxa login chatgptexists (usage.mdrepeats it). "share" means two things:/shareis pi's session upload (omitted),oxa share keymanages guest keys. - Docs and help drift.
cli.mdhas nooxa workand nooxa share;statusandsendare in prose but not in the Commands table;--stall-timeoutand--output-schemaare missing from the option tables.--helpomitsupdate --extensionsandidentity --offline.usage.mdomits/helpand/usage.tools.mddoes not mention bash background jobs. - Persistence differs per command.
/theme xsaves,/mode xneeds--save,/modeland/thinkingneed Ctrl+S, and no save path was found for/yolo. - Three ways to set one permission mode:
/mode auto,/auto,/yolo [on|off]. Only/yolotakes on/off. - Names that mislead.
--approvemeans "trust the project", not "approve tool calls".--themeloads a file while--use-themeselects one.oxa listlists packages,--list-modelslists models.-vis version while--verbosehas no short form./sessionand/usageare the same./engine loadis/modelunder another name. - Flag style. Multi-letter single-dash shorts (
-nt,-nbt,-xt,-na) read as clustered flags. Package verbs are top level, MCP verbs nested. --experimentalis a required flag on one subcommand, not a system.- Discoverability gaps. No per-subcommand
--helpfound (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:
- No single answer to "what is running?" A user has
/session,/engine,oxa status,oxa work status, and soon/goaland the lead's/status. Subagent children and background jobs appear in none of them. - The user cannot stop a background job or one child, only the whole turn. Known defects:
--max-timedoes not stop a child (dogfood: P2:--max-timedoes not stop a running sub-agent; a child has no time or turn limit #508);subagentis offered with no agents defined (dogfood: the subagent tool is offered when no agents are available #696, fix in PR fix(oxa): hide subagent tool when no agents are available #803). - Subagent has four switches and an invisible default. "Unset is on unless the model is Flash or the window is below 32K" cannot be read from the UI.
- Verbs differ per feature:
kill,wipe,clear,revoke,remove;workhas none.
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/offstrings (oxa.sandbox.net,codemode.mode). - Flags mostly exist only as
--no-x. Tools are switched by a second mechanism (defaultTools,--tools,--exclude-tools) that overlapsoxa.subagent.enabled,oxa.webSearch.enabledandcodemode.enabled. - Env booleans each accept a different set:
OXA_OFFLINEtakes1/true/yes;OXA_WEB_SEARCHtakes0/false/no/off;OXA_REDUCED_MOTIONtakes anything but empty or0;OXA_CLEAR_ON_SHRINKtakes only1. - Slash commands persist inconsistently (section 1, item 4).
Proposed model, one rule per layer:
- The settings file is the truth. Every switch is
<area>.<feature>.enabled: bool. Old spellings stay as accepted aliases with a start-up note. - 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 andoxa configshows why it is on or off. - Env:
OXA_<FEATURE>with one shared parser (1/true/yes/on,0/false/no/off). - 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"./themefollows the same rule. - Precedence: defaults < user < project < env < flag < slash.
oxa configalready prints the source; addoxa config get|set|unset <key>so nobody hand-edits JSON. - Experimental:
experimental.<name>: trueor--experimental <name>;oxa configlists 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=dumbandui.animation: offshow. - 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_textshows only the name today) and announce transitions only (start, blocked, done) throughui.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
- Subcommand
--helpat run time: only usage-on-error was found in source. - Whether a finished background job wakes the session: no wake event was found in
jobs.rs; Epic: oxa as the orchestrator's daily driver (replace Codex/dsh lanes) #94 and Post-0.2: bridge native Bash jobs into A2A goal lifecycle #258 still ask for it. ARCADE-ANIMATION.mdandOXA-UI-DESIGN.mdwere not found onmain, so animation proposals were checked against the code only.
Activity