Aider's --watch mode: live coding with AI suggestions in your editor of choice
Published 2026-04-04 by Owner
Aider’s standard usage is a chat session in your terminal — you switch away from your editor, type a prompt, switch back. For some workflows this is fine. For others, the context-switching is the friction that keeps Aider from being your daily driver.
aider --watch (sometimes called watch mode or AI! comment mode) sidesteps this. Aider runs in the background, watches your files for special trigger comments, and acts on them when you save. You stay in your editor; Aider responds to comments you write inline.
After three weeks of using watch mode as my default for some kinds of work, this is the setup and the workflow that’s emerged.
What watch mode does
Run Aider with the --watch-files flag in a terminal:
aider --watch-filesIt loads your files (or you /add them as usual) and then sits idle, watching for changes. When you save a file with a comment of the form AI! ..., Aider treats that comment as a prompt and acts on it.
Example. You write in your editor:
function parseDate(input: string): Date | null {
// AI! handle ISO 8601, RFC 2822, and unix timestamps; return null for invalid
}Save the file. Aider notices the change, sees the AI! comment, replaces it with a real implementation, and saves the file back. Your editor reloads (assuming auto-reload is on).
The result: Aider as a ghost in your editor that responds to specific comments rather than a separate REPL you switch to.
The two trigger forms
Aider recognizes two comment markers:
AI! — execute now, take action. Used for explicit work requests.
// AI! refactor this to use async/await instead of promisesAI? — answer the question, don’t change the code. Used for asking questions about code.
// AI? what's the time complexity of this function?You can also write multi-line prompts:
// AI! Replace this implementation with one that:
// - Uses a streaming JSON parser
// - Handles backpressure
// - Returns a typed error if input is malformed
function parseStream(input: NodeJS.ReadableStream) {
// ...
}The block of consecutive AI! comments is read together as the prompt.
A worked example
A real morning session, simplified:
// Step 1: I write the function signature and a comment
function calculateMonthlyTotals(transactions: Transaction[]): MonthlyTotal[] {
// AI! group by month, sum amounts, sort descending by month, return array
}Save. Aider sees the comment, fills in the body:
function calculateMonthlyTotals(transactions: Transaction[]): MonthlyTotal[] {
const groups = new Map<string, number>();
for (const tx of transactions) {
const month = tx.date.toISOString().slice(0, 7);
groups.set(month, (groups.get(month) ?? 0) + tx.amount);
}
return Array.from(groups.entries())
.map(([month, total]) => ({ month, total }))
.sort((a, b) => b.month.localeCompare(a.month));
}I review. Looks fine. I keep typing.
// Step 2: Add a test file
// In transactions.test.ts:
// AI! test calculateMonthlyTotals with three transactions across two months,
// AI! one transaction in a third month, and an empty input caseSave. Aider writes the tests. I review, run them, they pass.
The total time for a 30-line function plus tests was about 4 minutes, including the time I spent reviewing each output. Without watch mode, the equivalent in normal Aider would have involved switching to the terminal twice and re-explaining context.
What works well in watch mode
Single-function additions. “Add this function with this behavior.” Fast, in-place, no context switching.
Inline questions. “Why does this work?” The AI? form lets me ask without breaking flow.
Test generation alongside implementation. Write the function, add an AI! comment in the test file, save. Test appears.
Documentation generation. “Add JSDoc to this function” via AI! comment. Cleaner than a separate session.
Stub generation. Define an interface, add AI! comments inside an empty class, save, get a skeleton implementation.
The unifying pattern: tasks that are well-described by an inline comment in the code’s natural location.
What doesn’t work well in watch mode
Multi-file changes. Watch mode is single-file-focused. A change that touches three files is awkward; you’d add AI! comments in each, but the coordination between them is poor.
Interactive refinement. When the first AI! result isn’t right, you can edit the code and add another AI! comment, but it’s clunkier than the back-and-forth of normal Aider chat. For tasks where you expect to iterate, normal Aider is better.
Architectural questions. “How should I organize this module?” doesn’t fit in an inline comment well. Use a separate Aider session for these.
Debugging. “Why is this failing?” is rarely answerable by editing one file. Use normal Aider.
The unifying pattern: tasks that need conversation rather than execution.
Editor configuration that helps
A few editor settings make watch mode work better:
Auto-save. If your editor saves on focus-loss or after a brief delay, AI! comments trigger automatically. In VSCode: "files.autoSave": "afterDelay" with a 2-second delay.
Auto-reload. Your editor should reload files when they change on disk. Most editors do this by default. VSCode does. If yours doesn’t, watch mode produces stale-buffer issues.
Visible diffs. When Aider modifies your file, the changes appear in version control. A visible git status (status bar, gutter indicators) helps you see what changed. VSCode’s gutter is sufficient.
Format-on-save off, or whitespace-only. If your formatter aggressively reformats code, it can fight with Aider’s edits. Either turn format-on-save off in watched files, or use a formatter that only handles whitespace.
The workflow that emerges
After three weeks, my actual mix:
- Watch mode: about 60% of my Aider use. Most function-level work, test additions, doc generation, small inline tasks.
- Normal Aider chat: about 30%. Multi-file refactors, debugging, architectural discussions.
- Normal Aider one-off: about 10%. Quick “do this one thing in this one file” tasks where I happen to have a terminal open already.
The 60% in watch mode is the work that used to be the most disruptive — small tasks where the context-switch cost was a meaningful fraction of the work itself. Removing the switch made these tasks 2-3x faster end-to-end, even though the AI’s actual work-time was the same.
What surprises new users
Three things I wish I’d known earlier:
Watch mode runs against the conversation history just like chat mode. The conversation accumulates. If you start a watch session and gradually load more files, those files become context for subsequent prompts. This can be useful (the AI knows your codebase better) or a problem (token costs go up). Use /clear periodically.
You can still use slash commands while watch mode is active. The terminal where Aider is running accepts /add, /drop, /model, etc. Watch mode and chat mode aren’t separate; watch is just an extra trigger source.
The AI! comment is removed by Aider’s edit. When Aider acts on a comment, it replaces the comment with the code. So you don’t accidentally leave AI! comments in committed code. (Make sure your editor’s git diff view shows you what changed.)
Tradeoffs vs. other tools
Compared to inline tools like Cursor’s Cmd+K:
- Cursor’s Cmd+K is faster for the smallest changes. A 5-line edit is faster with Cmd+K than with watch mode, because you don’t need to write the comment.
- Watch mode is more flexible for multi-line/multi-step prompts. The AI! comment can be 10 lines specifying constraints; Cmd+K’s input is shorter and more pressured.
- Watch mode preserves Aider’s git-native commits. Each Aider edit produces a commit (configurable), which is useful for refactoring sessions. Cmd+K doesn’t.
For users already comfortable with Aider, watch mode is an enhancement, not a replacement. For users who’d previously written Aider off because of the chat-only UX, watch mode is what changes the calculus.
Setup TL;DR
# Install or upgrade Aider
pip install -U aider-chat
# Run with watch mode in your repo
aider --watch-files
# In your editor, configure auto-save with ~2s delay
# Write AI! or AI? comments in your code
# Save the file; Aider acts on the commentTen minutes to set up. Three days to internalize the workflow. After that, it’s the most natural Aider mode for the work it suits, and the friction of normal Aider feels suddenly higher than it used to.
