Watching a directory (hh watch)
hh run -- <agent> records an agent it launches. Some agents can't be
launched that way: a GUI app, an IDE extension, or an agent session that is
already running in another terminal. hh watch records what such an agent
does — every file it creates, edits, renames or deletes in a directory —
without starting it.
hh watch # the current directory, until Ctrl-C
hh watch ~/code/site # a specific directory
hh watch ~/code/site --daemon # in the background
hh watch --status # what is being watched
hh watch ~/code/site --stop # finish a background watch
hh watch --idle-timeout 15m # finish after 15 minutes without changes
A watch session is an ordinary session: it appears in hh list, and
hh replay, hh inspect --diff, hh export, hh scan and hh search work
on it like any other.
Worked example: recording a GUI agent's work
Say a desktop coding agent is about to refactor ~/code/site, and you want a
record of exactly what it changed.
Start watching the project before you give the agent its task:
$ hh watch ~/code/site --daemon --name "desktop agent: auth refactor" ● Watching /home/me/code/site in the background · session 3fa2c1 · pid 48213 · stop with `hh watch --stop`From the moment that line prints, every change under the directory is recorded. The files already there are the session's baseline, so the first edit to each one diffs against what it held before the agent touched it.
Work with the agent in its own window as usual. Check on the watch at any time:
$ hh watch --status PATH SESSION PID MODE STARTED FILES ------------------ ------- ----- ---------- ------- ----- /home/me/code/site 3fa2c1 48213 background 5m ago 4When the agent is done, stop the watch. The session is finalized before the command returns:
$ hh watch ~/code/site --stop ✓ Stopped watching /home/me/code/site · session 3fa2c1 · 12m4s · 6 steps · 4 files changed · hh replay 3fa2c1Review what happened:
hh replay 3fa2c1 # step through each change, with diffs hh inspect 3fa2c1 --diff # or print everything as one unified diff
Without --daemon, hh watch stays in the foreground and Ctrl-C finishes the
session, printing the same summary hh run prints.
What gets captured
Only file changes: the same watcher, ignore rules (.git/, node_modules/,
target/, the root .gitignore, [record] ignore), size limit
([record] max_file_size), binary handling and before-side rules as
hh run (Recording). Record-time redaction
([redaction] at_record) applies too.
There is no wrapped command, so there is no terminal output and no transcript — a watch records what was done, not what the agent said or which tools it called. A change is recorded whichever process makes it: the agent, you in your editor, or a build tool. Watch a directory you are not also editing if you want the record to be the agent's work alone.
In the session data a watch session has:
| Field | Value |
|---|---|
command |
[] (hh list shows (watch: file changes only)) |
capture_tier |
effects, set when the session starts |
agent_kind |
generic |
exit_code |
null |
status |
ok when stopped by Ctrl-C, --stop, SIGTERM or the idle timeout |
hh replay states the gap in its header: watched directory — file changes only, no terminal or transcript.
One watcher per directory
A directory has at most one watcher. A second hh watch on the same
directory — however the path is spelled — prints the running session and
exits 0 without starting another:
$ hh watch ~/code/site
● Already watching /home/me/code/site · session 3fa2c1 · pid 48213 · `hh watch --stop` to finish it
Watching a directory and, separately, a subdirectory of it are two watchers, and a change in the subdirectory is recorded by both.
Stopping
| How | Result |
|---|---|
| Ctrl-C (SIGINT) in the foreground | Session finalized as ok. |
hh watch [path] --stop |
Sends SIGTERM to the watcher for that directory and waits (up to 30 s) until its session is finalized. Running it when nothing is watched prints No watcher running and exits 0. |
kill <pid> (SIGTERM) |
Same as --stop, without waiting. |
--idle-timeout <duration> |
Finishes on its own after that long with no filesystem activity in the directory (90s, 15m, 2h; a bare number is seconds). Off by default. Any filesystem event counts as activity, ignored paths included. |
A change made just before the stop is still recorded: on shutdown the watcher drains events still in flight and rescans the directory for anything it missed.
If a watcher dies without finalizing (killed with SIGKILL, a crash, a reboot),
the next hh command of any kind marks its session interrupted — the same
check that recovers a crashed hh run — and clears its lock, so the directory
can be watched again. Everything recorded up to the crash is kept.
Background watchers (--daemon)
--daemon starts the watcher detached from the terminal: in its own process
group, ignoring SIGHUP, with no stdin. It returns once the watcher is
observing. Files it keeps under the data dir:
| File | Contents |
|---|---|
<data dir>/watch/<key>.lock |
The watcher's pid, process start time, directory and session (JSON). It is the PID file, and it is also what enforces one watcher per directory. It is removed when the session has been finalized. |
<data dir>/watch/<key>.log |
The background watcher's warnings and its final summary line. Appended to by every background watch of that directory. |
<key> is derived from the directory's canonical path.
--daemon and --stop are not available on Windows yet; there, run
hh watch in its own terminal and press Ctrl-C to finish.
Directories hh refuses to watch
hh watch refuses your home directory, any directory that contains it, and a
filesystem root (/, C:\). Watching one would exhaust the operating
system's file-watch limits and record everything you do, not just the agent's
work. Watch the project directory the agent works in instead.
$ hh watch ~
✗ refusing to watch /home/me
why: it is your home directory — watching it would exhaust the operating system's file-watch limits and record everything you do, not just the agent's work
hint: watch the project directory the agent works in, e.g. `hh watch ~/code/my-project`
On Linux, a large project can still run into the per-user inotify watch
limit; hh doctor --capture reports it (Effect capture).
Exit codes
| Code | When |
|---|---|
0 |
The session was recorded and finalized; or a watcher already holds the directory (it is reported); or --stop found nothing to stop; or --status. |
1 |
The watch could not start or finish: the store can't be opened, the directory can't be watched at all, a background watcher failed to start, --stop could not signal the watcher or it did not finish in time, or --daemon/--stop on Windows. |
2 |
Usage error: an unknown or conflicting flag, a bad --idle-timeout, a path that does not exist or is not a directory, or a refused directory (home, an ancestor of home, a filesystem root). |
See Exit codes.