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.
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
Markdown
[](/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
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
- # herdr-core (`hc`)
- `hc` runs programs and coding agents in terminals that stay alive after you leave.
- Agents can start other agents, send them work, and hear back; you can attach to any terminal and take over.
- Core draws nothing. Use it from your shell, an agent, or your own app.
- ## Install
- Linux and macOS:
- ```sh
- 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
- ```
- Windows (PowerShell):
- ```powershell
- powershell -c "irm https://releases.herdr.dev/core/install.ps1 | iex"
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 19 on GitHub
- ```
- 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.
- ## Run it and come back
- ```sh
- hc run cargo test # stream output and wait for it
- hc run --bg --name web bun dev # start it and return
- hc ls # see live terminals
- hc attach web # take over; Ctrl+\ detaches
- hc read web --lines 100 # read without attaching
- ```
- Closing your viewer does not end the program.
- A waiting run checks in after 180 seconds by default, leaving the program running.
- It prints the terminal's address so you can read it or wait again.
- For a terminal you want to keep even if its program is lost, use `hc run --keep`.
- Recovery starts a fresh shell, never reruns the task.
- A normal exit or an explicit kill still ends it.
- To show a lost kept program's last saved screen above the new shell, set
- `restore_screen = true` in the same config.toml described below. It defaults
- to false. Changes apply at the next recovery. A divider marks where the old
- program ended; on Windows its screen is in history. `hc read` includes that
- old output, so scripts reading it can match text from the lost program. Each saved screen
- is consumed or discarded once, even with the setting off. A power cut that
- saves nothing starts blank.
- ## Default shell
- With no program, `hc run --bg` starts the machine's shell: `$SHELL` (or
- `/bin/sh`) on Unix, PowerShell 7 on Windows if available, else Windows PowerShell.
- Override it in `~/.config/herdr-core/config.toml` (Windows:
- `%APPDATA%\herdr-core\config.toml`, or `$XDG_CONFIG_HOME/herdr-core/config.toml`
- when set):
- ```toml
- shell = ["nu"]
- # Windows Git Bash (literal strings keep backslashes):
- # shell = ['C:\Program Files\Git\bin\bash.exe', '--login', '-i']
- ```
- The list is an executable followed by separate arguments, without extra path
- quoting. It must contain a nonempty executable. Changes apply to the next new
- shell or `keep` recovery, including recovery after a restart; no restart is
- needed. Running terminals, explicit programs, and quoted command lines keep
- their behavior. A bad setting reports a config error; a shell that cannot start
- reports `spawn_failed`. Recovery stays pending and retries, with errors in
- `core.log` (config) or `holder.log` (spawn); it never silently falls back to another shell.
- ## Draft wait
- Sends and parent notes wait for you to send or clear an unfinished draft,
- up to 60 seconds after your last key. In the same config.toml:
- ```toml
- notes_quiet = 3 # seconds of quiet before a parent note
- draft_wait = 60 # seconds a draft holds sends and notes; 0 keeps only the quiet pause
- ```
- Both settings apply to the next delivery without restarting the core. Values must
- be finite seconds that fit in a duration (a negative value means 0). If the config is invalid,
- delivery uses defaults and logs the config error once in `core.log`.
- Reverse sends allow at least the default 60-second draft hold.
- A parent configured above 60 seconds can still outwait a child configured below
- that parent's limit and cause its reverse send to time out.
- ## Agents run agents
- Give an agent `hc --skill`. It prints the agent docs in one read, including how to delegate, wait, report back, and clean up.
- [Templates](docs/templates.md) give an agent a command and a role.
- After saving the reviewer example from that page:
- ```sh
- hc templates
- hc run --bg --name review reviewer "Review src/x.rs. Read-only."
- hc send review "Focus on the error path."
- hc read review --lines 100
- ```
- Agents started inside an hc terminal become its children.
- They can report back with `hc send` and wait for their children with `hc wait --children all`.
- The parent gets notes when a child needs attention or ends.
- Children end with their parent unless started with `--outlive-parent`.
- On Unix, ending a terminal hangs up its program and foreground job, rather than
- hunting down detached programs. Programs deliberately detached with `nohup` or
- `setsid` can keep running, including background servers (their ports stay busy).
- An unexpected holder loss still uses inherited cleanup tokens to end abandoned
- programs, including detached ones. Windows keeps its job-object cleanup.
- Terminals kept alive through an update retain their old holder's behavior until
- recreated.
- ## Every machine
- ```sh
- hc machine add my-ssh-host --name box
- hc run --on box --cwd /srv/app cargo test
- hc attach box/t3
- ```
- Use the address returned by your run, not the example's `box/t3`.
- Programs and files stay on that machine. Your local core brings its terminals into the same list.
- [Machines](docs/machines.md) covers SSH, custom connections, remote files, and reconnecting.
- ## Status comes from the program
- An agent can say it is working, done, blocked, or in error through OSC 7501, the Program Status Protocol.
- Core stores what it reports. It does not guess from screen text or recognize agent brands.
- A program that does not report status has none.
- Use `hc get review` for a snapshot or `hc events` to follow changes.
- ## Build your own client
- `hc schema` prints the request/response API as OpenRPC with JSON Schema.
- [The API docs](schema/README.md) cover connecting, terminal streams, events, and status.
- Use `hc connect` to carry the protocol over stdin and stdout, including through SSH.
- ## Docs
- - [Commands](docs/commands.md): generated from the binary's help.
- - [Machines](docs/machines.md): work across machines.
- - [Templates](docs/templates.md): reusable agent roles.
- - [Security](docs/security.md): access, state, and updates.
- - [API](schema/README.md): build a client.
- For a quick lookup, run `hc --help` or a command's help, such as `hc run --help`.
- For agents, use `hc --skill`.
- ## Build from source
- You need Rust, Zig 0.16, and just. CI pins the Rust version in [.github/workflows/ci.yml](.github/workflows/ci.yml).
- ```sh
- git submodule update --init --depth 1
- cargo build --locked -p herdr-core
- just check
- ```
- `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.
- `just docs` refreshes the command reference. `just docs-check` checks it and the examples; CI runs the same tests.
- See [CONTRIBUTING.md](CONTRIBUTING.md) for contributor setup and checks.
- License: [Apache-2.0](LICENSE). `hc --licenses` prints the included third-party licenses.
- After a dependency change, regenerate them with `just notices`.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.