Moving from Herdr TUI to the Herdr desktop app: what your agent should check

Herdr came onto the scene driving multi-agent orchestration as a new trend in development. Now Herdr has launched its desktop app, and it is clearly meant to be the replacement.

My agent said to wait. Let things stabilize and move once there is a more stable release. I did not agree. There is absolutely no reason to stay on Herdr TUI, the old version I was running through Warp. The desktop app is the way of the future.

Migrating is fairly simple. It gets more complicated if you have a thorough configuration. These are the lessons I learned, written as things you can have your agent check for when it makes this migration.

Each item is the check, then why it matters. No fixes. Your agent knows your setup and can work out its own.

Before you start

• Check for uncommitted work in the repo that holds your agent config. Cleaning up on top of it mixes your changes with someone else’s and leaves you no clean undo.

Leftovers that keep steering your agents

• Check your agent CLIs’ hook configs (Claude Code, Codex, Cursor and the rest) for hooks Herdr TUI installed. They can still fire at every session start.
• Check your skills folders for a skill about Herdr TUI. Agents load skills whether or not the tool is still there.
• Check every instruction file (CLAUDE.md, AGENTS.md, skills) for old commands, old environment variables and old script names. One stale line is enough for an agent to take the old path.
• Check your permission allow-lists for commands that no longer exist.
• Check for files marked “deprecated” instead of removed. Agents read them and follow them anyway. A missing file makes an agent ask. An old file makes it obey.
• Check your agent CLIs for hooks that talk to desktop apps. On a Mac nobody sits at, those hooks are what set off macOS permission prompts.
• Check every file type your agents read, not just Markdown. An HTML architecture page kept describing the old setup after every Markdown file was clean.

Your own customizations

This is the part a stock migration guide never covers.

• Check for the helper scripts you built around Herdr TUI. Seat launchers, repair scripts, watchdogs, health checks. Look in your PATH on every machine, including copies that are not links to your shared version.
• Check for background jobs you set up (LaunchAgents, cron, scheduled tasks) that call the old CLI or your old helpers. Disabled ones still sit on disk, and an agent that finds one reads it as an instruction.
• Check your shared seat or crew config for comments and sections that only made sense for the old tool, and check the scripts that read it.
• Check for backup copies of old scripts and configs, the .bak, .old and “stale” files. Agents search your folders and find them.
• Check the documentation you wrote about your old setup. Architecture notes, runbooks, decision records. An agent treats a well-written old runbook as current.
• Check the updater you built. A custom “update everything” script may still update, restart or verify the old tool along with your CLIs.

The core and the login session

• Check that agent terminals still have the login session after a core update. Watch for gh, ssh, Keychain, DNS or clipboard failing inside agent terminals while your own shell works. It looks like a network problem and it is not.
• Check the processes that hold the terminals, not just the core. A healthy core does not mean healthy terminals.
• Check how the core was started on each machine. Started from a remote session, it may not reach that machine’s credentials.
• Check one machine after an update before you update the rest. Test an existing terminal and a brand-new one.
• Check whether “Restart” on an app update also updates the core. It does. One click is two updates, so it needs the same one-machine-first care.
• Check which process your running agents live in after an update. Running agents stay with the pre-update process until their tab closes. “Updated” does not mean every agent is on the new version.
• Check from inside an agent terminal, not your own shell. Your shell can be fine when every agent’s is not.

Multiple machines

• Check every machine for local copies of scripts and seat config that have drifted from the shared source.
• Check the old config folder for the old tool’s session files, settings and sockets. Before clearing it, check whether anything in the new setup still reads from that same folder.
• Check every machine the same way. Differences hide on the machine you did not look at, especially one that was offline when the cleanup ran.
• Check headless machines for permission prompts after an update. The updated core can look like a new app to macOS. Privacy prompts wait there with nobody to click them.

Spaces, tabs and restarts

• Check how your scripts stop an agent. Ending the terminal can close the tab and lose its name.
• Check where restarts relaunch agents after you rename or move a project folder. The folder an agent started in, and the folder its space was created in, may no longer exist.
• Check whether a resume still finds a conversation after a folder rename. Conversations are filed under the old folder name.
• Check that every running agent was restarted after the cleanup. Old instructions stay in its context until it is.

Three buttons worth building once you are on the desktop app

The desktop app can carry your own sidebar buttons. These three made a crew a lot easier to run for me. They are ideas, not how-tos. Let your agent build them its own way.

• ⤓ Update. One click updates every tool the crew depends on at once: the agent CLIs, MCP servers, skills, anything else, on every machine in parallel. No more finding out a seat was on an old version.
• ☕ Wake. A fresh start for the whole crew. Bring the tools the seats actually use up to date, restart every seat so it reloads current instructions, and land each project on its lead tab. Useful after a reboot, an update or a change to your instructions.
• 💤 Sleep. Stop every agent and leave the tabs in place, so nothing runs or burns tokens while you are away. Wake brings it all back.

If you build these, check:

• Whether a busy agent should be skipped or stopped.
• Whether the button stops the terminal it is running in.
• Whether a restart lands in the folder the project lives in now.
• Whether a restart resumes the conversation or starts fresh, and which seats should resume. A lead’s conversation with you is worth keeping. Worker seats are better fresh.
• Whether a resume picks the right conversation. Several agents share one project folder, so “the latest conversation here” may be another agent’s.

The bottom line

The desktop app is the easy part. The work is everything you built around the old one, because that is what your agents still read. Give your agent this list, let it check every machine from inside an agent terminal, and restart the crew when it is done.