QAwalk

All guides › By agent

By agent

QA with Codex: the skill in skills/qawalk and a pointer in AGENTS.md

How Codex runs QAwalk: where the skill lives, how AGENTS.md points to it, the prompts that work, and how Codex reads reviewer feedback before it continues.

Codex reads AGENTS.md and follows it. qawalk init --agent codex puts the skill into skills/qawalk and adds one paragraph to AGENTS.md, so acceptance walkthroughs become part of how the agent works in the repository.

The problem

Codex is fast at code and silent about screens. It will happily merge a form that overflows on phones, because nothing asked it to look.

What changes with QAwalk

AGENTS.md says: for acceptance plans, scenario runs and the canvas use skills/qawalk/SKILL.md. The skill defines done, what is allowed without asking and what is not, and links the references for writing the plan, executing steps, reading evaluations and handling environments.

How it works

  1. Install

    npm install --save-dev github:sinfin/qawalk#v0.1.0, npx qawalk init --agent codex --org <your-org>, npx qawalk doctor. The skill lands in skills/qawalk, AGENTS.md gets the pointer, qawalk.config.yml is created.

  2. Ask

    the same prompts as for any agent; Codex runs the CLI commands from the skill in its sandbox with network access to your local app and to the QAwalk service.

  3. Steps Codex cannot script

    mark them agent in the scenario; Codex follows the instructions, then qawalk capture --step <id> records what it reached.

  4. Feedback

    qawalk feedback and qawalk inbox in the terminal, or the MCP server as an HTTP tool source, before the next iteration.

Skills and prompts

Follow skills/qawalk/SKILL.md: walk the acceptance plan of TASK-123 on local, evaluate, build and share it, then post the canvas link into the PR.
Turn this task description into ACCEPTANCE.md and qa/scenario.yml; one criterion per check, semantic questions only for judgement.

Expected outcome: the files in the task folder, a validated scenario (qawalk validate), a shared run and one PR comment.

What you get

FAQ

Sandbox and network?

The CLI talks to your local app, to the shared Chrome over CDP and to app.qawalk.com over HTTPS. Allow those in the Codex sandbox; nothing else is needed.

Can Codex and Claude Code share a repository?

Yes: qawalk init --agent all installs both locations; runs are pinned per agent with --run <id>.

What it looks like

A real run of QAwalk on its own public pages, refreshed daily. This is the canvas your team gets.

6 of 6 steps passed · 2026-09-24Open the run in QAwalk ↗

More guides

QA with Claude Code: install the skill, ask in plain words, read the canvasQAwalk in CI: headless runs, read-only tokens, one comment per scenario

Install in three steps

QAwalk runs where your code and your agent are. The service stores and versions the results, shows the canvas and collects approvals.

  1. Add the CLI to the project
    npm install --save-dev github:sinfin/qawalk#v0.1.0

    Pre-launch: the repository is private. Ask Sinfin for access.

  2. Create the config and install the skill
    npx qawalk init --agent claude --org <your-org>
npx qawalk doctor

    The skill is copied to .claude/skills/qawalk.

  3. Create your organization and a token

    Create an organization; you become its admin. The start page offers a tester token in one click, later under Settings → API tokens. Put it into the project .env:

    QAWALK_TOKEN=qwk_…
TYPESAFE_API_KEY=…   # optional: semantic evaluator
  4. Run and share
    npx qawalk start --scenario docs/tasks/TASK-123/qa/scenario.yml --env local
npx qawalk walk        # playwright steps; agent/manual steps: qawalk capture
npx qawalk evaluate
npx qawalk share --pr

    Or ask your agent: “Walk the acceptance plan of TASK-123 with QAwalk on local and share the result.”