---
title: "vetd docs"
description: "Install vetd and use its MCP tools, CLI and Node SDK to check coding agent edits."
url: http://localhost:4173/docs
updated: 2026-11-11
---

# vetd docs

> vetd checks an agent's code changes in memory. It returns new TypeScript errors, rule violations, affected routes and affected Vitest tests. This page covers setup, tools, results, CLI, SDK, configuration and limits.

## Requirements

| | |
| --- | --- |
| Node.js | 22.18 or newer |
| TypeScript | `@typescript/native-preview` 7.0.0-dev.20260707 or newer, installed in the project |
| Project | `tsconfig.json` and `package.json` at the root |
| OS | macOS or Linux. Not Windows |
| Tests | Vitest (optional) |

## Setup

The package is not on npm yet. Install it from a local checkout:

```sh
npm install -D /absolute/path/to/vetd @typescript/native-preview
npx vetd init
```

`init` adds vetd to `.mcp.json` and adds instructions to `AGENTS.md`. It keeps your existing content. You can run it again safely.

For other MCP clients, use this command:

```sh
npx --no-install vetd mcp --root /absolute/path/to/project
```

Setup per agent: [MCP setup](http://localhost:4173/mcp.md).

## How an agent uses it

1. Send the change to `check`, as a unified diff or as `[{ "path": "src/x.ts", "content": "..." }]`. `content: null` deletes the file. Nothing is written to disk.
2. Read `ok`, `errors`, `violations` and `fallback`. Use `explain` on any id you don't understand.
3. Send fixes to `check`. Changes add up in the same fork.
4. Call `runTests` with `{ "scope": "affected" }` to run affected tests.
5. To try another approach, call `fork`. Call `discard` on the ones you don't keep.
6. Call `commit` to write the fork to disk. Call `verify` first for a second check.

Each MCP session has its own fork. Agents in the same folder don't see each other's changes. The CLI uses a fork named `default`. Forks unused for 2 hours are deleted.

## MCP tools

| Tool | Input | What it does |
| --- | --- | --- |
| `check` | `patch?`, `forkId?`, `detail?` | Applies a change in memory and checks every file it affects, plus the rules. Without `patch`, rechecks the fork |
| `fork` | `fromForkId?` | Creates a new fork. Returns a `forkId` |
| `discard` | `forkId` | Deletes a fork |
| `commit` | `forkId?` | Writes the fork's changes to disk. Returns the written files |
| `runTests` | `forkId?`, `scope?` | Runs Vitest: `"affected"` (default), `"all"` or a list of test files |
| `impact` | `file` or `symbol` | Lists the files, routes and tests that use a file or symbol (`name` or `path/to/file.ts#name`) |
| `routes` | `forkId?` | Lists App Router routes with params, rendering mode and client components |
| `explain` | `diagnosticId` | Explains an error and how to fix it. Takes a rule id, or `ts<code>@<file:line:col>` for a type error |
| `audit` | `rule?`, `limit?` | Runs the rules on the whole project. Returns a score and the top violations per rule |
| `verify` | `forkId?`, `oracle?` | Rechecks the fork from scratch in a separate `tsgo` and compares. `oracle: true` runs a full `tsgo --noEmit` (slow) |
| `status` | none | Shows memory, forks and recent recheck reasons |

JSON schemas: `src/api.ts`, or the MCP `tools/list` call.

## Check result

| Field | Meaning |
| --- | --- |
| `ok` | `true` if the change adds no type errors and no rule errors |
| `errors` | New type errors, grouped by message. `at` lists each location as `file:line:col` |
| `unverified` | Errors not compared with the files on disk. They may already have existed |
| `violations` | New rule violations. Pass the `id` to `explain` |
| `preexisting` | Number of errors already in the project. They don't fail `ok` |
| `tests` | Test files the change affects |
| `routes` | Routes the change affects |
| `fallback` | Why vetd checked more files than usual, if it did |
| `unsupported` | Project features vetd can't check incrementally |
| `omitted` | Number of items left out of the lists |
| `ms` | Check time in milliseconds |

Pass `detail: "full"` to get every field without limits: `typeErrors`, `ruleViolations`, `recheck`, `timingsMs` and `memory`.

- A failed or unsupported check is never a pass.
- If `fallback` is set, the result is still correct. It just took longer.
- `patch_failed` means the diff doesn't match the file. Read the file again and resend.
- Changes to files outside the project, in `.git/` or in `node_modules/` are rejected.

## CLI

```sh
git diff | npx vetd check --patch -
npx vetd check --patch change.diff
npx vetd impact src/lib/auth.ts
npx vetd impact src/lib/auth.ts#getUser
npx vetd test affected
npx vetd explain next/server-hooks
npx vetd routes
npx vetd verify --oracle
npx vetd status
npx vetd stop
```

Output is JSON. `check` exits with 1 when `ok` is false, and 2 on a startup or command error. Options: `--root DIR`, `--tsconfig FILE`, `--fork ID`, `--timeout SECONDS`.

Errors go to stderr as one line, then the fix and a link to this page. Set `VETD_DEBUG=1` for the stack trace.

## Node SDK

```ts
import { createEngine } from "vetd";

const engine = await createEngine({ root: "/path/to/project" });
const result = await engine.check({
  patch: [{ path: "src/lib/math.ts", content: "export const add = (a: number, b: number) => a + b;\n" }],
});
if (!result.ok) console.error(result.typeErrors, result.ruleViolations);
engine.close();
```

Other exports: `callTool`, `TOOLS`, `serveMcp`, `DaemonClient`, config helpers and the `Plugin` API for custom rules.

## Configuration

Put settings in `vetd.config.json` at the project root, or under a `"vetd"` key in `package.json`. Unknown keys are errors.

```json
{
  "tsconfig": "tsconfig.app.json",
  "plugins": {
    "next": {
      "serverOnlyModules": ["@/lib/db"],
      "clientEnvAllow": ["SENTRY_DSN"]
    }
  }
}
```

| Key | Effect |
| --- | --- |
| `tsconfig` | Which tsconfig to check, relative to the root |
| `plugins.next` | `false` turns off the Next.js rules. They are on by default in projects with `app/` or `pages/` |
| `plugins.next.serverOnlyModules` | Modules that must never be imported in client code |
| `plugins.next.clientEnvAllow` | Env vars client code may read, besides `NEXT_PUBLIC_*` |

Environment variables:

| Variable | Effect | Default |
| --- | --- | --- |
| `VETD_TSGO_IDLE_MS` | Stop `tsgo` after this much idle time | 5 minutes |
| `VETD_IDLE_EXIT_MS` | Exit vetd after this long with no clients | 10 minutes |
| `VETD_FORK_TTL_MS` | Delete unused forks after this long. `0` = never | 2 hours |
| `VETD_CACHE_DIR` | Cache folder | `$XDG_CACHE_HOME/vetd` or `~/.cache/vetd` |
| `VETD_TSGO` | Path to a newer `tsgo` binary | the project's `tsgo` |
| `VETD_BACKEND` | `api` forces the API backend | auto |
| `VETD_TIMEOUT` | CLI: give up after this many seconds without an answer | 0 (wait) |
| `VETD_DEBUG` | CLI: `1` prints stack traces with errors | off |
| `VETD_TEST_TIMEOUT_MS` | Stop a test run after this long | 10 minutes |
| `VETD_ORACLE_TIMEOUT_MS` | Stop a full `verify --oracle` check after this long | 15 minutes |

## Limits

- Keep a full typecheck and build in CI.
- vetd is an early release. The `tsgo` API it uses may change. Pin the `tsgo` version if you need repeatable results.
- The Go backend is experimental and needs Go installed.
- For the Pages Router, only route and link rules apply.
- npm, yarn, pnpm and Bun workspaces are supported.
- vetd may not match a full check on every project yet. If you think a result is wrong, run `verify --oracle` and report it.