GitHub: github.com/srijanshukla18/vigil

Most file watchers were built for one narrow task.

• watch: run a command on interval
• fswatch: emit raw events
• viddy: provide a TUI-like terminal view
• lazygit: show git diffs
• entr: trigger command execution

When an LLM is editing code continuously, you need all three in one place: event stream, inline context, and operator visibility.

I did not want a full IDE overlay. I wanted a reliable terminal pane I could keep open while agents ran.

Why Existing Workflows Felt Wrong

I started with a common shell pattern:

fswatch -r . | xargs -I{} sh -c 'echo "--- {} ---" && git diff {}'

It worked in principle, but for long autonomous edits it broke quickly:

• assumes git history is the only truth
• floods on noisy saves
• difficult to follow scroll state
• no durable “ignore” policy for local noise
• no explicit follow/pause semantics for long runs

That was my proof that this was not a tool-combo problem. It was a product loop problem.

The UX I Wanted

I wanted one command and one predictable behavior:

vigil .

Then:

• recursive watch on a path
• live event stream with minimal jitter
• inline diff for text changes
• create / modify / delete visibility
• follow stream by default with manual scroll control
• clear stream without resetting context
• debounce save bursts and skip large/binary files by default
• ignore known noisy directories such as .git, node_modules, target, .DS_Store

No daemon. No remote dependency. Just a loop in the terminal.

What Vigil Actually Is Under the Hood

I kept the implementation boundaries small:

• notify for filesystem events across platforms
• similar for textual diffs
• ratatui + crossterm for terminal UI behavior
• clap for concise CLI arguments

No extra services. No backend. No special editor integration.

The behavior then becomes simple:

• watch directory or explicit path
• optional extension-based filtering
• optional path-ignore rules
• baseline initialization on first sight to avoid bogus “full-file diff” noise
• stream updates with inline patch-like change view
• automatic follow mode with manual overrides
• light controls for navigation and stream management

The difference is not just function list; it is predictability. Most command-line watchers behave like glue scripts. Vigil behaves like a runtime operator surface.

Why Not Git-Only

I could have built a watcher that shells out to git diff always. In reality that would miss a lot of agent behavior:

• temporary generated output
• work outside repo boundaries
• uncommitted scratch files
• transient folders that are still important signals

When agents are autonomous, some useful work appears before commit. A git-only model delays visibility by definition.

Defaults Matter More Than Fancy UI

The first version that passed personal use did not win on the UI polish. It won on policy:

• baseline cache to avoid fake initial diffs
• event debounce for “save storm” behavior
• ignore list for repetitive directories
• optional diff toggle so you can keep context without overload

Without these, the tool becomes noise; with these, it becomes usable in production-like sessions.

Small Interface, Long Utility

I kept keybindings boring:

• q: quit
• c: clear stream
• d: toggle inline diff
• j/k: scroll
• g / G: jump top/bottom

Small keys were a deliberate decision. In a loop where you are monitoring agent execution, cognitive load should be low.

That simplicity matters because vigil is not meant to replace your editor. It is meant to stay open, be readable, and require almost no training when you come back after stepping away.

I also kept the command surface minimal on purpose: path argument, optional filter flags, and explicit behavior, not a maze of modes.

Why I Built It This Way

The core insight is still simple: in autonomous editing, observability is part of correctness.

You can have great prompts and great models and still misread what is happening if you cannot see changes with confidence.

Practically, the tool is most useful for:

• watching whether an agent is in a tight loop
• catching accidental broad edits before they become commits
• validating that generated files land in the expected area
• deciding whether to pause or let an agent continue

Vigil became a practical middle layer:

• not full intervention
• not full delegation
• just continuous awareness

That level is enough to decide whether to interrupt, let it continue, or reframe the task.

Practical Rule

If your agent system touches code in real time, you need a local “change surface” as a first-class tool.

watch and kubectl -w are excellent for their domains.

Vigil is for active, local code mutation while another actor is driving.

That was the gap I kept feeling. That gap is now the reason I still keep it running.