Verification

Verification is your own build or test command, run by hlix in the task’s checkout after the coder’s turn. Its result decides whether the task passed. Without it, “done” would only mean “the branch moved”: a coder that broke the build would look the same as one that fixed it.

Every coder is held to it. The command is yours, hlix runs it, and the result is recorded either way — including when there is no command to run.

Prerequisites

• A project in your Workspace.
• manage access on the project to set the command. Client collaborators cannot change it.
• A command that exits 0 on success and non-zero on failure. hlix reads only the exit code.

Where the command comes from

The more specific setting wins.

#	Setting	Set with	Use it for
1	The repository’s own command	PATCH /v1/api/projects/{id}/repos/{repoId} · field verifyCommand	Repositories that need different checks
2	The project default	PATCH /v1/api/projects/{id} · field verifyCommand	One command that suits every repository

A blank value counts as unset at both levels. If neither names a command, the task records a skip.

You rarely have to type the command. When none is set, hlix reads your package.json the first time the project starts — the test script, otherwise typecheck, check or lint, run with the package manager your lockfile names — and saves it on the repository, where you can change it. The preview’s command and port are detected the same way, from the dev or start script.

Set the project default

curl -sS -X PATCH "$HLIX_BASE_URL/v1/api/projects/$PROJECT_ID" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID" \
  -H 'content-type: application/json' \
  -d '{"verifyCommand":"npm test"}'

Expected result: 200 and the updated project, with "verifyCommand": "npm test". Send {"verifyCommand": null} to clear it.

Override it for one repository

curl -sS -X PATCH "$HLIX_BASE_URL/v1/api/projects/$PROJECT_ID/repos/$REPO_ID" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID" \
  -H 'content-type: application/json' \
  -d '{"verifyCommand":"pytest -q"}'

Expected result: 200 and the updated repository. The command is limited to 4,000 characters at both levels.

Both fields are also editable in the dashboard under Project → Settings: the project default on the verification panel, and the per-repository override on each repository’s row. See Repositories.

What runs, in order

1. Setup. If the repository has a setup command, it runs in the task’s checkout before the coder starts. If it fails, the task fails there; the coder never works on half-installed dependencies.
2. The coder’s turn. The task’s coder edits the checkout.
3. Verification. Your command runs in that checkout, with the same environment the setup command had.
4. One repair turn, only on a failure. The coder receives the task brief again, plus the command, its exit code and the end of its output.
5. Re-verification. The command runs again. That result is final.

There is exactly one repair turn: enough for a coder to fix what it broke, without an unbounded loop against your budget.

The three results

Result	What it means	What happens to the task
Passed	The command exited 0, on the first run or after the repair turn	The task branch is pushed and goes to review
Failed	Still non-zero after the repair turn	The work is still pushed and goes to review with the failure on record. Review re-runs the command on the combined work; a rejection sends the task back to its coder, which continues from the pushed branch
Skipped	No command is set	Recorded in the task’s log as a skip. Never reported as a pass

A skip is not a pass

A repository with no verification command is not a repository whose tests pass; it is a repository nothing checked. hlix records the skip as visibly as a pass so the two can never be confused.

Finished work is never thrown away. Failing work is still pushed, so you can read what the coder did and the next round continues from it. Nothing is delivered until your verification passes in review.

Reading the result

Every task’s log carries one result line, worded the same whichever coder ran:

[hlix verification] PASSED — `npm test`
[hlix verification] PASSED after 1 repair turn — `npm test`
[hlix verification] FAILED after 1 repair turn (exit 1) — `npm test`
[hlix verification] SKIPPED — no verify command is configured …, so nothing checked this work.

A failed result is followed by the end of the final run’s output, so the evidence sits next to the failure.

Limits

Limit	Value	Why
One verification run	10 minutes	A hung test suite becomes a failed result instead of using up the task’s time
Output returned	Last 120 lines, capped at 8,000 characters	The failure summary is at the end of a long log
The whole task	30 minutes by default	Setup, the coder’s turn, verification, the repair turn and re-verification share one time limit

Truncated output says what was dropped, so a shortened log is never mistaken for a complete one. Every captured line is redacted before it reaches the coder or the log, so a test that prints a credential does not expose it.

A run stopped at the 10-minute limit counts as failed: the work goes to review with the evidence recorded, as for any other failing command.

Every coder verifies the same way

The hlix coder and every external coder follow the same rules and print the same lines. hlix commits what the coder left, then verifies that commit; a repair turn’s changes are committed the same way. The repair is a follow-up in the same coder session.

An unfinished turn is not a skip

If the coder’s turn was cancelled or stopped at the task’s time limit, verification does not run: there is nothing meaningful to check in a half-edited tree. This is not recorded as a skip, because a skip means the project has no command. The partial work is still committed.

If verification does not do what you expect

• [hlix verification] SKIPPED … on a project you configured. A per-repository verifyCommand takes precedence over the project default, and an empty string on a repository counts as unset rather than inherited — set it to null to use the project default.
• hlix verification `npm test` exited 1. in the task’s log, or verification failed after 1 repair turn: `npm test` exited 1 in the task worktree. The work is pushed for review, which re-runs the check. The work went to review with the failure recorded; review re-runs the command and sends the task back if it still fails. If the same failure repeats, read the output in the task’s log and fix the cause or the command.
• [hlix verification] FAILED … (exit 124). The command was stopped at the 10-minute limit; the output ends with [hlix] killed after 600s — the verification command did not finish. Use a narrower command, such as a smoke suite.
• The task failed before the coder ran, naming a setup command. The repository’s setup command failed. Fix it and run the task again; each run starts in a fresh sandbox.
• {"error":"No fields to update"} with 400. The PATCH body was empty. Send the field you want to change.
• {"error":"Repository not found"} with 404. The repository id does not belong to this project.
• A 403 on either PATCH. Both changes need manage access on the project.
• The command passes locally and fails in the task. It runs in the task’s sandbox with the environment your setup command produced, not on your machine. Make sure the setup command installs what the check needs, and that any value it reads is a project secret.

Where to go next

If you want to…	Read
Set the command in the dashboard	Repositories
See how verification fits with review	Review & QA gates
Understand the sandbox it runs in	The Coding Workspace
Read the review evidence a task produces	Reviewing output

Next steps

Review & QA gatesVerification is the first check a change passes before it lands.

RepositoriesWhere the setup and verification commands live, per repository and per project.

The hlix coderHow the default coder runs a task.

External codersClaude Code, Codex, Cursor Agent and the other coders under the same check.