Skip to main content
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:
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:
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:
  • Press Enter to fix it. o4 runs the agent once, in the same way as 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.
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.
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.
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.

​
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:
To use a different command once:
To set it for the project, add it to .o4/config.toml:
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. 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.
  • 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:
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. Only --command goes after watch. Options such as --permission-mode after watch are rejected.
  • CLI reference: every o4 command and flag.
  • Configuration files: where .o4/config.toml lives and what else it holds.
  • Undo and rewind: 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.