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 change | Set |
|---|---|
| Which commands run and when | hooks.after_edit or hooks.turn_end. Checks run on changes by default. Examples |
| Which changes count | paths or extensions on an individual hook object. Hook fields |
| What checks report | on_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 show | failure_output chooses an excerpt, compact diagnostics, the last few lines, or RTK. Output modes |
| Whether the agent responds automatically | Top-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 initThe 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.
{
"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
| Use | Example 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
| Mode | What 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
{
"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
{
"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:
{
"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.