Skip to content

code-yeongyu/oh-my-openagent / .agents/skills/opencode-qa

opencode-qa

Verified

QA 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.

FileKindSize
SKILL.mdskill md11.3 KB
references/cli-commands.mdmarkdown3.8 KB
references/db-investigation.mdmarkdown5.8 KB
references/docker-qa.mdmarkdown3.2 KB
references/events-hooks.mdmarkdown4.5 KB
references/sdk.mdmarkdown4.1 KB
references/server-api.mdmarkdown6.5 KB
references/testing-harness.mdmarkdown6.2 KB
references/tui-tmux.mdmarkdown4.0 KB
scripts/db-session-by-id.shexecutablescript1.7 KB
scripts/db-session-by-name.shexecutablescript1.9 KB
scripts/db-session-by-text.shexecutablescript6.6 KB
scripts/export-roundtrip.shexecutablescript2.8 KB
scripts/lib/common.shexecutablescript9.5 KB
scripts/lib/fake-openai-branches.mjsscript1.2 KB
scripts/lib/fake-openai-events.mjsscript2.3 KB
scripts/lib/fake-openai-server.mjsexecutablescript3.7 KB
scripts/lsp-e2e.shexecutablescript134.1 KB
scripts/serve-wake-split-probe.shexecutablescript38.2 KB
scripts/server-smoke.shexecutablescript2.1 KB
scripts/sse-hook-probe.shexecutablescript4.4 KB
scripts/tui-smoke.shexecutablescript3.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.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall