Guide · Agent skill
How to use the tmux Real User Testing agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The tmux Real User Testing skill lets an agent run Qwen Code in a real terminal session, press keys the way a person would, and save a readable, timestamped record of every screen along the way. It is written for maintainers and developers who need to review how a dialog or slash command behaved on screen, not just whether it passed. This guide explains what the skill does, how to install it, how to ask for it in plain language, and what to check before running it.
tmux Real User TestingQwenLM/qwen-code · Apache-2.0 Download the skill Quick start
- 1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or the project's .claude/skills/, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Check requirements. Confirm tmux, bash, Node.js and npm are available, and that the project directory contains a Qwen Code checkout.
- 3Ask for a scenario in plain language. Describe the flow to test, such as the /auth or /model dialog, and ask for a readable tmux log and report.
- 4Review the readable log. Open tmux-readable-full.log in the timestamped tmp/ folder and read each labelled section in order.
- 5Check report.md and side effects. Read the PASS or FAIL result and the listed side effects, then confirm the evidence in the log supports it.
What an agent skill is and what this one does
An agent skill is a folder containing a SKILL.md file and optional supporting files. When you ask for something that matches the skill's description, the agent loads its instructions and follows them. This skill's description covers requests such as saving tmux logs, testing like a real user, and testing slash command interaction.
Once installed, the agent runs Qwen Code inside a tmux terminal session. It types slash commands, moves through dialogs with arrow keys, and confirms choices. After each meaningful step it takes a text snapshot of the screen with tmux capture-pane -p and appends it to a log.
- Output is saved in a timestamped folder under the project's tmp/ directory.
- The main deliverable is tmux-readable-full.log, a step-by-step transcript a maintainer can read later.
- A tmux-final-capture.log holds the final screen, and report.md gives a short PASS or FAIL summary with pointers to the artifacts.
- The skill favours rendered screen text over raw ANSI pipe output, which the source notes often looks garbled when opened as plain text.
How to install the tmux Real User Testing skill
Download the skill ZIP from this page and unzip it. You can install it in one of three places depending on how you work.
For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.
The commands in the skill's own examples refer to .qwen/skills/tmux-real-user-testing/scripts/tmux-real-user-log.sh. If you installed the skill into .claude/skills/ or ~/.claude/skills/, adjust those paths to match where the folder actually sits.
- Personal install: ~/.claude/skills/
- Project install: the project's .claude/skills/
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
How to trigger the skill with natural requests
You do not need to type a command to use the skill. The description lists phrases that should activate it, and you can phrase requests in English or Chinese. Name the scenario and say what you want to see afterward.
The skill is meant for requests that ask for a readable record or a real user style run, not just a result. Be specific about the flow, such as /auth, /model, or MCP setup.
- Test the /auth flow like a real user and save a readable log.
- Run a tmux-based real user E2E test of the /model dialog and give me a report I can review.
- Save the tmux logs for the slash command interaction and generate a TUI test report.
- 用 tmux 做真实测试，测试 slash command 交互，并保存 tmux 日志。
Run a scenario with the helper script
The skill includes scripts/tmux-real-user-log.sh, which starts a session, appends labeled snapshots, sends keys, waits for text, and finishes the run. The start command prints export statements, so you wrap it in eval to set SESSION, OUTDIR and LOG in your shell.
Before running a new scenario, the source recommends showing the script's full usage. Each snapshot is appended as a labelled section, and the source's /auth example shows the sequence: start, type and submit, snapshot, send keys, wait for a result, snapshot, then finish.
- Show usage first with the help command.
- Send typed text and Enter separately to avoid swallowed submissions.
- Use wait-for with expected text such as Successfully configured or Error instead of fixed sleeps.
- Use finish to capture the final screen and clean up the session.
eval "$(bash .qwen/skills/tmux-real-user-testing/scripts/tmux-real-user-log.sh \
start <scenario> . npm run dev -- --approval-mode yolo)"
bash .qwen/skills/tmux-real-user-testing/scripts/tmux-real-user-log.sh helpWhat you need before running it
The skill assumes a working development setup. The example starts the app with npm run dev, so the project needs Node.js and npm, and you need tmux and bash. The project directory must contain a Qwen Code checkout.
If the flow you are testing needs login details, such as /auth, you must supply the credentials yourself. The skill does not provide them.
- tmux installed
- bash
- Node.js and npm
- A Qwen Code checkout in the project directory
- Any credentials the tested flow needs, supplied by you
Safety notes before you run it
This skill runs scripts and uses the network. The flows it drives may open a browser window, trigger logins, or change configuration that persists between runs. The source notes that settings updates, opened browser windows and API calls should be recorded in the report as side effects.
Avoid running it against a real account or production credentials unless you are deliberate about it. Design scenarios so side effects are visible in the log, and do not overwrite earlier runs, since each run gets its own timestamped folder.
- Use test accounts rather than production credentials.
- Expect possible browser windows and persistent config changes.
- Keep the complete logs; only sanitise or trim them if you explicitly ask.
- Use the headless JSON E2E approach for pure tool or model API checks.
What people use it for
- Reproducing a terminal UI bug and recording the screen after each intermediate step.
- Checking that /auth, /model, or /manage-models dialogs navigate correctly with arrow keys, Space and Enter.
- Regression testing a multi-step MCP setup where the final state alone does not show what went wrong.
- Producing a readable transcript a maintainer can review without running the session again.
Frequently asked questions
Is the tmux Real User Testing skill free to use?
The source lists the licence as Apache-2.0, which is stated on the item's page. Check the repository's licence file for the full terms before reusing it.
What do I need installed to use this skill?
You need tmux, bash, Node.js and npm, a Qwen Code checkout in your project directory, and any credentials the flow you test requires. The example starts the app with npm run dev.
Where do I put the skill folder?
Unzip the downloaded ZIP into ~/.claude/skills/ for a personal install or into a project's .claude/skills/ folder. In the Claude apps you can upload the ZIP under Settings → Capabilities → Skills.
Why does the skill use capture-pane instead of pipe-pane logs?
The source explains that pipe-pane captures raw ANSI and control streams from the React Ink interface, which look garbled as plain text. capture-pane -p saves rendered screen text after each step, so the log is readable.
How is this different from a headless JSON test?
This skill is for checking the interactive terminal experience and keeping a narrative record of each screen. The source recommends the headless JSON E2E approach when you only need structured checks of tool execution or model API output.
Why does my test hang or show an error?
The source says to poll for expected text rather than sleep blindly. On timeout, the log records the screen as it was when the wait expired, so check that section first. Also confirm the required credentials and the Qwen Code checkout are in place.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits Qwen Code maintainers and developers who need a readable, screen-by-screen record of how a dialog or slash command behaved. It is a poor fit for simple pass/fail checks of tool execution or model output, where the headless JSON approach is more direct. Use it with test accounts, because its flows can trigger logins, browser windows and configuration changes that persist between runs.
Download the skill