vibeflow watch.
The task store, as a stream.
One long-running command that emits an event every time a task changes — created, moved to todo, reprioritised, commented on. Point it at a file or a webhook to drive agent loops and CI.
Quick start
Run it where your agent runs.
Watch continuously.
The default mode runs until you interrupt it (Ctrl+C) and prints full ticket details on every event. Events cover new tasks, moved-to-todo, status, comments, files, priority and description changes — enough to wake an agent the moment work becomes claimable.
-
Agent loop — watch for new todo work, then run
tasks --next. -
Notifications —
--webhook <url>POSTs each event as JSON to your own service. -
Logging —
--output <file>appends JSONL lines to a file.
Poll, emit, exit.
--once diffs the store against your
cursor, emits the pending events and exits — the shape you
want in a cron job, a CI step or a shell script.
Flag reference
Flags.
Run npx @vibeflow-tools/cli watch --help
for the canonical list.
| Flag | What it does |
|---|---|
| Usage | |
[dir] |
Project root directory to watch (default .). |
| Options | |
--json |
Emit events as JSONL lines to stdout. |
--output <file> |
Append JSONL events to a file. |
--webhook <url> |
POST each event as JSON to a webhook URL. |
--once |
One-shot poll: diff against state, emit events, exit. |
State
Where the cursor lives — and the gap rule.
-
Journal, not a snapshot —
.vibeflow/watch-state.jsonis an append-only journal with a cursor per consumer. - Gap rule — events older than one minute that were not delivered trigger an explicit gap event instead of a silent hole.
- Read-only — watch never modifies tasks; it only reports what the store did.
If something looks wrong
Common questions.
Does watch change my tasks?
No — watch only reads the task store and emits events. The one file it writes is its own state journal, .vibeflow/watch-state.json.
What if my watcher was down for an hour?
State is an append-only journal with a cursor per consumer, so a restarted watcher resumes where it left off. Events older than one minute that were never delivered do not arrive silently — they surface as a gap event, so your automation knows to re-read the store instead of trusting a hole in the stream.
Can several watchers run at once?
Yes — cursors are kept per consumer in the same journal, so each watcher (daemon, CI job, webhook relay) tracks its own position independently.
Related pages
Where to go next.
- How to use Vibeflow — the three-step workflow from annotation to merge
- vibeflow tasks — the command that claims the work watch sees
- vibeflow kanban — the board these events describe
- Give your AI agent UI context — why structured tasks beat prose
Ten seconds to your
first annotated task.
No account, no cloud, no browser extension.
Apache-2.0 · Node.js 22+ · tasks stay in your repository