Herdr

Herdr lets you run and watch over several AI coding agents — like Claude Code, Codex, Droid and GitHub Copilot CLI — right on your own servers, from your phone, tablet or Mac. The agents do their work on the server; Caret is your window into them. You can see at a glance which one is waiting on you, which is still working, and which has finished — and step in the moment an agent needs an answer.

This feature is built on herdr, an open-source "agent multiplexer" that runs on your server — think of it as a tmux or zellij that understands agents. herdr runs the agents and keeps track of what each one is doing; Caret connects to it over your normal SSH connection and gives you a touch-friendly view. As always, there is no Caret cloud in between — the app talks straight to your server.

What you can do

  • Run several agents at once, each in its own workspace, tab or pane.
  • See every agent's live state in one list — blocked, working, done or idle — so nothing waits on you unnoticed.
  • Jump straight to the agent that needs you and type your answer or approval.
  • Walk away. The agents keep running on the server even after you close Caret or lose signal. Come back later and pick up exactly where they were.
  • Get notified when an agent becomes blocked or finishes.
  • Review what an agent changed without leaving the app, with a built-in diff viewer.
  • Show an agent a picture — snap or pick a photo, mark it up, and hand it over for the agent to read.

Before you start

Because the agents run on your server, a little one-time setup happens there. Caret points you through it:

  1. A server you can reach over SSH. Add it in Caret the usual way — host, port and username — and make sure it connects.

  2. herdr installed on that server. It is a single open-source binary. Sign in to the server — for example from Caret's own terminal — and install it with one command:

    curl -fsSL https://herdr.dev/install.sh | sh

    (Homebrew users can run brew install herdr instead.) You only do this once per server.

  3. At least one coding agent. Install an agent's command-line tool on the server — Claude Code, Codex, Droid, GitHub Copilot CLI and more are supported. Caret helps you get these set up. Each agent signs in to its own provider with your account or key (Anthropic for Claude Code, OpenAI for Codex, and so on) — that part is between you and that provider.

Starting your agents

  1. Connect to the server in Caret and open Herdr.
  2. Caret starts herdr on that server, or reconnects to one already running, and shows your workspaces.
  3. Open a workspace and launch an agent — for example, start Claude Code in a pane and give it a task the way you normally would.
  4. Add as many agents as you like, each in its own pane or workspace. They all run side by side.

Reading the agent list

The list shows each agent's state at a glance:

  • 🔴 Blocked — the agent needs your input or approval.
  • 🟡 Working — it is actively running.
  • 🔵 Done — it finished, and you have not looked yet.
  • 🟢 Idle — finished and seen.

A workspace takes on the most urgent state of the agents inside it, so you can scan the whole list and go straight to whatever is waiting on you:

Workspaces
──────────────────────────────────
▾ api-server              🔴 blocked
    claude code           🔴 blocked
    codex                 🟡 working
▾ web-frontend            🔵 done
    copilot cli           🔵 done
▾ infra                   🟢 idle
    droid                 🟢 idle

(An example layout — yours shows your own servers and agents.)

You always see each agent's real terminal, not a re-rendered copy, so what you read in Caret is exactly what the agent printed.

One inbox for every server

When you are running agents on more than one server, you should not have to open each server in turn to find the one waiting on you. The Herdr board gathers them all in one place — turn it on in Settings (on Mac it lives in the sidebar) and it rides along the top of your home screen.

It has two views:

  • Inbox groups every agent across every server by what it needs — blocked first, then working, done and idle — so whatever is waiting on you stays at the top. Tap an agent to expand its recent output, then reply, focus it, open it in the terminal or review its changes without leaving the list.
  • By server lays the same agents out under each server, and also shows where herdr is installed and running.

Caret refreshes the board in the background and can notify you the moment an agent becomes blocked or finishes — on Mac, even while the app is tucked away, as long as the menu bar is turned on.

Reviewing what an agent changed

Agents edit files, so Caret lets you read those edits before you trust them. Wherever you see View changes — on an agent, or from the terminal — Caret shows what changed in the working folder, the same view you would get from git:

  • Read it as a single unified list or side by side.
  • Syntax highlighting, line numbers, line wrapping and an adjustable font size, with a tap to expand the surrounding lines for more context.
  • Added, deleted and renamed files are labelled, and untracked new files, image changes and merge conflicts are each called out.

The viewer is read-only — a safe way to look. When you are happy with the work, commit or undo it back in the terminal the usual way.

Showing an agent a picture

Sometimes the quickest way to explain something to an agent — a screenshot of a broken screen, a diagram, an error photographed off another monitor — is to show it. The terminal's on-screen keyboard has a photo key for exactly that:

  1. Tap the photo key and choose Take Photo, Photo Library or Files.
  2. Mark it up if you like — circle the part that matters — then tap Upload.
  3. Caret saves the picture to a temporary folder on the server and drops its location into your prompt (for example [Image #1]), so an agent such as Claude Code can open and read it.

Your agents keep running when you leave

Because the agents live on the server, they do not stop when you put your phone away or the connection drops. Close Caret and come back later, switch from your phone to your Mac, or even reattach from a plain terminal on your computer with herdr — the agents are right where you left them, still working or still waiting. This is the same session persistence herdr gives any terminal.

Staying in control

The agents are powerful — they run real commands on a real server — so a few habits keep you safe:

  • They run as your logged-in user, over your normal SSH connection. An agent can only do what that account is allowed to do. Connect with a limited account when you want a tighter leash.
  • Read what an agent proposes before you approve it, especially anything that deletes, overwrites, installs or restarts. Most agents stop and ask before risky steps — that is exactly when an agent shows as 🔴 blocked, waiting for you. Use View changes to see exactly what it has edited.
  • Try it on a non-critical server first while you get a feel for how it works.
  • Keep a record. Turn on session recording and you will have a full log of a session, saved on your device.

Privacy

  • Caret connects straight to your server over SSH. There is no Caret cloud in between, and nothing about your agents or their work is sent to us.
  • herdr is open-source software running on your own server — not a Caret service.
  • Each coding agent talks to its own AI provider (for example Anthropic for Claude Code, or OpenAI for Codex) using the account or key you set up on the server, under that provider's privacy policy — never through us. Only run agents on work you are comfortable sharing with the provider behind them.

For how Caret itself handles your data, see the Privacy Policy.

When something goes wrong

  • Herdr won't open, or the list is empty — make sure herdr is installed on the server and that you can run herdr there over SSH. If the SSH connection itself is failing, fix that first; see Can't connect to a server.
  • An agent doesn't appear, or its state looks wrong — check that its command-line tool is actually installed and running on the server. herdr recognizes the common agents automatically; a tool it doesn't know still runs, but may not report a state.
  • An agent errors about its key, login or quota — that is between the agent and its provider. Check the agent's own setup on the server and your account standing with that provider.
  • The connection dropped mid-session — no harm done: the agents keep running on the server. Just reopen the server in Caret to reattach.

Still need help?

Tell us your device and its operating system version, the app version (Settings → About), and what you were doing when the problem happened.