code-yeongyu/oh-my-openagent / .agents/skills/codex-qa
codex-qa
VerifiedQA the omo Codex Light edition (lazycodex / packages/omo-codex) itself, in strict isolation so ONLY our plugin is exercised, never the user's real ~/.codex. The first-party method drives the real `codex app-server` against an isolated CODEX_HOME plus a LOCAL mock model (no real API call), and proves a plugin hook fired by asserting hook/started + hook/completed notifications. Also: isolated install verification, per-component hook probes, a tmux TUI smoke, and runtime log observation (RUST_LOG / logs SQLite / /debug-config). Ships tested helper scripts each with a --self-test. Use whenever someone changes anything under packages/omo-codex or wants to QA, smoke-test, verify, or debug the Codex plugin, its hooks/components, the installer/config.toml, the app-server flow, or the Codex TUI. Triggers: codex qa, qa codex, codex-qa, test codex plugin, verify codex hook, codex app-server, lazycodex qa, isolated CODEX_HOME, prove codex hook fired, codex tui test.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.6 KB |
| references/app-server.md | markdown | 3.0 KB |
| references/components-hooks.md | markdown | 2.7 KB |
| references/docker-qa.md | markdown | 2.6 KB |
| references/install-verify.md | markdown | 2.6 KB |
| references/isolation.md | markdown | 2.5 KB |
| references/logging-debug.md | markdown | 2.6 KB |
| scripts/app-server-drive.shexecutable | script | 3.1 KB |
| scripts/hook-unit-probe.shexecutable | script | 3.0 KB |
| scripts/install-verify.shexecutable | script | 2.5 KB |
| scripts/lib/app-server-client.mjs | script | 6.3 KB |
| scripts/lib/app-server-client.test.js | script | 1.9 KB |
| scripts/lib/common.shexecutable | script | 7.1 KB |
| scripts/lib/mock-model.mjs | script | 2.1 KB |
| scripts/lsp-e2e.shexecutable | script | 150.9 KB |
| scripts/tui-smoke.shexecutable | script | 2.9 KB |
references/logging-debug.md
View on GitHub# Observing Codex at runtime (logs + debug surfaces)
The intent "use `/debugging` to watch logs while QAing" maps to the surfaces
below. Codex has **no `/debugging` command**; these are the real ways to observe
a run.
## 1. The notification stream (best signal for plugin QA)
When you drive via the app-server, the stdout stream IS the live trace:
`hook/started` / `hook/completed`, `item/*`, `mcpServer/*`, `error`, `warning`.
This is structured and assertion-grade — prefer it over scraping text logs.
`scripts/app-server-drive.sh` captures it; the JSON summary it prints is the
evidence.
## 2. app-server stderr (`RUST_LOG`)
The app-server writes tracing logs to **stderr** (not a file), filtered by
`RUST_LOG` (`app-server/src/lib.rs:638-651`). Turn it up and capture:
```bash
RUST_LOG=info # or debug
LOG_FORMAT=json # optional: machine-parseable lines
```
The driver inherits the env; raise `RUST_LOG` before invoking it to see the
plugin/hook subprocess accounting on stderr (surfaced in the summary's
`stderrTail`).
## 3. The logs SQLite DB
The app-server also writes structured logs to a SQLite DB under `$CODEX_HOME`
(alongside `state_5.sqlite`). Query it post-run for a durable record:
```bash
ls "$CODEX_HOME"/*.sqlite
```
## 4. TUI `/debug-config`
Inside the TUI, the slash command is **`/debug-config`** (NOT `/debugging`) —
"show config layers and requirement sources" (`tui/src/slash_command.rs:107`).
Useful to confirm which config layer enabled the plugin. Drive it under tmux:
```bash
tmux send-keys -t <sess> "/debug-config" Enter
tmux capture-pane -t <sess> -p -S -
```
For TUI visual QA evidence, render the live TUI through the real xterm.js web
terminal instead of scraping the tmux pane (`tmux capture-pane` degrades color
and CJK width):
```bash
node script/qa/web-terminal-visual-qa.mjs --title "Codex TUI /debug-config" \
--command "codex" --input "/debug-config" --input "{Enter}" \
--evidence-dir .omo/evidence/<slug>/codex-debug-config-web-terminal
```
Attach the resulting `terminal.png` and keep `metadata.json` with the cleanup
receipt. The tmux pane above proves the config text; this PNG proves the visual
TUI surface in true color.
## 5. `codex debug` subcommands
`codex debug models` (raw model catalog), `codex debug prompt-input` (the
model-visible prompt list), and `codex debug app-server …` (a built-in
app-server driver). Run them against the isolated `CODEX_HOME` for ad-hoc
inspection.
## Component-level logs
`rules` emits phase/timing lines to stderr under `NODE_DEBUG=codex-rules`. Most
components prove themselves through their stdout `additionalContext` or a disk
artifact — see [components-hooks.md](./components-hooks.md).
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: 321k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 321k | 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 |