> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open4rena.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Watch mode

> Run your project's check whenever files change, and let o4 fix failures.

`o4 watch` watches your project and runs a check command, such as your build or tests, every time files change. When the check fails, it shows the error and offers to have o4 fix it. Run it in a terminal next to your editor while you work.

## Start watching

Run `o4 watch` in the project's root folder:

```bash theme={null}
cd ~/code/api
o4 watch
```

To watch a folder without changing to it, pass it with `-C`: `o4 -C ~/code/api watch`.

o4 prints the folder and the command it will run, then waits for changes:

```text theme={null}
Watching /Users/you/code/api · cargo check --workspace
```

Each time you save, o4 waits until files have stopped changing for half a second, then runs the check once for the whole batch. When the check passes, it prints nothing. Stop watching with `Ctrl+C`.

## When the check fails

o4 shows the command's output and a suggestion that names the first error location it found and the files you changed:

```text theme={null}
Check failed after 2 changed file(s): cargo check --workspace
error[E0308]: mismatched types
 --> src/routes/users.rs:42:17
...
Failure at src/routes/users.rs:42:17 after editing src/routes/users.rs, src/models/user.rs; let o4 inspect it? [enter] fix  [d] dismiss
```

* Press `Enter` to fix it. o4 runs the agent once, in the same way as [print mode](/guides/print-mode), with a prompt containing the check command, its output, the changed files, and their `git diff`. The agent's reply is printed, and watching continues. If the fix run fails, for example because the model request fails, `o4 watch` stops with the error.
* Type `d` and press `Enter` to dismiss it and keep watching. Any other answer also dismisses it.

<Warning>
  `o4 watch` reads your answer from standard input, and an empty answer means fix. Run it in an interactive terminal. If standard input is closed or empty, as in a script, every new failure starts a fix run.
</Warning>

o4 reports each distinct failure only once per `o4 watch` run, whether you fixed or dismissed it. It tells failures apart by the first `file:line` location in the output (standard error first, then standard output). If the check fails again at the same place, or fails again with no location in its output, o4 prints nothing and keeps watching. Restart `o4 watch` to see that failure again.

<Note>
  While o4 waits for your answer, it doesn't run the check. Changes made in the meantime, including the fix, are picked up by the next run.
</Note>

## Choose the check command

o4 picks the command in this order:

1. The `--command` (or `-c`) option.
2. `command` in the `[watch]` section of the project's `.o4/config.toml`, if the workspace is trusted.
3. A default based on the files in the folder:

| If the folder has | o4 runs |
| - | - |
| `Cargo.toml` | `cargo check --workspace` |
| `package.json` | `npm test` |
| `pyproject.toml` or `pytest.ini` | `pytest` |
| `go.mod` | `go test ./...` |
| none of these | `true`, which always passes |

To use a different command once:

```bash theme={null}
o4 watch --command "npm run lint && npm test"
```

To set it for the project, add it to `.o4/config.toml`:

```toml theme={null}
[watch]
command = "make check"
```

o4 only reads the project's `.o4/config.toml` once you've trusted the workspace with `o4 trust`, because the file comes from the repository and could run any command. Until then, `o4 watch` ignores the setting and uses the default. See [Workspace trust](/safety/workspace-trust).

`o4 watch` only reads `[watch]` from the project's `.o4/config.toml`. A `[watch]` section in your global `~/.o4/config.toml` or in `.o4/config.local.toml` isn't used.

## How the check runs

* The command runs with `/bin/sh -c` in the folder where you started `o4 watch`, so you can use pipes and `&&`.
* It always runs in o4's `guarded` sandbox tier, whatever your `default_tier` setting, which lets commands write in the project folder, temporary folders and common tool caches. o4 starts no egress proxy for the check, so it has no network access, not even to package registries, unless a `[sandbox]` table without `allowedDomains` lifts the limit. If your check needs to download dependencies or write elsewhere, it may fail in ways it doesn't in a normal shell. See [Sandbox](/safety/sandbox).
* A check that runs longer than 10 minutes is stopped, and `o4 watch` exits with an error.
* Only the check's exit code decides pass or fail. o4 keeps up to 4 MB each of the command's standard output and standard error.

## Which changes trigger a check

o4 watches every file in the folder and its subfolders, and reacts when a file is created, changed or deleted. It ignores:

* Paths listed in the `.gitignore` in the root of the folder. Nested `.gitignore` files and your global git excludes aren't read.
* `.o4/index`, where o4 keeps its code index.

Everything else counts, including:

* Build output such as `target/` or `node_modules/`, unless your `.gitignore` excludes it. If the check itself writes files that aren't ignored, each run can start another one.
* The `.git` folder. Git commands that write to it, such as `git commit` or `git checkout`, start a check too.

## Options for the fix

Watch mode accepts the same global options as the rest of o4, and uses them for the fix run. Put them before `watch`:

```bash theme={null}
o4 -m anthropic:claude-sonnet-4-6 --permission-mode accept-edits watch
```

The fix runs in print mode, so the same permission rules apply: by default it runs in `auto` mode and anything that needs approval is denied. Use `--permission-mode` to allow less. See [Print mode and scripting](/guides/print-mode#permissions-in-print-mode).

Only `--command` goes after `watch`. Options such as `--permission-mode` after `watch` are rejected.

## Related pages

* [CLI reference](/reference/cli): every `o4` command and flag.
* [Configuration files](/configuration/overview): where `.o4/config.toml` lives and what else it holds.
* [Undo and rewind](/guides/checkpoints): the fix runs in print mode and isn't part of a session, so you can't rewind it. Commit before you accept a fix if you want an easy way back.