You commit, an agent reviews the commit, and the review opens beside your code. This extension is
the editor side of the headwatch CLI (see the README one folder up), which does the actual work.
What you get
Sidebar (activity bar → Headwatch):
Challenge tabs, each with its checklist progress and a count of new reviews. Opening a file
inside a challenge folder switches to it. + New starts a challenge: the next numbered
folder with a README from the template.
A challenge without a README shows Create README from template in place of the progress bar.
Session goal: set one with Set a goal (a goal, then "done when" criteria). The card
shows the time spent and reviews so far, and a box for each criterion. Click a box to tick it
yourself; the reviewer ticks criteria your commits meet. End session writes a summary to
the log.
Status as a three-step tracker (Commit → Agent review → Ready), with a live timer while the
agent works and the error text when it fails.
Progress from the - [ ] / - [x] checklist in your project README: an overall bar, the
next unchecked item, and each group with its own count. Click an item to jump to it.
Reviews as a timeline, newest first, marked NEW until you open them and REPLIED once you've
answered. Ended sessions appear as milestones. The activity bar icon shows how many are new.
Status bar: shows whether it's watching, reviewing (spinner) or has a new review. Click it to
open the latest review, or the output if something went wrong.
Review panel: each new review opens beside your editor without taking focus. Step through
older reviews with ‹ Older and Newer ›.
Reply: puts your cursor under the review in the log file. The next review reads your reply,
and the panel shows it under the review.
Works with a terminal watcher: new reviews are picked up from the log file, so they appear
even when headwatch watch runs in a terminal and not in the extension.
Setup
Install the CLI (cargo install --path .. from this folder) and run headwatch init in your
repo.
Install the extension: npm install && npm run package, then
code --install-extension headwatch-0.4.0.vsix.
Open the repo in VS Code. Watching starts by itself when the folder has .headwatch.toml.
Commands
Command
What it does
Headwatch: Show Latest Review
Open the review panel
Headwatch: Reply to Review
Jump to the reply spot for the review shown in the panel
Headwatch: Open Review Log
Open the whole Markdown log
Headwatch: Start Watching / Stop Watching
Start or stop the background headwatch watch
Headwatch: Set Session Goal / End Session
Start or close the session goal for the current challenge
Headwatch: New Challenge
Create the next numbered folder with a README and a review log
Headwatch: Create README from Template
Add a README to the current challenge
Headwatch: Switch Challenge
Pick which challenge the sidebar shows
Headwatch: Review Last Commit Now
Review HEAD now, for a commit made before watching started
Headwatch: Show Output
The CLI's output, including agent errors
Settings
Setting
Default
headwatch.executable
empty
Path to the CLI. Empty: PATH, then ~/.cargo/bin/headwatch.
headwatch.autoStart
true
Start watching when the folder opens.
headwatch.onReview
open
open the panel, notify with a button, or none.
headwatch.progressFile
empty
Markdown file with the progress checklist. Empty: README.md in the first watched path.
Notes
Only one watcher can run per repo. If headwatch watch is already running in a terminal, the
extension's watcher stops with a message saying so. The review panel still updates either way.
The extension runs headwatch watch --events and reads its @headwatch ... status lines.
