Skip to Content
Latch Docs

Configuration

Define checks, filter by changed files, and choose how failures are reported.

Use latch.json to run commands in any language and customize automatic checks. The file is optional when package script discovery finds the checks you want.

To changeSet
Which commands run and whenhooks.after_edit or hooks.turn_end. Checks run on changes by default. Examples
Which changes countpaths or extensions on an individual hook object. Hook fields
What checks reporton_success defaults to "silent", and on_failure defaults to "collect". Set these in defaults or override them per hook. Ordering and overrides
How much output to showfailure_output chooses an excerpt, compact diagnostics, the last few lines, or RTK. Output modes
Whether the agent responds automaticallyTop-level turn_end_feedback defaults to "report". Opt in to "continue_once" on supported harnesses. Turn-end feedback

Create a config

Create latch.json in the directory where checks should run, or generate a starter there with the standalone CLI.

latch config init

The starter keeps package script discovery enabled. If latch.json already exists, the command leaves it in place.

Editor completion and validation

The starter points to the hosted schema. For offline editor completion, copy latch.schema.json from the Latch repository, standalone archive, or npm wrapper into your project next to latch.json. Add "$schema": "./latch.schema.json" as a top-level property. Editors that support JSON Schema can then suggest fields and flag invalid values. Latch validates configuration and compiles path globs at runtime.

Examples

Try the runnable path and extension filter example to see which checks run for different edits.

latch.json
{
  "hooks": {
    "turn_end": {
      "commands": [["cargo", "fmt", "--all", "--", "--check"]]
    }
  }
}

Run a Rust formatting check at turn end when the worktree changes.

File structure

Prop

Type

Hook fields

Prop

Type

An object runs once if any changed file passes its filters. When both filters are set, the same file must match at least one pattern and one suffix. Renames can match either path. Empty filter lists are invalid.

Command syntax

UseExample value for commands
One command as text (v0.1.5+)"bun run lint"
Several commands in order[["make", "lint"], ["make", "test"]]

Latch splits strings with POSIX shell-style quotes and escapes. For example, "node check.js 'file with spaces.ts'" passes the filename as one argument. Latch launches the executable directly, so pipes, redirects, environment variable references, and globs are literal arguments. To use shell features, invoke a shell explicitly, for example [["sh", "-c", "make lint && make test"]]. Use nested arrays to preserve exact arguments, including for a single command such as [["make", "lint"]]. Flat arrays are invalid. commands: [] adds no explicit commands and leaves discovery enabled.

Ordering and overrides

A hook object inherits each setting it omits. Matching hook objects run in the order they appear. Discovered commands run together after explicit objects and inherit the global defaults.

Set an event to [] to disable it, including discovery. Set hooks to {} to disable both events.

Use latch explain after_edit or latch explain turn_end to see which commands and settings Latch resolved.

Failure output modes

ModeWhat the report shows
"excerpt" (default)A bounded preview of stdout and stderr.
"compact"Selected diagnostics such as assertion messages and failure names.
"tail"The last tail_lines lines of each stream.
"rtk"Output from a locally installed RTK filter, with compact output as a fallback.

When a report shortens output, it includes a path to the saved log if Latch could save it. Open the log directly, search it from chat, or use the CLI to replay the original streams. Direct latch run calls print the original streams.

Compact failure output

latch.json
{
  "defaults": { "failure_output": "compact" }
}

Compact mode keeps streams up to 1,200 bytes as-is. For each longer stream, it selects diagnostics such as failure names and assertions, drops repeats, and keeps a few lines from the end. Command failures and exit statuses still appear in order. The renderer runs locally without a model call.

Tail failure output

latch.json
{
  "defaults": { "failure_output": "tail", "tail_lines": 12 }
}

Tail mode shows up to the last 12 lines each from stdout and stderr in this example. Latch shortens unusually long lines from the left. When the preview omits output, the report includes the saved log path. Override the mode or line count on an individual hook.

RTK failure output

Install RTK separately and make sure rtk is on your harness's PATH. For a Vitest project:

latch.json
{
  "hooks": {
    "turn_end": {
      "failure_output": "rtk",
      "rtk_filter": "vitest",
      "commands": [["npm", "test"]]
    }
  }
}

Latch runs the check once and passes its captured output to rtk pipe --filter vitest. The report uses the check's original exit status and includes a path to the original stdout and stderr. Latch adds a compact stderr preview when it detects a diagnostic the filter omitted. If RTK is missing, rejects the filter, returns an empty preview, or takes more than two seconds, Latch shows the built-in compact preview instead. The standalone CLI and plugin bundle use the same external lookup.

On this page