Let AI agents run your Apex tests

Why this needs to be fast, not just possible

An agent's write-test-fix loop is the same loop you run, executed more often and with less patience for waiting. Every second in the test step is multiplied by however many iterations the agent needs.

At org speed, that multiplication is fatal: the agent either waits and burns your afternoon, or stops running tests and starts guessing. Neither is what you wanted when you turned it on. With tests executing locally in tens of milliseconds, running them after every edit is simply free — and an agent that can afford to check its work stops producing code that only looks right.

The second reason is interface quality. An agent shelling out to a test command reads a wall of formatted terminal output and infers what happened. Over MCP it gets structured JSON: counts, failures, file and line, coverage. Less to misread, and much less context burned on formatting.

Step 1 — Install Nimbus

# macOS / Linux
curl -sSL https://testnimbus.dev/install.sh | bash

# Windows (PowerShell)
iwr -useb https://testnimbus.dev/install.ps1 | iex

Confirm the tests run before you wire anything up. If nimbus test "*" works in your project, the agent path will work too — it is the same runtime. See running Apex tests locally if this is your first run.

Step 2 — Register the MCP server

nimbus mcp speaks Model Context Protocol over stdio. It initialises the runner once at startup — database, project sources — and then services requests until the agent disconnects, so calls after the first reuse a warm database and a parsed project rather than paying setup cost every time.

Claude Code

claude mcp add nimbus -- nimbus mcp

Any MCP client, via config file

Clients that read a project-level config — including Claude Code's .mcp.json and Cursor's .cursor/mcp.json — take the standard mcpServers shape. Check your client's own documentation for the file location; the entry itself is the same:

{
  "mcpServers": {
    "nimbus": {
      "command": "nimbus",
      "args": ["mcp"]
    }
  }
}

If nimbus is not on the agent's PATH — a common surprise with GUI-launched editors — use the absolute path from which nimbus as the command.

Server flags

# Start it directly — stdio JSON-RPC
nimbus mcp

# Worker count for run_apex_tests (0 = NumCPU)
nimbus mcp --parallel 4

# Coverage is collected by default so get_coverage answers
# after every run. Opt out if you do not want the cost.
nimbus mcp --coverage=false

Step 3 — Check what the agent can see

Ask the agent to list its tools. Eleven should appear:

• run_apex_tests — run tests by pattern, structured results back.
• get_coverage — per-class line coverage from the last run.
• list_test_classes — every @isTest class in the project.
• get_governor_usage — governor consumption (CPU, heap, and the rest) from the last run.
• execute_anonymous — anonymous Apex against the local runtime.
• query — SOQL against the local database.
• describe_schema — objects and fields as the project defines them.
• run_mutation_tests — mutation testing, to find assertions that never assert.
• explain_failure — the analysis nimbus explain prints, for one failure.
• triage_failures — a wall of failures grouped into root-cause clusters.
• query_graph — the dependency graph, same nimbus.graph/v1 payload the CLI emits.

explain_failure and triage_failures return exactly what nimbus explain and nimbus triage print — the same code path, not a parallel implementation. An agent and the human reviewing its work never get divergent accounts of the same failure. What that analysis does and does not claim is written up on the failure intelligence page.

Payloads are bounded on purpose. Arguments like max_failures, max_tests_per_cluster and survivors_only cap what comes back, so a five-hundred-failure run cannot blow the context window. The true counts are always reported alongside the truncated lists — less listed, nothing hidden.

Step 4 — Give the agent instructions, not just tools

Tools tell an agent what it can do. Skills tell it how the work is normally done — which is the difference between an agent that runs a test and one that raises coverage sensibly. nimbus skills fetches curated skills and writes them wherever your agent expects to find them.

# What is available, and what is already installed here
nimbus skills list

# Install one, or all of them
nimbus skills install <name>
nimbus skills install all

# Where did they go?
nimbus skills path

The target agent is detected from the project root — .claude/, .cursor/, .aider.conf.yml, AGENTS.md, .kiro/, opencode.json — and can be forced with --agent:

# Force the target: claude-code, cursor, aider, agents-md, kiro
nimbus skills install all --agent cursor

# Claude Code only: install for every project, not just this one
nimbus skills install all --global

# Overwrite a local copy that has diverged
nimbus skills install <name> --force

Keeping the human in the loop

The failure mode of agentic work is not bad code, it is unreviewed code. Two things help:

• Watch mode alongside the agent. Run nimbus test:watch in a terminal while the agent works. You see each result as it lands, in the same shape the agent sees it, without asking for a status update.
• The same gate in CI. An agent's pull request should meet the checks a human's does — the same test run and the same coverage floor. See Apex CI without a connected org.