DEV Community: Aviv Laufer

Every PR gets an agent review before a human sees it

Aviv Laufer — Tue, 10 Nov 2026 16:07:14 +0000

Part 4 of My Agentic Setup. Start from part 1

About 50 PRs a week come to me for review. I don't open any of them cold.

Each PR gets read first by an agent, in its own pane. The agent can read the PR and nothing else: it can't comment, approve, push or merge. It writes a report on my machine, and I read the report before I open the diff.

I start all of it with one command:

fmreview https://github.com/acme/api/pull/123 acme/web:45 'acme/api#130'

The idea: every PR gets a review from a model on a different vendor than the one that wrote the code, the reviewer is read-only, and its report comes to me before anything is posted on GitHub.

What broke

The reviewer model didn't reach the reviewers

My main agent, OMP, has a reviewer role pinned to a model on another vendor. But the pin applies only to a subagent whose type is literally reviewer.

My review agents are Firstmate scouts, and a scout is not a reviewer. Neither are the subagents a scout starts on its own. None of them get the reviewer model by themselves.

The fix is to pin the model by hand, every time. The note in my captain's preferences:

- Dispatch every code-review task on `openai-codex/gpt-6.1-sol` at high effort,
  not the default model (same as omp's `task.agentModelOverrides.reviewer` and
  `FMREVIEW_MODEL`). When spawning the scout, pass
  `--model openai-codex/gpt-6.1-sol --effort high` explicitly (the omp override
  only auto-applies to a subagent literally typed `reviewer`, not to a
  `scout`-typed spawn or its own internal fan-out subagents)

And fmreview puts the model into the message it sends, so the first mate doesn't have to remember:

# Keep FMREVIEW_MODEL/EFFORT in sync with
# task.agentModelOverrides.reviewer in ~/.omp/agent/config.yml.
: ${FMREVIEW_HARNESS:="omp"}
: ${FMREVIEW_MODEL:="openai-codex/gpt-6.1-sol"}
: ${FMREVIEW_EFFORT:="high"}

There is also an option to start omp in the reviewer role from the command line, if your omp build supports it. I leave it empty. Pinning the model is the path I verified.

`#` is a glob in my shell

The short way to name a PR is acme/api#123. In zsh with extendedglob on, # is a glob operator, so that word has to be quoted, or zsh tries to match files with it.

So fmreview also takes a form that needs no quotes:

case "$t" in
  https://github.com/*/pull/*)
    t="${t#https://github.com/}"; printf '%s#%s\n' "${t%%/pull/*}" "${t##*/pull/}" ;;
  */*\#[0-9]*) printf '%s\n' "$t" ;;
  # owner/repo:123 needs no quoting under extendedglob, unlike the # form.
  */*:[0-9]*) printf '%s#%s\n' "${t%%:*}" "${t##*:}" ;;
  [0-9]*) [ -n "$dr" ] && printf '%s#%s\n' "$dr" "$t"; return 0 ;;
  *) return 1 ;;
esac

A bare number works too, with --repo acme/api.

herdr's split ratio is the other way around

Before fmreview I had a simpler batch launcher: one pane per PR, each running a review. The first version was for cmux, which takes a whole pane layout as JSON in one call. When I moved to herdr, there was no such call. Panes are made one herdr pane split at a time.

To get equal panes, you split off one slice at a time. herdr's --ratio is the share the original pane keeps, not the share the new pane gets. Splitting a 20-row pane with --ratio 0.75 leaves it 15 rows and gives 5 away. So to carve n equal slices, the ratio at each step is 1/n:

split_off() {
  herdr pane split "$1" --direction "$2" \
    --ratio "$(awk "BEGIN { printf \"%.6f\", 1 / $3 }")" --no-focus |
    json_get result.pane.pane_id
}

The panes are laid out as a grid, rows first, so the PRs read left to right and top to bottom, and the panes stay close to square. Five PRs make three panes on top and two below.

A running server that looked down

The launcher checks that a herdr server is running. The obvious check is:

herdr status server | grep -q "status: running"

With set -o pipefail, this fails even when the server is up. grep -q exits on the first match and closes the pipe. herdr is still writing, gets SIGPIPE, and exits with an error. pipefail reports that error as the result of the whole pipeline.

The fix is to capture first and match after:

server_status="$(herdr status server 2>/dev/null || true)"
case "$server_status" in
*"status: running"*) ;;
*) echo "Error: no herdr server is running. Start one with: herdr" >&2; exit 1 ;;
esac

The setup

One PR: review-pr

The smallest piece is review-pr. It takes a PR URL, goes to my clone of that repo, and starts Cursor's agent CLI with the /review-pr command:

if [[ "$PR_URL" =~ github\.com/([^/]+)/([^/]+)/pull/[0-9]+ ]]; then
    ORG="${BASH_REMATCH[1]}"
    REPO="${BASH_REMATCH[2]}"
fi

REPO_DIR="$HOME/GitHub/$ORG/$REPO"
cd "$REPO_DIR"
exec "$(dirname "$0")/wt-agent" agent "/review-pr $PR_URL"

It needs the repo cloned at ~/GitHub/<org>/<repo>, and it stops if the folder isn't there. /review-pr is the command from the pr-review-toolkit plugin. wt-agent sets a marker in wt list while the agent runs, so I can see which worktrees have an agent in them.

The review stays in the pane. Nothing is posted.

Many PRs: one scout each

For a batch, I use fmreview. It does four things:

Normalizes each PR to owner/repo#number.
Creates a Firstmate home called reviews, the same way fm does, if it doesn't exist.
Writes a review charter into that home.
Opens the home in herdr, waits for omp to start, and sends the first mate this message:

ahoy

Dispatch one SCOUT per pull request below. One scout each, in parallel, each in its own pane.

Pull requests:
- acme/api PR #123
- acme/web PR #45

Profile for every one of these scouts: harness omp, model openai-codex/gpt-6.1-sol, effort high.

Register each repo as local-only if it is not registered yet.

Every brief must carry the full contents of data/review-charter.md in its Firstmate spec.
The charter is binding: these scouts are read-only and must not comment, review, approve,
request changes, push, or merge anything on GitHub.

When a scout finishes, relay its verdict and findings to me and then STOP. Do not act on
any recommendation, do not open follow-up tasks, and do not tear the scout down until I say so.

local-only means the first mate never opens a PR for that repo. A scout writes a report, never code.

fmreview --print shows the message without sending it.

The charter

Every scout gets the same charter, word for word, in its brief. The first part is about what it may not do:

## Read-only, without exception
- NEVER post a comment, review, approval, change request, or reaction on GitHub.
- NEVER push, close, reopen, label, assign, or merge anything.
- NEVER edit files in the project clone or the worktree.
- `gh` is for READING the PR only: diff, files, checks, linked issues.
- The single deliverable is `data/<id>/report.md`. Nothing leaves the machine.
- If the review implies an action, write the recommendation in the report and
  stop. The captain decides every next step.

The second part is what the report has:

- Verdict in one line, then findings ordered by severity.
- Every finding cites `path/to/file:line` from the PR's own diff.
- Separate what the diff does from what it fails to do.
- Call out failing or missing CI checks and say what they imply.
- Flag anything touching auth, tenancy boundaries, data retention, migration
  ordering, or IAM as captain-escalation regardless of test status.
- End with a short list of open questions for the author.

The third part says which review tools win when they disagree. First, the repo's own review rules, when a repo has them. A repo with compliance rules, for example, gets those checked before anything generic. Then pr-review-toolkit for the mechanics: correctness, edge cases, error handling, tests for the changed lines. Then a second mechanical pass, only on what the first two didn't cover.

Each finding goes in the report once, under the tool with the highest precedence that found it. The report also says which tools were there and which weren't. If none loaded, it says so and reviews without them, instead of guessing what their checklists say.

Five passes, one of them for the spec

Inside each review there are five review passes, all on the reviewer model. Four look at the code. The fifth is a spec reviewer, and it gets less context on purpose: only the diff, the commit list, and the linked ticket. When there's no ticket, it gets the intent from the brief.

It returns three lists, and every item quotes its source line:

asked but not built
built but not asked for
built wrong

The other four passes read the code the way the author meant it. This one checks the code against what was asked.

The reviewer is on a different vendor

The model that writes most of my code is Claude. The reviewer is a GPT model, so the reviewer is never the same model that wrote the code.

The profiles in my dotfiles set this per machine:

# Agent pins (task.agentModelOverrides). The pr-review-toolkit agents are the
# cheap first pass; reviewer and security-reviewer are the real gate.
reviewer = "openai-codex/gpt-6-sol:high"
security-reviewer = "anthropic/claude-sonnet-5-5:high"
code-reviewer = "@crew-light"
silent-failure-hunter = "@crew-light"
pr-test-analyzer = "@crew-light"
comment-analyzer = "@crew-light"

@crew-light points at another role, a small model. The pr-review-toolkit agents run often, so they get the cheap model. The security reviewer is Claude, so only the main reviewer is on the other vendor.

What runs today:

Role	What it does	Work laptop	Personal laptop
default, crew	writes the code	Claude Sonnet 5.5	Claude Sonnet 5.5 via Cursor
reviewer	the real gate, `fmreview` scouts	GPT-6.1 Sol, high	GPT-5.6 Terra via Cursor, high
security-reviewer	security pass	Claude Sonnet 5.5, high	Claude Sonnet 5.5 via Cursor, high
pr-review-toolkit agents	cheap first pass	Claude Haiku 5.5	Claude Haiku 5.5 via Cursor

When my own agents open the PR

The same review runs on the other side, when my agents write the code. These rules are in the instructions every agent gets (trimmed):

- Before opening: run the review skill (the repo's own, or
  `pr-review-toolkit:review-pr` otherwise) and `simplify`, and address the findings.
- Always draft (`gh pr create --draft`).
- Promote to ready only on the captain's explicit instruction for that PR. Green
  CI or self-review never authorizes promoting or merging.
  Humans approve and merge (squash); do not merge unless asked.

So an agent's PR has been reviewed by an agent before it exists, and a human still decides when it's ready and when it merges.

A budget for review rounds

The newest change is a limit on how many times a PR goes back and forth with a reviewer. Until late October, nothing in my setup said when to stop. Now my captain's preferences have this:

### Review budget
- Default to 3 review rounds per PR. Round 1 is a full review. Later rounds
  check only the changed code and the findings that are still open.
- Extend to 5 rounds only when the change touches security, permissions, auth,
  data loss, or state and concurrency, and a blocker is still open with
  evidence. Also extend when the captain asks.
- Stop early when a round returns only nits.
- Keep a ledger of every finding: id, severity, and outcome (fixed, rejected
  with reason, or open). Never guess usage or token numbers. Report only what
  the tools show.
- Make the smallest change that satisfies a reviewer. Do not widen the scope
  to fix things nobody flagged.

With the ledger, every finding ends with an outcome, and "rejected" needs a reason. A finding can't just disappear.

Try it

The companion folder has sanitized copies of review-pr and the herdr batch launcher, the PR parser, a script that prints the fmreview message, and the charter. The tests use a fake agent CLI and a fake herdr that keeps the size and place of every pane, so they check the real grid for 1 to 7 PRs, not just the calls. They also check URL quoting, PR parsing, and the read-only lines in the message.

cd 04-pr-review
make test

golem-notes-examples/04-pr-review

Who reviews your agents' code, and does the reviewer come from the same vendor as the author? Leave a comment.

This is part 4 of my series on running a real agentic dev setup. I publish each part first on Golem Notes, with the full write-up and what's coming next. Subscribe there to get the next one in your inbox: Golem Notes

My agents on two laptops, controlled from one phone app

Aviv Laufer — Wed, 28 Oct 2026 05:17:43 +0000

Part 3 of My Agentic Setup. Start from part 1

I have two laptops, a work laptop and a home laptop. Both run herdr, and both have agents working in it. I sit in front of one of them. The agents on the other one keep going, and sometimes they stop and wait for me: a question, an approval, a "done, what next?".

I wanted three things:

See and answer the agents on both laptops from my phone.
Get a shell on the home laptop from the work laptop.
The work laptop holds work credentials, so it accepts no incoming connections. Not from the phone, not from the home laptop, not from anywhere.

The idea: each laptop runs its own relay behind its own permanent address, both relays point the phone at the same app, so one app shows the agents from both laptops, and nothing on either laptop listens on the internet.

The relay was the easy part. The domain, the app's address and the closed lid were not.

What I use

From	To	How	When
Phone	both laptops	herdr-mobile-relay over a Cloudflare tunnel	every day
Work laptop	home laptop	SSH over Tailscale, then `hr-home`	every day
Work laptop	home laptop	SSH over Cloudflare Access	the setup with no VPN on the work laptop

The phone app is herdr-mobile-relay, a herdr plugin by 0cv. It has its own docs and a setup wizard, so I won't repeat them here. This post is about my setup around it, and what broke.

What broke

I couldn't use a domain I already had

I wanted a permanent hostname per laptop, so I used the relay's stable tunnel option. That runs on a Cloudflare tunnel, and a Cloudflare tunnel needs the domain's DNS hosted on Cloudflare.

The catch: below the Enterprise plan, Cloudflare can't take over just one subdomain. It takes the whole zone. My existing domain had its DNS somewhere else, with my website and email forwarding on it. Moving all of that just to get one hostname for a relay didn't make sense.

So I bought a new domain on Cloudflare Registrar. It starts on Cloudflare DNS, so there is nothing to move, and the wizard creates the relay records by itself. Nothing else lives on that domain. In this post it's example.dev.

Before running the wizard, check that the zone is live. It can take up to an hour after the purchase:

dig NS example.dev +short     # two *.ns.cloudflare.com names

The second laptop made a second app

The wizard asks two questions that look the same and aren't.

The first is the hostname. That is the laptop's own address, and each laptop gets its own:

work laptop: work-relay.example.dev
home laptop: home-relay.example.dev

The second is "Where should the phone setup link open?". This one is not about the laptop. It picks where the phone app is served from.

That matters on iOS, because iOS ties a home-screen app to the address it was installed from. If each laptop serves its own app, the phone gets two separate Herdr apps, each with one laptop in it. That is the opposite of what I wanted.

So the two laptops answer differently:

	Work laptop	Home laptop
Laptop's own address	`work-relay.example.dev`	`home-relay.example.dev`
Answer to "where should the phone setup link open?"	1. This relay	2. An existing installed Herdr app, then `https://work-relay.example.dev`
Where the phone app lives	`work-relay.example.dev` (creates it)	`work-relay.example.dev` (joins it)

Then, on the phone, import the home laptop's invite from inside the installed app, not with the camera. The app then shows 2/2 relays, with agents from both laptops in one list.

The phone app lives on one laptop

That answer has a cost. The work laptop serves the phone app, so a fresh install of the app, or an app update, needs the work laptop awake and online. The relay setup menu has an option, Configure App Deployment, that can move the app to Cloudflare Pages later and remove that dependency. Run it on one laptop only, the one that publishes app updates.

One more thing not to do: don't put Cloudflare Access in front of the relay hostnames. The relay already accepts only paired devices, and Access blocks the phone app.

Closing the lid still puts the Mac to sleep

A sleeping laptop can't be reached. Not by the relay, not over SSH.

My first setting for the home laptop was the usual one:

sudo pmset -c sleep 0          # never idle-sleep on the charger

That only stops idle sleep. Closing the lid is a separate trigger. macOS ignores the lid only in clamshell mode, and clamshell mode needs three things: the charger, an external display, and an external keyboard or mouse. Without a display, the power log shows a sleep like this, even with sleep 0:

Entering Sleep state due to 'Clamshell Sleep' ... Using AC

My home laptop is a MacBook Pro with an HDMI port, so the fix was an HDMI dummy plug, about $10. It tells macOS there is a monitor. With the plug in and the charger on, the Mac stays awake with the lid closed. Apple documents a keyboard or mouse as required too, but on this Mac it wasn't needed.

I tested it overnight. The lid was closed for about 16.5 hours, with the plug and no mouse. The best check is not the power log, which is huge and noisy. It is this:

sysctl kern.sleeptime kern.waketime

If both times are from before you closed the lid, the Mac didn't sleep. Mine still showed a sleep from before the plug went in.

Two things that didn't help:

sudo pmset -c disablesleep 1 keeps it awake with the lid closed, but on my Mac it didn't stay limited to the charger. It showed up as a global setting, so a closed Mac on battery would stay awake too. I turned it back off.
Herdr.app has a coffee cup in its status bar that keeps the Mac awake, for example "until agents finish". It only stops idle sleep. Closing the lid still sleeps the Mac.

The full AC settings on the home laptop:

sudo pmset -c sleep 0          # never idle-sleep on the charger
sudo pmset -c disksleep 0
sudo pmset -c womp 1           # wake on network access
sudo pmset -c displaysleep 15  # the screen may still turn off
pmset -g custom                # check the "AC Power" section

-c is charger only. Battery stays at its defaults.

One case no sleep setting fixes: with FileVault on, after a reboot the Mac waits at the login screen until someone unlocks it in person.

A warning about pairing on iOS

This is from the setup docs, and it's easy to get wrong. On iOS, the home-screen app and the browser keep separate storage. So if you scan the pairing QR and pair in the browser tab, you paired the tab, not the app.

What to do instead:

Scan the QR with the camera. The page says "Add Herdr to the Home Screen". Don't tap "Pair this browser instead".
Add it to the home screen, then open it from the home-screen icon.
If the app says "refused this device", the one-use invite was already used by the browser tab. Print a fresh one on the laptop (command below) and import it inside the app.
In the app, open gear > Devices, rename this device, and revoke any extra entry the browser tab left behind.

A fresh invite:

herdr plugin action invoke setup-link --plugin herdr-mobile-relay.events

The setup

One relay per laptop

On each laptop:

herdr --version                                   # 0.7.5 or newer
herdr plugin install 0cv/herdr-mobile-relay
herdr plugin action invoke install-service --plugin herdr-mobile-relay.events

The last command is the stable tunnel wizard. It opens a browser for the Cloudflare login, asks for the hostname and the app question above, then creates the tunnel, the DNS record and a background service, and prints the pairing QR.

The login writes ~/.cloudflared/cert.pem. That file is a credential. It never goes into dotfiles.

To check a relay:

herdr plugin action invoke status --plugin herdr-mobile-relay.events
curl -s http://127.0.0.1:8375/readyz -o /dev/null -w '%{http_code}\n'   # 200 when ready

Both laptops dial out to Cloudflare. No port is open on either one, and no router is touched. Traffic through the relay is end-to-end encrypted, so Cloudflare sees timing and frame sizes, not prompts or terminal output.

Devices and roles

My phone is the only controller. A controller can type, answer approvals, and start and stop agents. Any other device is a reader: it can watch, but it can't type, approve or upload.

In the app's settings, device lock is on, so it checks the device when it opens and when it comes back.

The pairing QR and link are passwords. Each one holds a one-use invite that expires after ten minutes. Don't screenshot it and don't paste it anywhere.

The phone and Firstmate

Firstmate drives the same herdr sessions. From the phone, I watch the crew and I work in my own sessions. I don't type into a Firstmate worker's pane: Firstmate treats that as me stepping in, and fixes it up on its next check.

SSH from the work laptop

The phone is for watching and answering. For shell work on the home laptop, I SSH in from the work laptop. I set this up two ways, and I use Tailscale day to day.

Tailscale: three locks on the work laptop

All three devices, both laptops and the phone, are on one personal Tailscale network. The default Tailscale policy lets every device reach every other device. I replaced it with this:

{
  "tagOwners": {
    "tag:home": ["autogroup:admin"]
  },
  "acls": [
    { "action": "accept", "src": ["autogroup:member"], "dst": ["tag:home:22"] }
  ]
}

My devices can reach port 22 on machines tagged tag:home. Nothing else is allowed. Only the home laptop has that tag. A tagged device also has key expiry turned off, so it doesn't drop off the network every 180 days.

That is one lock on the work laptop. There are two more:

No SSH server. Remote Login stays off in System Settings.
Shields Up. The Tailscale app refuses incoming connections on this device.

tailscale set --shields-up=true
tailscale debug prefs | grep -i shields      # "ShieldsUp": true
netstat -an -p tcp | grep LISTEN | grep '\.22 ' || echo "no ssh server"

And the check that matters, from the home laptop:

nc -vz -G 3 <work-laptop> 22      # must fail

tailscale ping may still answer. Ping isn't covered by the policy.

Tailscale's own SSH server isn't available in the macOS app, so the home laptop uses the Mac's normal OpenSSH, reached only over Tailscale. The SSH config entry on the work laptop:

Host home-ts
    HostName home-laptop
    IdentityFile ~/.ssh/id_ed25519_<this-machine>
    ServerAliveInterval 30

One key per machine, generated on that machine. After ssh-copy-id works, password logins on the home laptop are turned off:

printf 'PasswordAuthentication no\nKbdInteractiveAuthentication no\n' \
  | sudo tee /etc/ssh/sshd_config.d/100-keys-only.conf
sudo launchctl kickstart -k system/com.openssh.sshd

Keep that session open and test a new ssh before you close it.

Cloudflare Access: no VPN on the work laptop

The other way uses no VPN on the work laptop at all. The home laptop runs a second cloudflared tunnel, for SSH only, separate from the relay's tunnel. The work laptop's ssh goes through cloudflared access ssh, which only makes outgoing connections:

Host home
    HostName ssh-home.example.dev
    IdentityFile ~/.ssh/id_ed25519_<this-machine>
    ProxyCommand /opt/homebrew/bin/cloudflared access ssh --hostname %h
    ServerAliveInterval 30

An Access application in front of ssh-home.example.dev allows one email. So the first ssh home opens a browser login with a code sent to that email, and only then does the SSH key check happen. Two checks before a shell.

Joining the running agents

herdr keeps a server running on the home laptop. Its sessions, and the agents in its panes, keep running whether anyone is attached or not. Attaching adds another view of the same panes.

herdr can attach over SSH by itself:

herdr --remote home-ts                     # the default session
herdr --remote home-ts --session agents

The shortcut for that is hr-home. Detach with Ctrl+B, then Q.

A few rules I keep:

The agent in a pane is the same process. I type into its pane. I never start omp --resume on a conversation that is already open in a pane, because that runs a second process on the same chat.
Closing SSH only closes my view. The agents keep running.
A smaller terminal resizes the shared panes while it's attached. They go back when it detaches.

A remote shell should look remote

So a remote shell never looks like a local one, ssh and herdr --remote now tint the Ghostty background and set a REMOTE: <host> title, and reset both when I leave. The core is small:

_remote_tint_run() {
  local label color
  label=$(_remote_tint_label "$1")   # me@home-ts.example.dev -> home
  shift
  # Only for an interactive shell in Ghostty, with a tty on stdout.
  if [[ ! -o interactive || ! -t 1 ]] \
    || [[ $TERM != xterm-ghostty && -z $GHOSTTY_RESOURCES_DIR ]]; then
    "$@"; return $?
  fi
  color=${REMOTE_TINT_COLORS[$label]:-$REMOTE_TINT_DEFAULT}
  local rc=0
  {
    printf '\e]11;%s\a\e]2;REMOTE: %s\a' "$color" "$label" >/dev/tty
    "$@"; rc=$?
  } always {
    printf '\e]111\a' >/dev/tty    # back to the theme background
  }
  return $rc
}

The escape codes go to /dev/tty, so piped output stays clean. The always block resets the color even when the command fails.

The wrapper around ssh is most of the file. It reads the arguments to find the host, and skips the tint when there is no interactive shell to tint: ssh home uptime, ssh -N, ssh -T. -p 22 takes the next word and -p22 doesn't, so it has to know which options take a value.

The color is deep purple. Inside herdr, it shows only where herdr doesn't paint its own panel colors.

Rules for a laptop that holds work credentials

Phone control of agents is a new way into the work laptop. These are the rules I follow for it:

Device lock on in the phone app.
My own phone is the only controller.
If the phone is lost: revoke it in the app, and run stable-teardown on the work laptop.
The work laptop accepts no incoming connections: Remote Login off, Shields Up on, and the Tailscale policy denies it.
Tailscale on the work laptop is a personal network, signed in with a personal identity, as an outgoing client only. No exit node and no subnet routes on it.
cert.pem, tunnel tokens, and pairing QRs are passwords. They never go into dotfiles, a chat, or a screenshot.

Versions

What runs today:

Tool	Version
herdr	0.9.5
Herdr.app	20261013.1
herdr-mobile-relay	commit `6211568`
cloudflared	2026.10.0
Tailscale	1.102.4

Try it

The companion folder has the remote tint as a standalone zsh file, with tests, and the Tailscale policy from this post. The tests run an interactive zsh in a pseudo-terminal with fake ssh and herdr, so they need no Ghostty and no hosts. They check when the tint should happen and when it shouldn't, the host label, custom colors, and that the color resets when ssh fails.

cd 03-mobile-relay
make test

golem-notes-examples/03-mobile-relay

How do you reach your agents when you're not at the laptop they run on? Leave a comment.

This is part 3 of my series on running a real agentic dev setup. I publish each part first on Golem Notes, with the full write-up and what's coming next. Subscribe there to get the next one in your inbox: Golem Notes

Close the laptop, the agent keeps working

Aviv Laufer — Thu, 15 Oct 2026 13:01:37 +0000

Part 2 of My Agentic Setup. Start from part 1

When an agent runs on my laptop, it stops when I close the laptop. That is fine for a five minute task. It is not fine for an audit that takes an hour, or a crew of agents working through a backlog.

So my long agent work runs on a cloud VM, inside tmux. The laptop is only a window into it.

The whole thing is one command:

agent-session.sh my-vm --gcloud

I'm on the VM. I start omp, give it work, and close the laptop. Tomorrow I run the same command, from the same laptop or the other one, and I'm back in the same place. The agent kept going while I was away.

The idea is simple: the agent runs on the VM inside tmux, and the laptop is only a window, so one command starts the work or brings me back to it from any machine.

Getting there was less simple. Here is what broke first.

What broke

The VM was too small

My first VM was a 1 GB e2-micro. omp got killed by the OOM killer while it was generating its shell completions. Not while running an agent, just while setting up the shell.

Small doesn't mean slow here. It means broken. I moved to a larger VM, and now the troubleshooting table in my docs has this line:

a tool is killed with exit 137    out of memory; check free -h, resize the VM

The login never finished

Every agent CLI logs in on each machine separately. My laptop's logins don't carry over to the VM, and I don't want them to.

claude login opens a browser flow and then waits for the callback on http://localhost:54545/callback. On the VM, that is the VM's localhost. The browser is on my laptop. It authorizes, redirects to port 54545 on the laptop, finds nothing there, and the login never completes. The browser just spins.

The fix is to forward the callback ports back over ssh. The script has a flag for it:

# Ports the agent CLIs listen on for their OAuth callback. Forwarded so the
# browser on this laptop can reach a login running on the VM.
AUTH_PORTS="54545 54546 8976"

if [ "$FORWARD_AUTH" -eq 1 ]; then
  for port in $AUTH_PORTS; do
    forward_args+=(-L "${port}:localhost:${port}")
  done
fi

So the first time on a new VM I connect with --forward-auth, then run claude login and cursor-agent login inside the session. When a tool has a device code flow, like gh auth login --web, I use that instead. It needs no tunnel at all.

`Unknown scope: use`

Even with the tunnel, a login can fail with Unknown scope: use.

The cause: the login URL was in a boxed TUI panel. The panel wraps the long URL, and copying the visible lines cuts off the end of the scope list. The browser gets a broken URL.

The fix: copy the link from a plain, wide terminal. Or send the output to a file and take the URL from there:

claude login 2>&1 | tee /tmp/login.txt

Quoting in `--run`

I wanted to start a job without attaching first:

agent-session.sh my-vm --gcloud --run 'omp "audit the auth module and report back"'

That command goes through three layers: ssh, the shell on the VM, and tmux. Each one has its own quoting rules. A command with quotes inside quotes doesn't survive all three.

The fix is to not quote it at all. The script base64-encodes the command on the laptop and decodes it on the VM:

# The command crosses ssh, the remote shell and tmux, each with its own
# quoting. base64 is the one encoding that survives all three unchanged.
encoded="$(printf '%s' "$RUN" | base64 | tr -d '\n')"
remote="tmux new-session -A -d -s ${session_q}; \
        tmux new-window -t ${session_q} \"sh -lc 'eval \\\"\\\$(printf %s ${encoded} | base64 -d)\\\"; exec \\\$SHELL -l'\"; \
        tmux attach -t ${session_q}"

It is not pretty, but base64 has only letters, digits, +, / and =, so none of the three layers has anything to escape.

The exec $SHELL -l at the end matters too. When the agent finishes, the window stays open with a shell in it, so the final answer is still on screen when I come back.

Running the script on the VM itself

The script is meant to run on the laptop. Run it on the VM by mistake, and gcloud compute ssh tries to ssh from the VM to itself. It generates a new SSH key there and fails on permissions the VM's own service account doesn't have.

The fix is a hostname check. If I'm already on the target machine, the script skips ssh and just attaches:

if [ "$(hostname -s 2>/dev/null)" = "${HOST%%.*}" ]; then
  exec tmux new-session -A -s "$SESSION"
fi

Now the same command does the right thing from both places.

`command not found: omp`

This one happens on a fresh VM. You connect, tmux starts, then you install the tools. Inside the session, omp is not found.

The tmux server started before the tools were installed, so it still has the old PATH, and every new window gets that old PATH too. Reconnecting doesn't help, because the server is still running.

tmux kill-server

Then connect again.

Smaller ones

Some issues came from setting up the VM, not from running agents on it:

A minimal Debian image has no make, and my setup runs make. It is in the first install step now.
Debian ships Node 18. Some of my npm tools need 22. Linux takes Node from mise instead of apt.
The ssh client forwards a locale the VM didn't generate, which prints a setlocale warning on every login. It is harmless. Installing the locale on the VM, or not forwarding it, makes it go away.

The setup

The VM comes from the same dotfiles

The VM is not special. It gets the same dotfiles as my laptops, with a Linux layer on top. This is the whole OS profile:

# profiles/os/linux.toml
# Linux defaults, targeting headless Debian and Ubuntu LTS hosts.

capabilities = ["cli", "linux"]

[shell]
ssh_use_keychain = false

[packages]
packs = ["base", "agents", "formal", "linux"]

cli without desktop keeps desktop applications off a headless machine. ssh_use_keychain = false matters because UseKeychain is a macOS-only SSH option, and on Linux it makes ssh reject the whole config file.

The agents pack

The agent tools come from a package pack. On macOS most of them are Homebrew formulas. On Linux most don't have an apt package, so each row has an upstream installer:

[[package]]
name = "can1357/tap/omp"
provider = { macos = "brew", linux = "upstream" }
binary = "omp"
install = { linux = "...curl the release binary into ~/.local/bin..." }

[[package]]
name = "claude-code"
provider = { macos = "upstream", linux = "upstream" }
install = "curl -fsSL https://claude.ai/install.sh | bash"
binary = "claude"

[[package]]
name = "node"
provider = { macos = "brew", linux = "upstream" }
min_major = 22
install = { linux = "mise use -g node@lts" }

The bootstrap script shows each upstream command and asks before running it. It also exits non-zero until everything is installed, so a half-installed VM doesn't look finished.

What runs on the VM today:

Tool	What it does there	Installed on Linux by
tmux	keeps sessions alive	apt
omp	my main agent	release binary
Claude Code	crew agent	its install script
Cursor agent	crew agent	its install script
Firstmate	runs the crew	git clone
worktrunk	worktrees	release tarball
Node	for the npm tools	mise

New machine, in order

Setting up a VM follows the same eight steps as a laptop:

Base tools: git, ssh, make, Python, chezmoi
A new SSH key for this machine, added to GitHub
Clone the dotfiles
A dry run into a fake home
Declare the machine in a profile
Install the software
Install the configuration
Log in to each tool

Configuration and software never mix. Step 7 installs no packages, and step 6 changes no configuration. Logins are always last, and always per machine. Nothing is copied from another machine.

How the script works

One tmux command does most of the work

The whole idea is one tmux flag:

remote="tmux new-session -A -s $(printf %q "$SESSION")"
exec ssh -t "$HOST" "$remote"

new-session -A attaches to the session if it exists and creates it if it doesn't. So the first connection and every connection after it are the same command.

ssh is only the transport. -t gives it a terminal, because tmux refuses to attach without one.

On GCP the script uses gcloud compute ssh with --tunnel-through-iap. My VM has no external IP, so IAP is how I reach it.

Less typing

The machine, project and zone are the same every time, so I set them once:

# ~/.zshrc.local
export AGENT_SESSION_HOST=my-vm
export AGENT_SESSION_PROJECT=my-project
export AGENT_SESSION_ZONE=my-zone

Now it is:

agent-session.sh --gcloud            # connect
agent-session.sh --gcloud --list     # what is running

--list is my dashboard:

billing: 1 windows (created Mon Sep 14 09:57:17 2026)
payments: 1 windows (created Mon Sep 14 09:56:16 2026)

Sessions, windows and tabs

These three are easy to mix up, so here is how I use each one:

A tmux window (Ctrl-b c, or fm <project>): jobs I want to watch together. Ctrl-b w picks one.
A tmux session (--session <name>): jobs I want kept apart, each one reattachable on its own.
A Ghostty tab: only a way to see two sessions at the same time. Closing it changes nothing on the VM.

One thing surprises people. Two Ghostty tabs attached to the same session show the same screen, live, with both cursors. That is nice for watching a long run on a second monitor, and useless for doing two things at once. Different work needs --session, not another tab.

What survives

Closing the laptop, losing wifi, disconnecting: keeps running.
Connecting from the other laptop: same sessions, same screens.
Two laptops connected at once: both see the same screen.
Rebooting the VM: the agents stop.

The VM is always on, so the last one almost never happens. I have tmux-resurrect and tmux-continuum installed, so if the VM does reboot, the sessions and windows come back. An agent that was in the middle of its work doesn't.

Where I am now

These days I mostly use herdr for this. It does the same job as tmux on the VM, with its own way of saving machines and reconnecting. Use one or the other, not both: herdr inside tmux makes their keyboard shortcuts fight.

The pattern is the same either way. The agent runs on a machine that stays on, and the laptop is only a window.

Try it

The companion repo has a sanitized copy of agent-session.sh and a test suite. The tests run tmux on a private socket with fake ssh and gcloud, so they don't need a VM and don't touch your own tmux server. They check the --run quoting with quotes, $ and backticks, the local attach, --forward-auth and the IAP flags.

cd 02-remote-agents
make test

golem-notes-examples/02-remote-agents

Where do your long agent runs live: your laptop, a VM, something else? Leave a comment.

This is part 2 of my series on running a real agentic dev setup. I publish each part first on Golem Notes, with the full write-up and what's coming next. Subscribe there to get the next one in your inbox: Golem Notes

I talk to one agent. It runs the others.

Aviv Laufer — Mon, 05 Oct 2026 12:49:31 +0000

The map of my setup: OMP in the middle, the tools it dispatches, and the 13 parts coming next.

Most of my coding day happens in one terminal pane. I type into OMP, and OMP does the rest.

It picks a model for each job. Planning goes to Opus. Normal turns go to Sonnet. Reviews go to a GPT model, so the reviewer is never the same model that wrote the code. When the work is big, OMP hands it to a fleet: Firstmate spawns crew agents, each one in its own worktree, and most of the time the crew is working and I'm not.

I use several coding agents, but I don't configure them separately. One repo decides which rules, skills, identities and models every agent gets, on every machine.

That repo is my dotfiles. It started in December 2016 with a tmux and vim config. In the last three months, since agents took over my workflow, it got almost as many commits as in the nine years before.

This post is the map: every tool, how they connect, what broke when I first wired them together, and the fix.

The map

                         me
                          |
                          v
   +---------------------------------------------+
   |  OMP  (my main tool, one model per role)    |
   +---------------------------------------------+
            |                        |
            | talks to models        | fm <project>
            | directly               v
            |              +----------------------+
            |              |  Firstmate           |
            |              |  (first mate on OMP) |
            |              +----------------------+
            |                 |   dispatch rules
            v                 v
   Anthropic, Cursor,     crew: OMP, Claude Code,
   OpenAI, local model    Codex, Grok
                              |
                              v
                     treehouse worktrees
                     (one per task, pooled)

   herdr on the laptop, tmux on the VM: every agent gets a pane
   dotfiles: renders the config for all of the above

It runs on two laptops and a cloud VM. My work laptop gets the company rules: our skills, our ticket conventions, our compliance rules. My personal laptop should not see any of that, and the two use different model accounts.

I'll go through each box below. First, the part that went wrong.

What broke

OMP is where I type, but it is not the only agent that runs. Firstmate starts Claude Code, Codex or Grok as crew, and Cursor agent is there too. Each of these tools reads its instructions from a different place:

~/.claude/CLAUDE.md
~/.codex/AGENTS.md
~/.pi/agent/AGENTS.md
~/.agents/AGENTS.md
~/.gemini/GEMINI.md
~/.config/opencode/AGENTS.md
~/.copilot/copilot-instructions.md

Seven files that should say the same thing. Skills have the same problem: each tool has its own skills folder.

Agents read their instructions in every session, so when those instructions drift, the agents drift with them. Nothing warns you.

Two things were wrong.

First, the files had drifted. My ~/.codex/AGENTS.md was a copy I'd made by hand in May, and it was out of date. Pi, another agent I had installed, saw only 3 of my 23 skills. Each tool was working with a different set of rules, and I had assumed they were all the same.

Second, the instructions were too long. The global file had grown to 465 lines, about 21 KB or 5,300 tokens. It loads on every turn, in Claude Code and each of its subagents, in OMP, Codex, Pi, Gemini, OpenCode and Copilot. So every one of those paid for all 465 lines, every time.

The fix

One source, compiled per machine

I split the instructions into small fragments, one topic per file:

agents/fragments/
  00-header.md
  05-no-emojis.md
  10-voice.md
  20-workflow.md
  30-git-conventions.md
  32-worktrees-stacking.md
  35-pull-requests.md
  45-core-principles.md
  ...
  50-work-skills.md     # work only
  55-compliance.md      # work only

Each machine profile is a plain list of the fragments it gets. The personal profile leaves out the work-only ones:

# agents/machines/personal.txt
00-header.md
05-no-emojis.md
20-workflow.md
35-pull-requests.md
32-worktrees-stacking.md
45-core-principles.md
30-git-conventions.md
40-languages.md
10-voice.md

make build puts them together into one flat AGENTS.md, with a marker before each fragment so I can see where a rule came from:

while IFS= read -r name; do
  case "$name" in ''|'#'*) continue ;; esac
  printf '<!-- Source: fragments/%s -->\n' "$name"
  cat "fragments/$name"
done < machines/$(PROFILE).txt

Why flat and not includes? Codex, Pi and Cursor don't expand any include syntax. So the modular part lives in the source, and every tool gets one plain file.

make deploy then symlinks that one file into all seven paths. There are no copies left to go stale. When I edit a fragment and run make build, every tool picks it up in its next session.

A check that blocks drift

A pre-commit hook runs make check. It builds again into a temp folder and diffs the result against the built file. If I edit a fragment and forget to build, the commit fails:

check: build/personal/AGENTS.md is out of date. Run: make -C agents build

One skills folder

Skills go in one place, ~/.agents/skills/. When I checked in July, Codex, Cursor, OpenCode, Gemini and Copilot all read that folder directly. Claude Code doesn't, so make skills-sync adds a symlink per skill into ~/.claude/skills/. It does the same for Pi's own folder, which is where the 3-of-23 problem was.

It never overwrites a real file. A skill installed some other way gets skipped with a warning, not deleted.

Then I could cut it in half

With one file, I could finally see everything in one place. So I cut it. 465 lines down to 215. About 5,300 tokens down to 2,500.

The biggest cut was the pull request procedure. I moved it, as is, into a skill. It loads only when an agent works on a PR. The fragment kept only the hard rules: draft only, no merge and no deploy without my approval. The rest of the fragments I trimmed down to the rules, without the explanations.

With seven copies, I never cut anything. I didn't know which copy was the real one, so I only added. With one source, cutting is safe.

Now I split instructions into two kinds. Rules every agent needs on every turn go in the global file, and I keep it short. Procedures for one kind of task go in a skill. An agent renaming a variable doesn't need my PR procedure, and it shouldn't pay for it in tokens.

The rest of the map

With that in place, here is what each box in the diagram does.

OMP

OMP (Oh My Pi) is a coding agent that talks to the model APIs directly. I log in to Anthropic, Cursor and OpenAI once, and OMP routes each kind of work to a model through roles:

modelRoles:
  default: cursor/claude-sonnet-5-5:medium
  plan:    cursor/claude-opus-5-5:medium
  task:    cursor/claude-sonnet-5-5:medium
  slow:    cursor/composer-2.5:high
  smol:    cursor/gpt-5.6-luna:medium
  commit:  cursor/gpt-5.6-luna:low
  tiny:    local/lfm2.5-230m

The reviewer is set in a separate block of the same config file:

task:
  agentModelOverrides:
    reviewer: cursor/gpt-5.6-terra:high

That's my personal laptop. It only has Claude and Cursor accounts, so almost everything goes through Cursor. The work laptop uses the same roles with different providers, and dotfiles picks the right ones per machine.

Model names change every few months, so here is the current table. I'll keep it up to date. The pattern is what matters.

Role	What it does	Current model
default	normal turns	Claude Sonnet 5.5
plan	planning	Claude Opus 5.5
task	subagent work	Claude Sonnet 5.5
slow	hard fixes	Composer 2.5
reviewer	code review, different vendor than the author	GPT-5.6 Terra
smol	cheap fan-out	GPT-5.6 Luna
commit	commit messages	GPT-5.6 Luna, low effort
tiny	throwaway calls	a 230M local model
judge	"is this actually done?"	a small model on Cloudflare Workers AI

Firstmate

Firstmate runs a fleet of agents. I'm the captain. The first mate is an OMP session that takes my ask, writes a brief and starts crew agents to do the work. fm <project> opens it for one project, and each project gets its own home, so backlogs and running tasks never mix.

The crew is OMP by default, but a few dispatch rules send work to other tools:

{
  "when": "The task is a trivial mechanical edit: rote rename, formatting sweep, targeted typo fix, dependency bump, or gathering files.",
  "use": { "harness": "claude", "model": "haiku", "effort": "low" }
},
{
  "when": "The task is a scout: investigate, audit, trace a bug, or produce a standalone report without changing code.",
  "use": { "harness": "omp", "effort": "high" }
}

My preferences for the first mate live in a markdown file it reads at the start of every session. A few lines from it:

- Never use em dashes in PR titles, PR bodies, commit messages, or comments.
- Every PR any worker opens is created in draft mode, no exceptions.
- Escalate to me on any change touching auth, tenancy boundaries, data
  retention, or migration ordering, even when the tests are green.
- Scout tasks end in a report, never a code change.

Worktrees: two tools on purpose

When I start an agent myself, I use worktrunk (wt). One alias creates a branch, a worktree and an agent session:

worktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"

[aliases]
cc  = "wt switch --create {{ branch }} -x claude"
cur = "wt switch --create {{ branch }} -x wt-agent -- cursor-agent"

When Firstmate starts a crew agent, it uses treehouse. Treehouse keeps a pool of worktrees per repo and leases one out per task (treehouse get --lease, then treehouse return). Two crew agents on the same repo get slot 1 and slot 2 and never collide. Most of the worktrees on my machine come from treehouse, because most of the time the crew is the one working.

herdr and tmux

herdr is the terminal multiplexer on my laptops. Unlike tmux, it knows which pane is an agent and whether that agent is working, blocked, done or idle:

[ui]
agent_panel_sort = "spaces"     # one space per repo/worktree
status_indicators = "symbols"   # blocked/working/done/idle
show_agent_labels_on_pane_borders = true

With several crew agents running, ctrl+alt+up and ctrl+alt+down jump between them. On the cloud VM I use plain tmux, so agents keep running after I close the laptop.

Dotfiles

Everything above is rendered from the dotfiles repo, in layers:

base < os < organization < machine < local.toml

Each layer only overrides the values it names. The work laptop declares the work organization and the personal one. The personal laptop declares only personal. A repo outside every declared root has no git identity at all, so a commit fails instead of going out under the wrong name.

Try it

The companion repo has a small working version of the fragments build: four fragments (one of them work-only), two profiles, a pre-commit hook, and the Makefile with build, check and deploy. By default it deploys into a fake home folder, so it never touches your real config. When you point it at your real home, it skips any real file in the way instead of overwriting it.

make build && make deploy
ls -la fake-home/.codex   # AGENTS.md -> .../build/personal/AGENTS.md

golem-notes-examples/01-the-map

What's coming

One part every two weeks:

The map (this post)
Close the laptop, the agent keeps working: agents on a cloud VM with tmux
My agents on two laptops, controlled from one phone app
Every PR gets an agent review before a human sees it
Captain, first mate, crew: orchestrating a fleet of agents
Nine roles, not one model
Right model for the task: dispatch rules and cheaper subagents
When the credits run out: fallback chains
A cheap judge for "is this actually done?"
Teaching agents how I work: my skills library
Dotfiles an agent can't break
One laptop, many companies: identities and secrets
Testing your dotfiles like production code
What I'd do differently

If you run more than one agent tool, I'd like to know how you keep their rules in sync. Leave a comment.

This is part 1 of my series on running a real agentic dev setup. I publish each part first on Golem Notes, with the full write-up and what's coming next. Subscribe there to get the next one in your inbox: https://golemnotes.substack.com/p/i-talk-to-one-agent-it-runs-the-others?utm_source=devto&utm_medium=social&utm_campaign=agentic-setup-01

DEV Community: Aviv Laufer

Every PR gets an agent review before a human sees it

What broke

The reviewer model didn't reach the reviewers

# is a glob in my shell

herdr's split ratio is the other way around

A running server that looked down

The setup

One PR: review-pr

Many PRs: one scout each

The charter

Five passes, one of them for the spec

The reviewer is on a different vendor

When my own agents open the PR

A budget for review rounds

Try it

My agents on two laptops, controlled from one phone app

What I use

What broke

I couldn't use a domain I already had

The second laptop made a second app

The phone app lives on one laptop

Closing the lid still puts the Mac to sleep

A warning about pairing on iOS

The setup

One relay per laptop

Devices and roles

The phone and Firstmate

SSH from the work laptop

Tailscale: three locks on the work laptop

Cloudflare Access: no VPN on the work laptop

Joining the running agents

A remote shell should look remote

Rules for a laptop that holds work credentials

Versions

Try it

Close the laptop, the agent keeps working

What broke

The VM was too small

The login never finished

Unknown scope: use

Quoting in --run

Running the script on the VM itself

command not found: omp

Smaller ones

The setup

The VM comes from the same dotfiles

The agents pack

New machine, in order

How the script works

One tmux command does most of the work

Less typing

Sessions, windows and tabs

What survives

Where I am now

Try it

I talk to one agent. It runs the others.

The map

What broke

The fix

One source, compiled per machine

A check that blocks drift

One skills folder

Then I could cut it in half

The rest of the map

OMP

Firstmate

Worktrees: two tools on purpose

herdr and tmux

Dotfiles

Try it

What's coming

`#` is a glob in my shell

`Unknown scope: use`

Quoting in `--run`

`command not found: omp`