code-yeongyu/oh-my-openagent / .agents/skills/opencode-qa
opencode-qa
VerifiedQA opencode itself, per case: verify the CLI/terminal (opencode run, db, serve, export), prove a specific plugin hook/action/event fired via the SSE event stream, smoke-test the TUI under tmux, and investigate sessions in opencode's SQLite DB by id, title/name, or message text. Ships tested helper scripts (each with a --self-test) plus per-domain references. Use whenever someone wants to QA, smoke-test, verify, or debug opencode's CLI, HTTP server, plugin hooks/events, or TUI, or to find/inspect opencode sessions in the database. Triggers: opencode qa, qa opencode, test opencode, verify opencode hook, opencode session db, find opencode session by id/name/text, opencode tui test, opencode server health, opencode event stream.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.3 KB |
| references/cli-commands.md | markdown | 3.8 KB |
| references/db-investigation.md | markdown | 5.8 KB |
| references/docker-qa.md | markdown | 3.2 KB |
| references/events-hooks.md | markdown | 4.5 KB |
| references/sdk.md | markdown | 4.1 KB |
| references/server-api.md | markdown | 6.5 KB |
| references/testing-harness.md | markdown | 6.2 KB |
| references/tui-tmux.md | markdown | 4.0 KB |
| scripts/db-session-by-id.shexecutable | script | 1.7 KB |
| scripts/db-session-by-name.shexecutable | script | 1.9 KB |
| scripts/db-session-by-text.shexecutable | script | 6.6 KB |
| scripts/export-roundtrip.shexecutable | script | 2.8 KB |
| scripts/lib/common.shexecutable | script | 9.5 KB |
| scripts/lib/fake-openai-branches.mjs | script | 1.2 KB |
| scripts/lib/fake-openai-events.mjs | script | 2.3 KB |
| scripts/lib/fake-openai-server.mjsexecutable | script | 3.7 KB |
| scripts/lsp-e2e.shexecutable | script | 134.1 KB |
| scripts/serve-wake-split-probe.shexecutable | script | 38.2 KB |
| scripts/server-smoke.shexecutable | script | 2.1 KB |
| scripts/sse-hook-probe.shexecutable | script | 4.4 KB |
| scripts/tui-smoke.shexecutable | script | 3.6 KB |
references/tui-tmux.md
View on GitHub# QAing the opencode TUI under tmux (Case C)
## Verdict first (be honest)
- tmux CAN launch the opencode TUI and `capture-pane` reads the rendered frame; `send-keys` delivers keystrokes to the composer. This is proven and good for SMOKE checks: did it boot, does it render, does it accept input.
- The TUI is a 60fps full-screen app (built on @opentui/solid) with a custom renderer, animations, and a worker thread. Asserting on conversation OUTPUT by scraping the frame is FRAGILE and not recommended.
- For real behavior assertions prefer: `opencode run` (Case A, references/cli-commands.md), the server API + SSE (Case B, references/server-api.md + events-hooks.md), or the TUI control HTTP API (below). The TUI talks to the same server, so API-level QA is equivalent to driving the screen.
## Safety: isolate so QA never pollutes the real DB
Launching the real TUI would create sessions in the real ~/.local/share/opencode DB. Run it under an isolated XDG sandbox. The bundled `scripts/tui-smoke.sh` does exactly this and verifies the real session count is unchanged before/after.
## Smoke test (bundled)
- `scripts/tui-smoke.sh --self-test` launches the TUI under tmux in an isolated sandbox, polls capture-pane for a render marker (version string / "Ask anything" / footer), sends a sentinel keystroke, then kills the tmux session and confirms the real DB is untouched.
## Browser-rendered TUI visual evidence
For PR evidence or any TUI visual QA claim, render the live TUI through the real
xterm.js web terminal - NEVER the `tmux capture-pane` frame, which degrades
color and CJK width:
```bash
node script/qa/web-terminal-visual-qa.mjs --title "OpenCode TUI QA" \
--command "opencode" --input "{Enter}" \
--evidence-dir .omo/evidence/<slug>/opencode-web-terminal
```
The helper runs a real pty, renders it in xterm.js under Chrome, captures
`terminal.png` (true color), writes `terminal.txt` + `metadata.json`, and
records the cleanup receipt (`--from-file <capture.ansi>` replays a saved raw
stream). This is the required TUI visual evidence pattern when the review needs
to see the screen, while `scripts/tui-smoke.sh` remains the isolation/smoke
authority.
## Manual tmux recipe (fenced) - for ad hoc smoke
```
SESS=oqa_tui_demo
DIR=$(mktemp -d)
tmux new-session -d -s "$SESS" -x 200 -y 50
# isolate XDG so no real session is written
tmux send-keys -t "$SESS" "XDG_DATA_HOME=$DIR/data XDG_CONFIG_HOME=$DIR/cfg XDG_STATE_HOME=$DIR/state XDG_CACHE_HOME=$DIR/cache OPENCODE_DISABLE_AUTOUPDATE=1 OPENCODE_DISABLE_MODELS_FETCH=1 opencode $DIR" Enter
sleep 7
tmux capture-pane -t "$SESS" -p | sed -n '1,30p' # inspect the rendered frame
tmux send-keys -t "$SESS" "hello" # type into the composer
sleep 1
tmux capture-pane -t "$SESS" -p | sed -n '1,30p'
tmux kill-session -t "$SESS" # teardown (kills the TUI)
rm -rf "$DIR"
```
Explain: capture-pane -p prints the visible frame; send-keys injects input; kill-session tears down the process tree. Always teardown and remove the temp dir.
## The reliable alternative: TUI control HTTP API
A running TUI is a client of the local server, so you can drive it over HTTP without scraping the screen:
- POST /tui/append-prompt - append text to the composer
- POST /tui/submit-prompt - submit the composer
- POST /tui/execute-command - run a TUI command
- POST /tui/show-toast - show a toast
- GET /tui/control/next + POST /tui/control/response - the control channel
Use these (with auth + ?directory=) to deterministically drive a TUI you launched, then assert via the event stream (references/events-hooks.md).
## Headless component testing (for source-level TUI tests)
opencode unit-tests TUI components headlessly with @opentui/core/testing `createTestRenderer` (see packages/opencode/test/cli/tui/, e.g. app-lifecycle.test.ts). This is the route for asserting TUI component behavior in the source repo; see references/testing-harness.md.
Bottom line: tmux for smoke, server/SSE or /tui/* control for assertions, createTestRenderer for source unit tests.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |