{
  "markdown": "<div align=\"center\">\n\n# herdrchat\n\nThe chat client for hc ([herdr](https://herdr.dev)): see and answer every hc terminal from Feishu or Telegram.\n\n[English](README.md) · [简体中文](README.zh.md)\n\n[![npm](https://img.shields.io/npm/v/herdrchat.svg)](https://www.npmjs.com/package/herdrchat)\n[![CI](https://github.com/zhangxiangliang/herdrchat/actions/workflows/ci.yml/badge.svg)](https://github.com/zhangxiangliang/herdrchat/actions/workflows/ci.yml)\n[![license](https://img.shields.io/npm/l/herdrchat.svg)](https://github.com/zhangxiangliang/herdrchat/blob/main/LICENSE)\n\n</div>\n\n**herdr-app is hc's desktop and phone client; herdrchat is hc's chat client.**\n\n[herdr](https://herdr.dev) runs your coding agents (Claude Code, codex, pi, …) in\nterminals that stay alive: **hc** (herdr-core) keeps them running, and herdr-app shows\nthem in spaces and tabs. But to use herdr-app away from your desk, your phone has to\nreach the machine that runs hc, so you first need a VPN or a private network, and working\nwith an agent on a small phone screen is clumsy.\n\nherdrchat shows the same terminals in a chat app you already have on your phone. It connects out to Feishu or Telegram by\nitself, so there is nothing to set up on your network: no public IP, no VPN. Each\nherdr-app tab gets its own Feishu group, or a topic in your private chat with the\nTelegram bot. You read what the agent says while it works, tap buttons to answer its\nquestions, send and receive images, and see all terminals in one overview. A new group or\ntopic starts with the conversation so far. The groups and topics stay quiet: when an agent\nneeds you or is done, the overview comes again at the bottom of your direct chat with the\nbot and rings, what rang first (the room, a tap opens it, and what it said); the one before\nit stays as a one-line record that says \"handled\" once you have dealt with it (Feishu mutes\nits groups once you have sent `/auth` to the bot; Telegram does so right away).\n\nClaude Code, Codex, OpenCode and Pi are mirrored fully, their dialogs answered with buttons\n(Pi asks nothing itself; an extension's dialog is read off the screen).\nOther agents show their screen when you type to them, until herdrchat learns to read their\nconversations too. Under every post a small line says where it came from and how it stands: the\nharness, model and git branch, how full the context is, and the 5-hour and 7-day limits\n(`claude · claude-opus-5-5 · main · context 23% (234k) · 5-hour 2% · 7-day 57%`).\n\n## You need\n\n- **herdr**: herdrchat is built on it and does nothing without it. Install it from\n  [herdr.dev](https://herdr.dev) first (or let your coding agent do it with you:\n  `/herdrchat setup` offers to); its **hc** must run on this machine, with at least one\n  session.\n- **Node.js 20** or newer, on **macOS or Linux**.\n- **Feishu**: a Feishu team (not Lark) where you may create a custom app and publish it.\n  **Telegram**: a Telegram account. Use one app, or both at once.\n\nA few words used below: a **session** is one hc core (its terminals); a **space** and a\n**tab** are how herdr-app groups terminals; a **profile** is one herdrchat setup for one\nchat app (`default` unless you name another).\n\n## Install\n\n```bash\nnpm install -g herdrchat                    # the herdrchat command\nnpx skills add zhangxiangliang/herdrchat    # optional: the skill, for your coding agent\n```\n\nThe skill teaches your coding agent (Claude Code, Codex, …) to set herdrchat up and look\nafter it for you. When the `skills` tool asks Copy or Symlink, pick Symlink, so updates\nreach the agent.\n\n## Set up\n\n**With your agent:** ask it `/herdrchat setup`. It asks which chat app, then walks you\nthrough everything, clicking in the Feishu console for you when it can.\n\n**In the terminal** (the same steps, asked one by one; the agent can also click through\nthe Feishu console for you, with the [Ego Lite](https://lite.ego.app/) browser, which the\nterminal cannot; without Ego it tells you what to click):\n\n```bash\nherdrchat setup\n```\n\nIt asks which chat app, takes the bot's token (or the Feishu app's keys) and checks them\nat once, picks your hc sessions (`default` unless you say otherwise), starts the bot, and\nshows a 6-digit code: send it to the bot and it knows you are its owner. Last, it offers\nto keep it running as a service. No file to edit, no id to copy.\n\nMaking the Telegram bot or the Feishu app, and doing it all by editing the settings file\ninstead: the [guide](docs/guide.md#set-up-telegram).\n\n## Use\n\nIn your chat app: type in a terminal's group or topic to talk to it; tap a card's buttons\nto answer a question. In the direct chat with the bot: `/ls` for the overview, `/new` to\nstart a terminal, `/kill` to end one (or `/kill` in its own group or topic), `/usage` for\nevery account's limits.\n\n| Ask your agent | What it does |\n|---|---|\n| `/herdrchat setup` | Sets everything up with you: the Feishu app or the Telegram bot, the settings, the first start. |\n| `/herdrchat status` | Says whether it runs, and what is wrong if anything is. |\n| `/herdrchat fix` | Finds the cause of a problem and fixes it. |\n| `/herdrchat config` | Changes a setting: which terminals, which ones stay quiet, tags. |\n| `/herdrchat start`, `stop`, `install`, `logs`, `auth` | The same as the commands below, with checks first. |\n| `/herdrchat feishu <task>` | Does a task in the Feishu developer console (with the [Ego Lite](https://lite.ego.app/) browser, or step by step). |\n| `/herdrchat telegram <task>` | The Telegram bot, from @BotFather to the first topic. |\n\nOn the command line: `herdrchat setup`, `pair`, `init`, `start`, `stop`, `status`, `logs`, `install`,\n`uninstall`, `hooks`, `version`; `herdrchat` alone lists them. Add `--profile <name>` to run a\nsecond chat app beside the first.\n\nRecommended for Claude Code and Codex: `herdrchat hooks install` (it shows what it changes\nand asks first). It adds herdrchat's hook to their own settings, so what they ask you (a\npermission, Claude's questions and plans) comes to the chat in their own words and options,\nand your tap goes straight back to them, with no screen read. Without it, the dialog is\nread off the screen, as before. Codex asks you once to trust the new hook (`/hooks` in\nCodex), and while the hook waits Codex shows no prompt of its own: tap \"Answer in the\nterminal\" on the card to get it there. `herdrchat hooks uninstall` takes it out. Codex's\nquestions (in Plan mode, and the ones it asks without waiting) need no hook: they are read\nfrom its own log. For Pi it puts in a small Pi extension instead\n(`~/.pi/agent/extensions/herdrchat.js`), which tells herdrchat which session each pi\nwrites, so two pi in one folder each keep to their own room (in a pi that runs already:\n`/reload`).\n\n## Update\n\nWhen npm has a newer herdrchat, the bot says so once in your direct chat, with an\n**Update** button. Or in a terminal:\n\n```bash\nherdrchat update                 # the latest, with its skill and hook\nherdrchat update 1.10.2          # back to that version\n```\n\nEither way npm installs it, and every running bot starts again on it by itself within a\nminute (a few seconds without the bot), then says which version it runs now. herdrchat\nnever updates without your tap. A bot you run by hand (`herdrchat run`) says it needs a\nrestart instead.\n\nFrom a version before 1.11.0 (no `herdrchat update` yet), once by hand:\n`npm install -g herdrchat@latest`, then `herdrchat start` for each profile.\n\n## Where things are\n\nSettings in `~/.config/herdrchat/<profile>/config.env`, everything the bot writes in\n`~/.local/state/herdrchat/<profile>/`. Updating or reinstalling herdrchat never touches\nthem. `herdrchat status` prints both.\n\n## Privacy and safety\n\n- What your terminals show goes to Feishu's or Telegram's servers. Telegram bot chats are\n  not end-to-end encrypted.\n- Only the owner set in `config.env` can type into your terminals; everyone else is\n  ignored.\n- Keep the Feishu app secret or the Telegram bot token like a password: whoever has it\n  can drive your terminals.\n- On Feishu, the bot's tags are visible to your whole team (`HERDR_BOT_TAGS=off` turns\n  them off).\n- What looks like a secret (an API key, a token, a private key, `PASSWORD=…`) is hidden\n  before it is posted or logged; it is a safety net, not a guarantee (docs/guide.md,\n  \"Secrets are hidden\").\n- With `herdrchat hooks install`, a tap in the chat can allow what Claude Code or Codex\n  asks to do, as a key in the terminal can.\n\n## Remove\n\n`herdrchat uninstall` (for each profile), `herdrchat hooks uninstall`, `npm rm -g herdrchat`, delete\n`~/.config/herdrchat` and `~/.local/state/herdrchat`, then delete the Feishu app or the\nTelegram bot (@BotFather, `/deletebot`).\n\nHow it works and every setting: [docs/guide.md](docs/guide.md).\n\n## License\n\nMIT © [zhangxiangliang](https://github.com/zhangxiangliang)\n",
  "bytes": 8822,
  "sha": "c384bfbe665866a9d541b42bab0ae1703cc300012308f9b621b1702ab197c2cf",
  "repo_slug": "zhangxiangliang/herdrchat",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/skl_zhangxiangliang_herdrchat_herdrchat_6df70fc4/readme"
}