Agent Workflow Integration

Configure your AI coding agent to automatically run human QA tests after completing coding tasks. No prompting, no manual steps — when your agent finishes a feature, it creates a Runhuman test, waits for results, and reports back.

How it works: You add instructions to your agent’s configuration file (CLAUDE.md, .cursorrules, etc.) that tell it to run runhuman create after completing user-facing changes. The agent uses the Runhuman skill to know how the CLI works, and your configuration tells it when to use it.

The principle: It’s binary. Either QA testing is off (you ask manually when you want it), or it’s on and fully automatic. No “would you like me to run a test?” interruptions.

---

Prerequisites

Before configuring workflow integration, you need:

1. The Runhuman skill installed in your agent:

npx skills add volter-ai/runhuman-skills -y

2. A Runhuman project configured in your repo:

runhuman login        # Authenticate via GitHub
runhuman init         # Set up project + staging URL

3. A staging or preview deployment accessible to testers. Runhuman tests are performed by real humans — they need a URL they can open in a browser.

After runhuman init, your .runhumanrc will look like:

{
  "organizationId": "org_abc123",
  "projectId": "proj_def456",
  "defaultUrl": "https://staging.myapp.com"
}

---

Claude Code: CLAUDE.md

The simplest approach. Add this to your project’s CLAUDE.md:

## QA Testing

After completing any user-facing feature, bug fix, or UI change,
automatically run a human QA test:

1. Summarize what changed and what a tester should verify
2. Run: `runhuman create <staging-url> -d "<test description>" --sync`
3. Use the staging URL from `.runhumanrc` (or run `runhuman config list`)
4. Wait for results and report them inline
5. If the test finds issues, fix them immediately

Skip QA for: refactors, test changes, documentation, CI configs,
dependency updates, or any non-user-facing change.

What this does: After your agent implements a feature, it automatically creates a test with a description based on the changes, waits for a human tester to complete it, and reports the results — all without you lifting a finger.

Scoped variant

If you only want QA on specific areas of your app:

## QA Testing

After completing changes to any file in `src/pages/checkout/`
or `src/components/payment/`, automatically run a human QA test:

1. Run: `runhuman create https://staging.myapp.com/checkout -d "<description>" --sync`
2. Focus the test description on the checkout and payment flow
3. Report results inline

With templates

If you have a Runhuman template for consistent test structure:

## QA Testing

After completing user-facing changes, run a QA test using the
"Find Bugs" template:

1. Run: `runhuman create <staging-url> --template "Find Bugs" --sync`
2. Report results inline

---

Claude Code: Custom Slash Command

For on-demand testing instead of automatic. Create this file:

.claude/commands/qa-test.md

Run a human QA test on the current project's staging deployment.

1. Read `.runhumanrc` for the staging URL (the `defaultUrl` field)
2. If no URL is configured, run `runhuman config list` to check
3. Summarize recent changes from the conversation context
4. Create a test:
   runhuman create <url> -d "<test description based on changes>" --sync
5. Report results with pass/fail status and any issues found
6. If issues are found, fix them

If the user provided a specific description with this command,
use that as the test description instead of summarizing changes.

Now you can run /qa-test in Claude Code whenever you want a human QA test. You can also pass a description: /qa-test check the mobile layout of the settings page.

---

Claude Code: Hooks

For automatic triggering after git commits or pushes. Add to your .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "pattern": "git push",
        "command": "echo 'HOOK: Run runhuman create with --sync after pushing to verify your changes with a human tester'"
      }
    ]
  }
}

This nudges the agent to run a QA test after every git push. The hook output appears in the agent’s context, prompting it to act.

Limitation: Hooks fire on specific tool uses (like Bash commands), not on abstract events like “task completed.” The best trigger points are git commit or git push since those typically mark task boundaries.

Combine with CLAUDE.md: For the most reliable setup, use both — CLAUDE.md instructions for the “what to do” and hooks for the “when to do it” trigger.

---

Cursor

Add this to your .cursorrules file:

## QA Testing with Runhuman

After completing any user-facing feature, bug fix, or UI change,
automatically run a human QA test:

1. Use `npx runhuman create <staging-url> -d "<test description>" --sync`
2. The staging URL is in `.runhumanrc` (the `defaultUrl` field)
3. Base the test description on what was just implemented
4. Wait for results and report them inline
5. If the test finds issues, fix them

Skip QA for refactors, test changes, docs, CI configs, and
dependency updates.

The same principle applies — the agent reads .runhumanrc for the URL and uses the Runhuman CLI (installed via the skill) to create and monitor tests.

---

Other Agents

Any AI coding agent that supports the Runhuman skill can be configured with similar instructions. The pattern is always the same:

1. Install the Runhuman skill (gives the agent CLI knowledge)
2. Add instructions to the agent’s config file telling it when to run tests
3. The agent uses runhuman create ... --sync and reports results

See the Agent Skills page for installation instructions across different platforms.

---

Customization

Dynamic preview URLs

If your staging URL changes per PR (e.g., Vercel or Netlify preview deployments):

## QA Testing

After completing user-facing changes and pushing to a PR:

1. Get the preview URL from the PR's deployment status or from the
   pattern: https://pr-<number>.preview.myapp.com
2. Run: `runhuman create <preview-url> -d "<description>" --sync`
3. Report results inline

Cost awareness

Each test costs based on tester time (~$0.0085/second). A typical 5-minute test costs ~$0.27-0.45. You can control costs by:

• Scoping narrowly: Only test specific pages or flows, not the entire app
• Using shorter durations: Add --duration 5 for quick smoke tests
• Skipping non-UI changes: The “skip for refactors, tests, docs” instruction is important
• Using templates: Consistent templates avoid wasted tester time on unclear instructions

Output schemas

Get structured pass/fail results by adding a schema:

## QA Testing

After completing user-facing changes, run a QA test with structured output:

1. Create a schema file based on what changed (e.g., checkoutWorks, formSubmits)
2. Run: `runhuman create <url> -d "<description>" --schema-inline '<json>' --sync --json`
3. Parse the structured results and report pass/fail for each check

---

Full Workflow Example

Here’s what a typical session looks like with agent workflow integration enabled:

You: “Add a password reset flow to the login page”

Agent:

1. Reads the codebase, plans the implementation
2. Implements the password reset form, email trigger, and reset confirmation page
3. Writes tests, commits the code
4. Automatically runs: runhuman create https://staging.myapp.com/login -d "Test the new password reset flow: 1. Go to login page 2. Click 'Forgot password' 3. Enter an email address 4. Verify the reset email is mentioned 5. Check for any UI issues or confusing steps" --sync
5. Waits 5-10 minutes for the human tester
6. Reports back:

QA Test Results (passed)

• Forgot password link is visible and clickable
• Email input accepts valid addresses
• Confirmation message appears after submission
• No console errors
• One note: the “Back to login” link on the confirmation page is hard to see on mobile

You: “Fix that mobile visibility issue”

Agent:

1. Fixes the contrast/sizing of the “Back to login” link
2. Commits the fix
3. Automatically runs another QA test focused on the fix
4. Reports: all checks pass, mobile link now visible

The entire QA cycle happens without you managing test creation, waiting, or result checking.

---

Next Steps

Topic	Link
CI/CD recipes and workflows	Cookbook
Reusable test configurations	Templates
Automated CI/CD testing	GitHub Actions
CLI command reference	CLI Tool