a sidecar for herdr

Your herdr agents, in your chat app.

Every herdr space becomes a private room, every tab a thread. Your agents' replies, "done" and "needs you" reach your phone; permission prompts come with Allow and Deny; a new thread opens a new tab. Discord and Telegram are built in, and any chat app plugs in as an adapter.

$ npm install -g @thl-ai/herdr-link

then herdr-link init: it asks for a bot token and sets up the rest.

Or let your coding agent do it. Tell it:

Read https://thl-ai.github.io/herdr-link/install.md and install herdr-link for me.

Get started GitHub

#✳️apiweb

you 9:41

run the tests and fix what fails

👀 1

herdr-link 9:42

🔐 Permission: approve Bash: pnpm test

AllowAllow alwaysDeny

herdr-link 9:47

Fixed the missing import in src/routes.ts. All 67 tests pass.

you 9:48

nice, commit it

👀 1

How it works

herdr-link runs next to herdr on your computer. herdr stays the source of truth; the chat app becomes a remote for it.

herdr

Spaces, tabs, agents

Claude Code, Grok or any program, each in its tab, reporting working, done or needs you.

⇄

herdr-link

Mirrors and routes

Keeps rooms and threads in step with herdr, types your messages into the right agent, brings their replies back through one shared hook.

⇄

your chat app

Rooms, threads, buttons

Push notifications, history and buttons from the app on your phone. Discord and Telegram built in.

From your phone

Everything you'd walk back to your desk for.

💬

Talk to an agent

Write in a tab's thread: it is typed into that tab's agent. Screenshots and files land beside it.

🔐

Approve from anywhere

Permission prompts arrive with Allow, Allow always and Deny, wired to each agent's real keys.

❓

Answer its questions

When the agent asks with a form, each question comes with its options as buttons, or write your own answer.

⏳

Watch long turns

A long turn keeps one message up to date: how long it has run and what the agent is doing now.

🖥

Quiet at your desk

A bar in the Herdr window shows the link is up; at the desk, messages arrive without a push.

🔔

Know when it's done

The agent's final answer, or "✅ Done" and "⚠️ Needs you", as messages your phone pings you for.

➕

Start new work

A new thread opens a new tab with the agent you pick; a task in your private chat with the bot starts one in any space.

📊

A control room

Your private chat with the bot keeps a live dashboard of every agent, plus /status, /screen and /space new.

🧭

Split tabs, many machines

Several panes in one tab, spaces on other herdr machines, several computers: each stays clear.

Bring your own chat app

Adapters are separate programs, in any language, speaking a small JSON-RPC protocol on stdin and stdout. The bridge does everything herdr-specific; an adapter only knows its platform. Discord and Telegram are two of them.

Rooms, threads, buttons: the adapter maps them to what its app has.
Capabilities: no buttons or no rooms? The bridge works around it.
A full spec: an OpenRPC schema, examples and a 50-line adapter to start from.

Writing an adapter →

// bridge → adapter
{"method": "message.post", "params": {
  "place": {"kind": "thread", "thread": "45"},
  "text": "🔐 Permission: approve Bash: pnpm test",
  "actions": [{"id": "prompt:3:allow", "label": "Allow"},
              {"id": "prompt:3:deny", "label": "Deny"}]}}

// adapter → bridge: the owner pressed Allow
{"method": "action.pressed", "params": {
  "place": {"kind": "thread", "thread": "45"},
  "message": "9001", "action": "prompt:3:allow"}}

Only you

Whoever can write in those threads can run code on your machine, so herdr-link is built for one owner.

Owner check on every message, reaction, button and command, not only chat permissions.
Private rooms only you and the bot can see; your other rooms on the same server are left alone.
Local hooks: agents talk to herdr-link over a unix socket only you can open.
Least privilege: each adapter sees only the secrets its config lists.