Skip to content
Back to search

herdr-core

herdr-core: terminals for coding agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 13 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/herdrdev/herdr-core with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/herdrdev/herdr-core'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/herdrdev--herdr-core/badge.svg)](/listings/herdrdev--herdr-core)

HTML

<a href="/listings/herdrdev--herdr-core"><img src="/api/listings/herdrdev--herdr-core/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Linux and macOS:

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

Windows (PowerShell):

powershell -c "irm https://releases.herdr.dev/core/install.ps1 | iex"

Builds are available for Linux and macOS on x86_64 and aarch64, and Windows on x86_64. Linux builds are static. On Windows, templates and quoted shell commands need `sh` on PATH, such as Git for Windows provides.

Run `hc update` to update. Running terminals keep running. Updates and `hc server restart` keep the environment the core started with; run `hc server restart --fresh` from a terminal outside Herdr to use that shell's environment without ending programs. Stopping and starting also takes a fresh one. The update from an older core to 0.1.19 uses the updater's environment once, because older cores can't save it for the next core.

If saving fails, the restart still goes ahead with the launcher's environment. Saved settings expire after three minutes and cannot carry over to another boot on Linux or macOS. On Windows, a restart cut short by a fast reboot can reuse them once. A plain SIGTERM keeps terminals and screens, but does not save settings. The new launcher still chooses the session's location and, on macOS, whether it starts from SSH or launchd.

See [security](docs/security.md) for the trust and signing details.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 186 lines · 2 findings marked
  1. # herdr-core (`hc`)
  2. `hc` runs programs and coding agents in terminals that stay alive after you leave.
  3. Agents can start other agents, send them work, and hear back; you can attach to any terminal and take over.
  4. Core draws nothing. Use it from your shell, an agent, or your own app.
  5. ## Install
  6. Linux and macOS:
  7. ```sh
  8. curl -fsSL https://releases.herdr.dev/core/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 13 on GitHub
  9. ```
  10. Windows (PowerShell):
  11. ```powershell
  12. powershell -c "irm https://releases.herdr.dev/core/install.ps1 | iex"
  13. ```
  14. Builds are available for Linux and macOS on x86_64 and aarch64, and Windows on x86_64.
  15. Linux builds are static. On Windows, templates and quoted shell commands need `sh` on PATH, such as Git for Windows provides.
  16. Run `hc update` to update. Running terminals keep running.
  17. Updates and `hc server restart` keep the environment the core started with;
  18. run `hc server restart --fresh` from a terminal outside Herdr to use that shell's
  19. environment without ending programs. Stopping and starting also takes a fresh one.
  20. The update from an older core to 0.1.19 uses the updater's environment once,
  21. because older cores can't save it for the next core.
  22. If saving fails, the restart still goes ahead with the launcher's environment.
  23. Saved settings expire after three minutes and cannot carry over to another boot
  24. on Linux or macOS. On Windows, a restart cut short by a fast reboot can reuse them
  25. once. A plain SIGTERM keeps terminals and screens, but does not save settings.
  26. The new launcher still chooses the session's location and, on macOS, whether it
  27. starts from SSH or launchd.
  28. See [security](docs/security.md) for the trust and signing details.
  29. ## Run it and come back
  30. ```sh
  31. hc run cargo test # stream output and wait for it
  32. hc run --bg --name web bun dev # start it and return
  33. hc ls # see live terminals
  34. hc attach web # take over; Ctrl+\ detaches
  35. hc read web --lines 100 # read without attaching
  36. ```
  37. Closing your viewer does not end the program.
  38. A waiting run checks in after 180 seconds by default, leaving the program running.
  39. It prints the terminal's address so you can read it or wait again.
  40. For a terminal you want to keep even if its program is lost, use `hc run --keep`.
  41. Recovery starts a fresh shell, never reruns the task.
  42. A normal exit or an explicit kill still ends it.
  43. To show a lost kept program's last saved screen above the new shell, set
  44. `restore_screen = true` in the same config.toml described below. It defaults
  45. to false. Changes apply at the next recovery. A divider marks where the old
  46. program ended; on Windows its screen is in history. `hc read` includes that
  47. old output, so scripts reading it can match text from the lost program. Each saved screen
  48. is consumed or discarded once, even with the setting off. A power cut that
  49. saves nothing starts blank.
  50. ## Default shell
  51. With no program, `hc run --bg` starts the machine's shell: `$SHELL` (or
  52. `/bin/sh`) on Unix, PowerShell 7 on Windows if available, else Windows PowerShell.
  53. Override it in `~/.config/herdr-core/config.toml` (Windows:
  54. `%APPDATA%\herdr-core\config.toml`, or `$XDG_CONFIG_HOME/herdr-core/config.toml`
  55. when set):
  56. ```toml
  57. shell = ["nu"]
  58. # Windows Git Bash (literal strings keep backslashes):
  59. # shell = ['C:\Program Files\Git\bin\bash.exe', '--login', '-i']
  60. ```
  61. The list is an executable followed by separate arguments, without extra path
  62. quoting. It must contain a nonempty executable. Changes apply to the next new
  63. shell or `keep` recovery, including recovery after a restart; no restart is
  64. needed. Running terminals, explicit programs, and quoted command lines keep
  65. their behavior. A bad setting reports a config error; a shell that cannot start
  66. reports `spawn_failed`. Recovery stays pending and retries, with errors in
  67. `core.log` (config) or `holder.log` (spawn); it never silently falls back to another shell.
  68. ## Draft wait
  69. Sends and parent notes wait for you to send or clear an unfinished draft,
  70. up to 60 seconds after your last key. In the same config.toml:
  71. ```toml
  72. notes_quiet = 3 # seconds of quiet before a parent note
  73. draft_wait = 60 # seconds a draft holds sends and notes; 0 keeps only the quiet pause
  74. ```
  75. Both settings apply to the next delivery without restarting the core. Values must
  76. be finite seconds that fit in a duration (a negative value means 0). If the config is invalid,
  77. delivery uses defaults and logs the config error once in `core.log`.
  78. Reverse sends allow at least the default 60-second draft hold.
  79. A parent configured above 60 seconds can still outwait a child configured below
  80. that parent's limit and cause its reverse send to time out.
  81. ## Agents run agents
  82. Give an agent `hc --skill`. It prints the agent docs in one read, including how to delegate, wait, report back, and clean up.
  83. [Templates](docs/templates.md) give an agent a command and a role.
  84. After saving the reviewer example from that page:
  85. ```sh
  86. hc templates
  87. hc run --bg --name review reviewer "Review src/x.rs. Read-only."
  88. hc send review "Focus on the error path."
  89. hc read review --lines 100
  90. ```
  91. Agents started inside an hc terminal become its children.
  92. They can report back with `hc send` and wait for their children with `hc wait --children all`.
  93. The parent gets notes when a child needs attention or ends.
  94. Children end with their parent unless started with `--outlive-parent`.
  95. On Unix, ending a terminal hangs up its program and foreground job, rather than
  96. hunting down detached programs. Programs deliberately detached with `nohup` or
  97. `setsid` can keep running, including background servers (their ports stay busy).
  98. An unexpected holder loss still uses inherited cleanup tokens to end abandoned
  99. programs, including detached ones. Windows keeps its job-object cleanup.
  100. Terminals kept alive through an update retain their old holder's behavior until
  101. recreated.
  102. ## Every machine
  103. ```sh
  104. hc machine add my-ssh-host --name box
  105. hc run --on box --cwd /srv/app cargo test
  106. hc attach box/t3
  107. ```
  108. Use the address returned by your run, not the example's `box/t3`.
  109. Programs and files stay on that machine. Your local core brings its terminals into the same list.
  110. [Machines](docs/machines.md) covers SSH, custom connections, remote files, and reconnecting.
  111. ## Status comes from the program
  112. An agent can say it is working, done, blocked, or in error through OSC 7501, the Program Status Protocol.
  113. Core stores what it reports. It does not guess from screen text or recognize agent brands.
  114. A program that does not report status has none.
  115. Use `hc get review` for a snapshot or `hc events` to follow changes.
  116. ## Build your own client
  117. `hc schema` prints the request/response API as OpenRPC with JSON Schema.
  118. [The API docs](schema/README.md) cover connecting, terminal streams, events, and status.
  119. Use `hc connect` to carry the protocol over stdin and stdout, including through SSH.
  120. ## Docs
  121. - [Commands](docs/commands.md): generated from the binary's help.
  122. - [Machines](docs/machines.md): work across machines.
  123. - [Templates](docs/templates.md): reusable agent roles.
  124. - [Security](docs/security.md): access, state, and updates.
  125. - [API](schema/README.md): build a client.
  126. For a quick lookup, run `hc --help` or a command's help, such as `hc run --help`.
  127. For agents, use `hc --skill`.
  128. ## Build from source
  129. You need Rust, Zig 0.16, and just. CI pins the Rust version in [.github/workflows/ci.yml](.github/workflows/ci.yml).
  130. ```sh
  131. git submodule update --init --depth 1
  132. cargo build --locked -p herdr-core
  133. just check
  134. ```
  135. `just install` installs this checkout and restarts your core. Running terminals keep running. A running core keeps its environment; if none is running, the one it starts gets only the login's own variables (PATH, HOME, USER, SHELL, locale, SSH agent and markers, display, session paths; see `scripts/restart-core.sh`), never the rest of the build shell's.
  136. `just docs` refreshes the command reference. `just docs-check` checks it and the examples; CI runs the same tests.
  137. See [CONTRIBUTING.md](CONTRIBUTING.md) for contributor setup and checks.
  138. License: [Apache-2.0](LICENSE). `hc --licenses` prints the included third-party licenses.
  139. After a dependency change, regenerate them with `just notices`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.