test-tui-claude-feature-via-cmux

Test TUI-only Claude Code features via cmux, not --print

When to use this skill

Use this skill any time a verification question is about a Claude Code feature that is implemented in the TUI (slash commands, dialogs, pickers, status bar indicators, settings menus). The most common failure mode is treating claude --print "/feature" as a test — it isn't, and the resulting "isn't available in this environment" error leads to wasted time reading minified binary strings chasing phantom gates.

Trigger phrases (load this skill when you see any of these):

• "Does /advisor work?"
• "Does the /config menu show X?"
• "Is the /model picker working?"
• "Verify the slash command"
• "Test the Claude Code TUI feature"
• Any verification question where the answer is a slash command, dialog, picker, or status indicator

Do NOT use this skill for:

• Plain completion questions (--print "what model are you?" works)
• Tool use / file reading / API contract tests (--print is fine)
• Anything that doesn't involve a TUI slash command, dialog, or picker

The core rule

claude --print is non-interactive mode. Slash commands render inside the Ink TUI as menus, dialogs, or pickers — they have no --print representation. The binary's response to any TUI slash command in --print mode is always:

/<feature> isn't available in this environment.

That error specifically means "I cannot show you this in non-interactive mode," not "this feature is broken." Treating it as a feature-gate failure is the mistake this skill exists to prevent.

The correct test path

# 1. Spawn a fresh Claude Code workspace in cmux
export CMUX_SOCKET_PATH=/private/tmp/cmux-debug-may-18.sock
WS_OUT=$(cmux new-workspace --cwd "$PWD" --command "claude")
WS=$(echo "$WS_OUT" | grep -oE 'workspace:[0-9]+' | head -1)

# 2. Find the auto-created surface
sleep 2
SURF=$(cmux list-pane-surfaces --workspace "$WS" 2>/dev/null \
       | grep -oE 'surface:[0-9]+' | head -1)

# 3. Wait for Claude to be ready (look for the `❯` prompt in screen text)
cmux read-screen --workspace "$WS" --surface "$SURF" --scrollback --lines 30

# 4. Send the slash command + press Enter
cmux send --workspace "$WS" --surface "$SURF" "/advisor"
cmux send-key --workspace "$WS" --surface "$SURF" enter

# 5. Read the result (dialog, picker, error message, etc.)
sleep 2
cmux read-screen --workspace "$WS" --surface "$SURF" --scrollback --lines 50

# 6. Clean up — Esc out + close workspace
cmux send-key --workspace "$WS" --surface "$SURF" escape
cmux close-workspace --workspace "$WS"

For multi-step TUI flows (multi-screen dialogs, follow-up pickers), repeat steps 4-5 with appropriate send-key calls between (arrow keys, enter, etc.). See the cmux skill (~/.hermes_prod/skills/cmux/SKILL.md) for the full key set.

Bundled helper: scripts/test-tui-feature.sh

A wrapper script that takes the slash command as an argument and runs the full spawn-send-read-cleanup cycle:

~/.claude/skills/test-tui-claude-feature-via-cmux/scripts/test-tui-feature.sh /advisor
~/.claude/skills/test-tui-claude-feature-via-cmux/scripts/test-tui-feature.sh /config
~/.claude/skills/test-tui-claude-feature-via-cmux/scripts/test-tui-feature.sh /model

The script:

1. Spawns a cmux workspace running claude
2. Waits for the ❯ prompt (polls read-screen with a 30s timeout)
3. Sends the slash command + Enter
4. Reads the resulting screen text
5. Cleans up the workspace
6. Exits 0 on success, 1 on timeout/error

What this skill prevents

• 30+ minute rabbit holes reading minified JS bundles (isFirstPartyApiBackend, xr(), VW(), oct(), isFirstPartyAnthropicBaseUrl)
• Phantom-gate theorizing: "maybe the proxy is making it not first-party?"
• Adding redundant env vars to settings.json (e.g. _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL=1) that don't change behavior
• Burning context on debug output that doesn't apply to the actual test environment
• Forgetting that the user is observing the test (cmux makes it shareable)

When --print IS valid evidence

--print is fine for:

• Simple completion tasks: claude --print "what model are you?"
• API contract tests: tool use, file reading, error handling, schema validation
• Streaming behavior, response time, error recovery
• Anything that doesn't require a TUI slash command, dialog, picker, or status bar

Rule of thumb: if the question is "does this feature work in the TUI" or "does this slash command do X" → use cmux. If the question is "can the model do X" or "does the API return Y" → --print is fine.

Common false alarms

Symptom	Likely real cause	Test that proves it
--print "/advisor" returns "isn't available"	Normal non-interactive behavior	Open in cmux, see picker
--print "/advisor" returns 401 / auth error	OAuth or keychain issue	claude --print "what model are you?" — if that works, auth is fine
claude in TUI never reaches ❯ prompt	Workspace trust, settings issue	cmux read-screen shows what's actually on screen
Slash command opens but shows wrong content	Real bug — model/state issue	Reproduce in cmux, check the actual dialog

Verified example (2026-06-23)

Test target: advisorModel: "claude-opus-4-8" in ~/.claude/settings.json — was the advisor actually using Opus 4.8?

• claude --print "/advisor" (with and without various ANTHROPIC_BASE_URL settings) → always returned "isn't available in this environment"
• cmux send "/advisor" + enter in workspace:30 surface:65 → opened the picker dialog showing 1. Fable 5 / ❯ 2. Opus 4.8 ✔ / 3. Sonnet 4.6 / 4. No advisor
• The ✔ on Opus 4.8 = current selection = the advisorModel setting was being read correctly. Feature was working the whole time.

The user had to push back twice ("are you opening claude code itself and typing /advisor?", "use cmux stop being lazy") before the correct test was performed.

References

• cmux skill: ~/.hermes_prod/skills/cmux/SKILL.md
• Source memory file: ~/.claude/projects/-Users-jleechan--hermes-prod/memory/bestpractice_2026-06-23_test-tui-features-via-cmux.md
• Wiki source page: ~/llm_wiki/wiki/sources/bestpractice-2026-06-23-test-tui-features-via-cmux.md
• Wiki concept: ~/llm_wiki/wiki/concepts/TUISlashCommandTesting.md
• Bead: jleechan-37uv (closed)
• Roadmap: ~/roadmap/learnings-2026-06.md entry dated 2026-06-23
• Claude Code binary version: 2.1.185 (verified)