​

Operating modes

Qodex can run the same saved scenarios on demand, on a schedule, or from an external event. Coding agents can start runs over MCP, and Autopilot agents keep working between your chats.

​

The shared model

A scenario is the unit of work. You usually create scenarios through chat, then run them against any environment whenever you need them. The agent, scheduler, webhook runner, MCP server, Autopilot agents, and PR review flow all use the same scenario store, scripts, and findings pipeline. You author a scenario once, then reuse it wherever it needs to run.

​

On-demand

Use on-demand mode when you want to ask Qodex for something directly. You talk to the agent in chat. The coordinator breaks down the brief, starts sub-agents, and streams tool calls and results back in real time over a WebSocket. This mode is best for authoring, exploratory runs, triage, and one-off “test this PR” requests. The agent updates project memory as it works, so the next session can reuse what was discovered.

​

Scheduled

Use scheduled mode when you want coverage to run without a person asking for it. Saved scenarios run on daily, weekly, or custom cron schedules. Open Test runs, then Schedules, to create or edit one. Each schedule chooses a target environment, a tag filter, and an optional priority filter. Only active scenarios run on a schedule; drafts are skipped. A scheduled run uses the deterministic replay path. API scenarios make HTTP calls. UI scenarios replay through the intent runner’s step cache, falling back to the LLM resolver only on a cache miss. Scheduled runs publish a test_run record with per-scenario pass, fail, and error breakdowns. Any real bugs become findings in the project.

​

Event-driven

Use event-driven mode when another system should decide when Qodex runs. External systems trigger runs through per-project API keys (qk_*). A POST /webhooks/trigger call from CI, a deploy hook, or a custom GitHub Action can run one scenario, a tag, or the full active suite. Each project can mint multiple keys. Keys are SHA-256 hashed, revocable, and use-counted. The same key gates the GitHub App’s per-PR review and any CI integration you write. For the GitHub App, push and pull_request webhooks drive the PR review flow: walkthrough comment, inline findings, preview-deploy checks, and a Check Run that can gate merges.

​

From a coding agent

Use MCP when a coding agent such as Claude Code or Cursor should drive Qodex. The agent connects to the Qodex MCP server, signs in through the browser or with a personal key for CI, then runs saved scenarios and suites, reads runs and findings, triages findings, and searches endpoints and app behavior. See MCP.

​

Autopilot

Use Autopilot when Qodex should keep working without anyone starting a chat. Autopilot agents run on a schedule, when a bug is opened or reproduced, or when you press Run now. They write and replay tests, reproduce bugs, and draft tests for new production errors. Everything they do or need lands as a task card on the Autopilot board, where you approve proposals and answer questions. See Autopilot.

​

Which mode to choose

• On-demand: authoring new scenarios, debugging failures, running ad-hoc explorations.
• Scheduled: nightly regression, weekly security audit, continuous coverage as the app evolves.
• Event-driven: CI gates, deploy verification, PR review.
• Coding agent: running and triaging Qodex tests from inside Claude Code, Cursor, or another MCP client.
• Autopilot: standing jobs that keep the suite in sync with the product between sessions.

​

Related