Install with an agent

Let the coding agent you already use set herdr-link up. Tell it:

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

It checks your computer, installs what's missing (asking first), walks you through the bot, and checks that everything works at the end. The bot token never goes through the agent: you type it into herdr-link yourself. The rest of this page is written for the agent.

For the agent

You are installing herdr-link for the person you work with. herdr-link connects herdr (a terminal app where coding agents run in tabs) to Discord or Telegram: every herdr tab becomes a chat thread, agent replies and permission prompts reach the owner's phone, and the owner answers from there. Full human guide: https://thl-ai.github.io/herdr-link/docs/getting-started.html

Rules

• Never ask for, read, print or store a bot token. Whoever sees the token controls the bot, and the bot can type into the owner's terminals. The owner types it into herdr-link init or into ~/.config/herdr-link/.env themselves. Don't cat that file.
• Ask before installing anything besides the npm package (herdr, Node).
• herdr-link init is interactive (a hidden token prompt, yes/no questions, "press Enter once the bot is on your server"). Don't run it from your shell tool: ask the owner to run it in a terminal of their own (a new herdr tab is fine) and to tell you when it's done.
• herdr-link doctor only looks, so run it freely. Its --fix asks questions (interactive again), and --fix --yes installs and starts things without asking: don't run either. Apply the fix each ✗ line names yourself, one at a time.
• Give the owner manual steps as a numbered list, one action per step.
• Talk to the owner in their language; the commands stay as they are.

1. Check the computer

uname -s              # Darwin or Linux; anything else: stop, it isn't supported
node --version        # needs v24 or newer
hc --version          # herdr-core
command -v herdr-app  # the herdr app

• Node older than 24: tell the owner; if they use nvm, nvm install 24 && nvm alias default 24 (ask first).
• No herdr: ask, then run herdr's official installers: curl -fsSL https://releases.herdr.dev/core/install.sh | sh (core) and curl -fsSL https://releases.herdr.dev/app/install.sh | sh (app). The owner opens the herdr app once afterwards.
• herdr-core installed but not running (hc server status says so): hc server start.

2. Install the package

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

3. Pick a chat app

Ask the owner: Discord or Telegram? (Both is fine: set up Discord first, then add Telegram.) A new, empty server or group of their own is best: access to it means running code on their computer.

4a. Discord

Give the owner these steps (Discord doesn't let programs create bots):

1. Open https://discord.com/developers/applications → New Application, name it (say herdr), accept the terms.
2. Installation → Install Link → None → Save Changes.
3. Bot: turn Public Bot off, leave Requires OAuth2 Code Grant off, click Reset Token and copy the token (Discord shows it once). Don't paste it to me.
4. In a terminal of your own, run herdr-link init, paste the token when it asks, and answer its questions (Enter takes the default). When it prints an invite link, open it, pick your server, Authorize, then press Enter.
5. Tell me when it's finished.

init turns on the intent the bot needs, finds the owner and the server, picks up the agents on PATH, writes the config and the .env, installs the agent hooks and the background service. Then go to step 5.

4b. Telegram

init only does Discord; for Telegram you write the config.

1. Prepare the secrets file (no token in it yet):

   mkdir -p ~/.config/herdr-link && touch ~/.config/herdr-link/.env && chmod 600 ~/.config/herdr-link/.env
   

2. Give the owner these steps:

   1. In Telegram, talk to @BotFather: /newbot, pick a name and a username ending in bot, copy the token. Don't paste it to me.
   2. Open ~/.config/herdr-link/.env and add a line TELEGRAM_TOKEN=<the token>.
   3. Create a group and turn on Topics in its settings.
   4. Add the bot to the group as an admin with Manage topics.
   5. In BotFather: /mybots → your bot → Bot Settings → Allow Groups? → turn groups off (it stays in your group).
   6. Write any message in the group, then open your private chat with the bot and press Start.
   7. Tell me when it's done.

3. Run herdr-link telegram. It checks the group (Topics on, the bot an admin) and prints an [adapters.telegram] section with the group and owner ids. If it reports a problem, give the owner the fix it names.

4. Write ~/.config/herdr-link/config.toml: start from the example in the package ("$(npm root -g)/@thl-ai/herdr-link/config.example.toml"), replace the [adapters.discord] section with the printed Telegram section, and keep only the agents that are on PATH (claude, grok; the shell agent always stays). If the owner already has a config (Discord), add the Telegram section to it instead.

5. Install the rest:

   herdr-link hooks install
   herdr-link service install
   

5. The bar in the Herdr window

If the herdr app is installed:

herdr-link mod install

It shows a small bar in the Herdr window: whether the link works, and a switch between at the desk (messages arrive without a push) and away.

6. Check

herdr-link doctor
herdr-link status

Every line of doctor should be ✓, and status should show the chat app connected. A ✗ line says what to run (herdr-link hooks install, herdr-link service install, hc server start, herdr-link init…); run it (init the owner runs, see the rules) and check again. If editing ~/.claude/settings.json for the hooks is refused by your permissions, ask the owner to run herdr-link hooks install themselves.

7. Tell the owner what's next

1. Restart running agent sessions (yours too): agents read their hooks when they start.
2. Discord: right-click each of the bot's categories → Notification Settings → All Messages, so the phone pings. Server Settings → Integrations → the bot → allow its commands only for themselves.
3. Install the chat app on the phone and sign in.
4. Try it: write in a tab's channel or topic; 👀 means it reached the agent, and the reply arrives there when the agent is done.

More: https://thl-ai.github.io/herdr-link/docs/getting-started.html (Try it, At the computer, Keeping it running) and https://thl-ai.github.io/herdr-link/docs/troubleshooting.html