The field guide.
A practical handbook for working with Operator — not a step-by-step tutorial but an annotated reference you'll return to as your use of agents deepens. Six chapters, roughly twelve minutes, read in any order.
Frame the outcome, not the method.
Operator's output is only as good as your instruction — not because it needs hand-holding, but because ambiguous scope invites over-reach. A well-framed request usually runs without a single clarifying question.
- Start with a clear outcome, not a method — Operator will sometimes find a better approach than the one you had in mind.
- Scope is your strongest lever. When in doubt, narrow it; you can always widen it on the next run.
- Constraints are information, not restrictions — “Node 18, no ESM” or “stay backwards-compatible” tells it how to decide without stopping to ask.
- Paste one concrete example — a single “like this” is worth three paragraphs of description, and Operator generalises from it.
01“wire a Stripe webhook for failed payments”
02plan · 3 steps — endpoint, retries, alert
03generated app/api/stripe/webhook/route.ts
04preview ready — pr-447.kaer.dev
05one-tap approval from your phone
06✓ handed off to Operator — PR opening
07the thread follows you — laptop, phone, tablet
01“wire a Stripe webhook for failed payments”
02plan · 3 steps — endpoint, retries, alert
03generated app/api/stripe/webhook/route.ts
04preview ready — pr-447.kaer.dev
05one-tap approval from your phone
06✓ handed off to Operator — PR opening
07the thread follows you — laptop, phone, tablet
Let it plan before it touches a file.
Operator reasons about the best path before acting. The reading phase is often longer than the writing phase — a quiet stretch is usually mid-read, not idle.
- Don't interrupt a quiet stretch — a reset loses the context Operator has built by reading your code.
- On ambiguous or risky tasks it surfaces the plan as text first — that pause is the approval gate working, not indecision.
- For large work it decomposes into phases itself; giving it a phased structure just makes each diff smaller to review.
- Ask it to “walk me through the plan before making changes” to approve, redirect or narrow before a character is written.
Planning is not overhead. The biggest source of wasted agent time is acting on a misunderstood task — a 30-second plan prevents a 10-minute rollback.Field guide · Letting it plan
Read the diff in two minutes flat.
Operator's output is a git diff, and reading it well is a fast skill. The goal isn't every line; it's the few that matter. The pattern: file list, then deletions, then test changes, then comments.
- Read the file list first — a change outside the expected radius is the most common thing worth redirecting. Sort by path, not line count.
- Scan deletions before additions. Added lines are usually low-risk; deleted lines are where intent lives. Red before green.
- Watch for quiet test relaxation — a new .skip() or a dropped assertion is a silent regression. Grep for skip/xit after every run.
- Read the comments Operator adds — they document the decision behind the change, not noise.
export function charge(user: User) {
− return flatRate(user.plan);
+ const used = meter.creditsFor(user);
+ return creditRate(user.plan, used);
}
Gates are the handshake, not an interruption.
Operator pauses before anything hard to reverse — pushes, merges, schema migrations, infrastructure. For most tasks the only gate is the final “merge this PR?”; the rest runs unattended.
- If a run hits zero gates, check the scope — either it's genuinely safe to run unattended, or it's narrower than you realised.
- Each gate shows what it's about to do and why. Approve, reject, or redirect — you're approving intent, not implementation.
- Configure gates per workspace — before any network call, any deletion, any commit, or none at all for a trusted repo. Defaults are conservative.
- Gates carry context: reject with a reason and Operator folds it forward. A rejection is a course correction, not a restart — prior work stays.
01$ kaer automation · nightly-report
02trigger 02:00 · fetch metrics · render summary
03connected · postgres · slack · gmail
04approval gate — send to #team?
05✓ approved on phone · report delivered
06next run scheduled · tomorrow 02:00
07audit log · every action attributed
01$ kaer automation · nightly-report
02trigger 02:00 · fetch metrics · render summary
03connected · postgres · slack · gmail
04approval gate — send to #team?
05✓ approved on phone · report delivered
06next run scheduled · tomorrow 02:00
07audit log · every action attributed
Redirect the direction, correct the detail.
Redirection is the normal mode of working with an agent, not failure. Two or three redirects is a healthy session; knowing when to steer rather than restart is what keeps it productive.
- Wrong detail is a correction — one sentence. Wrong direction is a redirect — one paragraph. Restarts are rare.
- Surface the constraint, not the symptom: “stay compatible with v2 clients” beats “don't touch the schema” — it lets Operator solve it differently.
- Partial work isn't wasted — redirected files stay on disk and Operator builds on them next run. You're steering a session, not resetting a test.
- Some redirects are architectural — “step back, this is too complex” is valid; Operator assesses what to unwind and proposes a simpler path.
Recovery is part of the workflow.
Occasionally a run stalls, errors, or produces output you can't use. With the right routine a stalled run is a five-minute interruption, not a lost afternoon.
- Most “errors” are clarification requests in disguise — a missing credential, an uninstalled dependency, a conflict in your instructions. Read the stop message; it's the most diagnostic output there is.
- Read the session log before restarting — every file read, plan, gate and action is there, so you can redirect to the point it went off-track instead of rerunning.
- For partial output, commit the good parts first, then start a narrower follow-up from that checkpoint — Operator reads the committed state and continues.
- Three failures at the same point means an environment problem, not a task problem — a missing dependency or an expired credential. Change something before retrying.
Operator is best understood in motion.
The guide gives you the vocabulary; the intuition comes from running tasks. Start with something small, in a codebase you know well.
or see how operator works