Visp Code docs.

How the loop works

Visp Code runs an actor–critic loop around your coding agent’s work.

The agent (the actor) builds one usable slice at a time inside an authorized file scope. Visp Code executes the checks that slice declares, and an independent reviewer (the critic) judges the result against the original request. Its findings come back to the agent as the next repair step.

It works as a CLI (visp) and as an MCP server (visp serve --mcp); both use the same workflow services. In practice the agent runs the commands itself: the installed instructions and hooks tell it how, and send it back when it stops early.

What counts as evidence

Only what Visp Code executed itself: check commands, browser journeys and their screenshots, and the reviewer’s attributed judgments. The agent’s own claims are never evidence.

User guide

From install to a checked change, in four steps.

1. Install and set up

Visp Code needs Node.js 22.16 or newer and a Git repository. It is in beta; the npm package is visp-coder.

npm install -g visp-coder@beta

The package installs three executables: visp, visp-migrate for backed-up upgrades of saved history, and visp-runner, an optional experiment runner. Then set up the project for your coding host: claude-code, codex, cursor, copilot, opencode or generic.

visp init --harness codex
visp install --harness codex --dry-run   # preview what will be written
visp install --harness codex
visp doctor

init writes visp.yml and .visp/. install writes the host’s instruction files and VISP.commands.md, registers the MCP server, and installs hooks. visp doctor checks the installation.

2. Quick start

visp feature "Add a retry button to the failed-save banner"
visp work --check "npm test"   # one slice for the whole request, checked by your tests
# ...implement...
visp done                      # run checks; independent review
visp next                      # findings or the next step
visp accept                    # check the assembled product
visp pr                        # reviewer document for the pull request

This is the light path: the whole request becomes one slice with scope ** and your test command as its check. Use a full brief when the request has several independently usable parts.

3. Write a brief for larger work

A brief lives at .visp/features/<id>/brief.yaml. It holds outcomes, behavior examples, decisions, checks and slices. The agent authors only the brief; everything else under .visp/ is generated. A slice needs an outcome, a bounded write scope and at least one runnable check for its functional outcomes.

outcomes:
  - id: O001
    kind: functional
    statement: Starting the game switches it to the playing state.
    priority: must
checks:
  - id: C001
    command: [node, --test, test/game.test.mjs]
    outcomes: [O001]
    files: [src/game.js, test/game.test.mjs]
    verifierFiles: [test/game.test.mjs]
    environment: node
  - id: C002
    command:
      kind: browser-journey
      journey:
        url: http://localhost:3000/
        viewport: { width: 390, height: 844 }
        actions:
          - { kind: click, selector: '#start', capture: true }
          - kind: wait-for
            selector: '#game'
            attribute: { name: data-state, value: playing }
            timeoutMs: 5000
            capture: true
    outcomes: [O001]
    files: [index.html, src/game.js]
    environment: browser
slices:
  - id: T001
    goal: Start a game from the title screen.
    outcomes: [O001]
    scope:
      allowed: [index.html, src/game.js, test/game.test.mjs]
    checks: [C001, C002]

Update a brief with visp brief --patch - --reason "<why>", which merges entries by id, or replace it with --from -. Common natural field names (description, then, slice IDs like S1) are rewritten and reported; anything ambiguous is refused with its field path.

4. Scope and host hooks

scope.allowed is the set of paths the agent may change while a slice is authorized. Changing scope takes a brief update and a new visp work.

A Stop hook also sends the agent back to an unfinished, recently active feature, at most three times.

Full reference: workflow guide, browser journeys and product review, and internals.

Independent review

The critic is a separate model session that judges the work, not the agent’s account of it.

Independent acceptance tests

With codex-exec (and, from the next beta, claude-exec), visp feature also starts a tester that writes one standard-library test file from the original request alone. Visp Code keeps it only if it has at least three assertions and fails on the unimplemented project, then pins it under acceptance/<feature>/. From then on the agent can’t quietly change it: changing it is an intent change that visp pr lists.

The tester runs on new projects only by default (fewer than three tracked source files). On existing codebases, tests written from reading the code assumed behavior the code doesn’t have, and agents then broke correct code to satisfy them. critic.existingCodeTests: true is an experimental, opt-in mode that runs the tester against a disposable copy of the repository.

Budgets

With webSearch: true the reviewer may search the web for public documentation. Every query is logged to the feature and listed by visp pr.

Full reference: critic guide.

Configuration

visp init writes a commented visp.yml at the project root.

Every key is optional, unknown keys are rejected with their path, and the file is never rewritten for you. The keys you are most likely to change:

harness: claude-code        # claude-code, opencode, codex, copilot, cursor, generic
profile: minimal            # minimal or standard

critic:
  harness: codex
  launch: codex-exec        # or host (default)
  maxCalls: 3

workflow:
  strictness: standard      # relaxed, standard, strict, locked
  maxChangedFiles: 40
  blockedPaths: [".env", ".env.*", node_modules, dist, build, .git]
  validationCommands:       # one command per entry, no shell
    - pnpm test

context:
  tokenBudget: 12000

visp doctor --settings shows every effective value and whether it came from the file or a default. Rerun visp install after changing harness or profile.

What to commit

Most of .visp/ is meant to be committed. A reviewer or CI needs to see what a change declared and what was checked.

Full reference: configuration and migrating from 0.4.

Commands

Grouped by when you reach for them.

CLI output is compact; --json prints the full result. MCP tools reply with compact text plus the complete result in structuredContent; pass detail: true for full text.

In the next beta

On the main branch now, not yet on npm. npm install -g visp-coder@beta installs 0.5.0-beta.2 until the next release.

A Claude reviewer

critic.launch: claude-exec with critic.harness: claude-code runs the independent reviewer and tester as restricted claude -p sessions, whichever host does the coding.

Flip check

workflow.flipCheck: auto reruns each passing check on the pre-change code in a temporary copy. A check that passes either way is shown as a coverage gap; it never gates acceptance. Use off for checks with external side effects.

Dispute a wrong test

visp done --dispute "<test name>" --reason "<request quote and why>" asks the independent reviewer to rule on a pinned test. It is the worker’s only route against one.

Existing tests protected

Workers are pointed at up to eight existing tests that cover what they changed, and reviewers must report a weakened, skipped or deleted test unless the request changes that behavior.

Large repositories

Reviews of large existing codebases anchor on the files changed since authorization and get a bounded diff first. visp init adopts a whole-project check only if it passes now.

Static pages and rules

Browser journeys can open project:/index.html with no server running. visp rules keeps the rules you state for all later work.

Details: changelog, Unreleased and the critic guide.

Results & limits

On Visp Code’s own benchmark, it matched or beat every other arm on every task, most clearly on the larger ones.

Four tasks with hidden checks, Claude Haiku 4.5 as the coding agent, three runs per arm. The other arms were bare coding, Spec Kit and BMAD.

With a strong worker (October)

With Codex gpt-6-luna at maximum effort as the worker, every arm scored at or near the maximum on the four new-project tasks, so they no longer separate the arms; Visp Code took about 22 minutes per task and Spec Kit about twice that. On existing repositories, SWE-bench Verified Mini (50 Django and Sphinx issues, two runs per arm) with a Claude Sonnet 5.5 reviewer through claude-exec:

None of these differences is significant (sign tests, p 0.12 to 0.58). Strong workers gain little on these tasks; the clearer gains are with a weaker worker, above.

Every number and its limits: research summary. The harness, tasks and hidden checks are in bench/.

When something is stuck

work says the slice has no runnable check

Declare the command that exercises the slice (your test runner or a browser journey). The reply includes a patch that adds one. For a small change, use visp work --check "<test command>".

A check failed with environment-failed

Nothing about the product was tested. Install the missing executable or browser, or rerun the same command with your host’s sandbox escalation, then pass --retry-environment.

No review happened after done

The reply says why. For codex-exec, check that critic.harness is codex and the Codex CLI is signed in. From a sandboxed shell without network, rerun visp done with sandbox escalation.

An edit or commit was refused for scope

The error names the out-of-scope files. Update the brief and run visp work again rather than widening scope by hand. A denial that blames the installation is fixed with visp doctor.

STATE_BUSY, or a mismatch after upgrading

Another Visp Code writer is active; visp doctor reports lock owners and --fix recovers abandoned transactions. After upgrading, rerun visp install and restart MCP servers and host sessions. Projects with 0.4 history need visp-migrate.

Source, issues and changelog: github.com/djkeshawa/visp-coder. Checked against release 0.5.0-beta.2 and the main branch on October 11, 2026; features marked “Next beta” are on main but not yet on npm. Use visp --help for your installed version.