herdr-core (hc)
Run coding agents in terminals that survive your exit, pass work between them, and take over terminals from anywhere.
- Source repo
- herdrdev/herdr-core
- Stars
- ★ 832
- Last updated
- 4d ago
- License
- Apache-2.0
- Primary language
- Rust
- FA score
- 58/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers with long-running builds or test suites: start cargo test or bun dev with hc run --bg, leave, then check progress via hc attach or hc read.
- Not a fit if
- People wanting a ready-made GUI: the core draws nothing itself
- Teams that must guarantee detached background programs are killed
- Workflows that infer agent status from screen text or agent brands
- Website
- herdr.dev/core ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-16+23.1 ★/day over 7 days
- Source review
- 58/100 · Major gaps
What does this agent do, and when should you use it?
herdr-core, invoked as hc, is a terminal and process orchestration tool: it runs programs or coding agents in background sessions that keep running after you close the viewer, so you can reattach or read output later. The core draws no UI; you use it from a shell, from an agent, or through your own client. Agents started inside an hc terminal become children that can receive work with hc send, wait on siblings with hc wait --children all, and report notes when they need attention. Status is not guessed from screen text: programs report it via OSC 7501, the Program Status Protocol. Terminals can be extended across SSH machines with hc machine add and hc run --on, and a local core lists them all together. For custom clients, hc schema prints an OpenRPC request/response API with JSON Schema, and hc connect carries the protocol over stdin/stdout, including through SSH.
hc launches a command line (cargo test, bun dev, a template-defined agent role) or the default shell inside a persistent session and retains its output buffer. hc run streams output and waits; --bg detaches immediately; --keep starts a fresh shell if the program is later lost without rerunning the task. hc ls lists live terminals, hc attach takes over (Ctrl+\ detaches), hc read --lines N reads output without attaching, hc get returns a snapshot and hc events follows changes. A waiting run checks in after 180 seconds by default and prints the terminal's address. Agents that start children can report back with hc send, block on hc wait --children all, and extend lifetime with --outlive-parent; parents receive notes when a child needs attention or ends. Draft handling is governed by draft_wait and notes_quiet in config.toml. hc machine add and hc run --on schedule work on remote SSH hosts while programs and files stay there. hc schema emits the OpenRPC surface and hc connect bridges it over stdin/stdout; hc --skill prints agent documentation in one read.
- Developers with long-running builds or test suites: start cargo test or bun dev with hc run --bg, leave, then check progress via hc attach or hc read.
- Teams orchestrating multiple agents: a parent sends work to children with hc send, waits with hc wait --children all, and relies on notes to know when a human is needed.
- Engineers working across machines: register an SSH host with hc machine add and run commands there with hc run --on, viewing all terminals from a local core.
- Builders of custom front-ends or IDE integrations: consume the OpenRPC interface from hc schema and bridge it with hc connect over stdin/stdout or SSH.
- Users who want reusable agent roles: save a reviewer template and launch it with hc run --bg --name review reviewer "Review src/x.rs. Read-only."
- Operators who cannot stay attached to a window: use hc run --keep so a lost program still leaves a shell for investigation.
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
curl -fsSL https://releases.herdr.dev/core/install.sh | sh
- Config files
.github/workflows/ci.ymlXDG_CONFIG_HOME/herdr-core/config.toml- Install notes cover
- Windows · macOS · Linux
How do you install or deploy this agent?
On Linux and macOS, run the official install script. On Windows, use the PowerShell script. Builds exist for Linux and macOS on x86_64 and aarch64, and Windows on x86_64; Linux builds are static.
curl -fsSL https://releases.herdr.dev/core/install.sh | shpowershell -c "irm https://releases.herdr.dev/core/install.ps1 | iex"Building from source needs Rust, Zig 0.16 and just; CI pins the Rust version in .github/workflows/ci.yml:
git submodule update --init --depth 1
cargo build --locked -p herdr-core
just checkjust installOn Windows, templates and quoted shell commands need sh on PATH, such as Git for Windows provides.
How do you use this agent?
After installing, run programs directly with hc; with no program, hc run --bg starts the machine's shell ($SHELL or /bin/sh on Unix, PowerShell 7 if available on Windows, else Windows PowerShell).
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 attachingThe default shell and draft wait are configurable in config.toml (Windows: %APPDATA%\herdr-core\config.toml, or $XDG_CONFIG_HOME/herdr-core/config.toml when set):
shell = ["nu"]
# Windows Git Bash (literal strings keep backslashes):
# shell = ['C:\Program Files\Git\bin\bash.exe', '--login', '-i']
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 pauseHand an agent the docs and drive it with a template:
hc --skill
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 100Work across machines:
hc machine add my-ssh-host --name box
hc run --on box --cwd /srv/app cargo test
hc attach box/t3Build your own client or update the core:
hc schema
hc connect
hc updateWhat are this agent's strengths and limitations?
- Terminals outlive the viewer: programs keep running after you detach, and hc attach or hc read let you return without disturbing them.
- First-class agent-to-agent primitives: hc send, hc wait --children all, parent notes and --outlive-parent give delegation a defined protocol.
- Status is reported by programs via OSC 7501 (Program Status Protocol); the core stores what is reported instead of guessing from screen text or brands.
- Multi-machine operation is built in through SSH and custom connections, with a local core listing all terminals.
- Client-friendly by design: hc schema exposes OpenRPC with JSON Schema, and hc connect carries the protocol over stdin/stdout, including through SSH.
- The core renders nothing, so you need your own shell or client to use it interactively.
- On Unix, ending a terminal hangs up the foreground job, but nohup/setsid-detached programs may survive and keep ports busy; only unexpected holder loss triggers token-based cleanup.
- Windows support for templates and quoted shell commands depends on sh being on PATH, e.g. Git for Windows.
- Saved settings expire after three minutes and cannot carry over to another boot on Linux or macOS; a plain SIGTERM keeps terminals but does not save settings.
- Some README examples are placeholders: attach expects the address returned by your run, not the sample box/t3.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| herdr-core (hc) This agent | 58 · Major gaps | CLIFree | ★ 832 | 4d ago | Rust | — |
| tlbx | 73 · Some gaps | Self-hosted serviceFree + model costs | ★ 119 | today | C# | Codex · Claude Code |
| TUIOS Terminal Workspace | 74 · Some gaps | CLIFree | ★ 6.6k | today | Go | — |
| cmux | 79 · Good | Desktop appFreemium | ★ 29k | today | Swift | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
docs/security.md honestly states core runs with the account's access, is not a sandbox, and has no per-client auth; Unix socket 0700 and Windows named pipes limited to the account and SYSTEM. Disclosure is good but the privilege model is broad, so least_privilege is 1. The skill asks the user once per session whether to use hc, but run/update/restart and remote machine installs have no per-action confirmation, and rollback relies only on --keep and holder survival, so user_confirmation and rollback are 1. Data-flow transparency (state dirs, sockets, remote trust, update checks) and sensitive-data handling (terminal output may contain secrets, state unencrypted) are documented, scoring 2. Dependency security has cargo-deny, a pinned toolchain, SHA-pinned actions and a third-party notices check, but no audit results are shown, scoring 2. Source attribution for Ghostty upstream and licensing is stated in AGENTS.md and README, scoring 2.
README and the skill manual consistently and concretely describe wait timeouts, draft_wait, first_message.sent and spawn_failed, so failure_messages is 2. Self-consistency is broadly coherent, though the skill excerpt is truncated and some behavior depends on interacting config values, so 2. Dependency availability requires Rust, Zig 0.16, just, submodules and network install scripts, plus sh and ConPTY on Windows, with no offline path, so 1.
The skill states scenarios (sub-agents, background tasks, cross-machine) and boundaries (window layout belongs to herdr-app), with a fairly precise trigger ($HC_TERMINAL_ID, ask once), and covers Linux/macOS/Windows and SSH, scoring 2. Windows still needs sh and differs on templates and quoted commands, so not 3.
README has clear structure, complete install notes, worked examples and known limitations (conditional signing, expiring saved settings, SIGTERM not saving settings); LICENSE is full Apache-2.0 matching Cargo.toml, scoring 3. Versioning is only described as a CHANGELOG rule and v* tags with no changelog content in the packet, scoring 1. Maintenance responsibility names a single maintainer who alone can release, clear but single-point, scoring 2.
Output usability is concrete (JSON vs text, hc get/read/wait), scoring 2. Marginal value over tmux/nohup (agent orchestration, status protocol, cross-machine) is asserted without benchmarks, scoring 2. Cost-benefit is thin: curl|sh install, Zig and submodule build, paid real-agent smokes, scoring 1.
AGENTS.md requires reporting only what was observed and status only from OSC 7501, supporting claim_traceability and fact_inference_separation at 2. README, skill manual, security doc and CI corroborate each other (update keeps terminals, signing conditions, test isolation), scoring 2. No executed test evidence and the install scripts and release manifest are outside the packet, so not 3.
- Core runs with the account's access and has no per-client auth; any process that can reach its socket effectively has a shell as that account. Do not run as root/administrator and do not forward the socket to untrusted parties.
- Install and update use curl|sh plus an HTTPS manifest with SHA-256 checks, but the manifest is not independently signed; Windows builds are unsigned when the signing profile is unset, and macOS team-signature enforcement applies only with the default release service.
- State is not encrypted and terminal output or saved screens may contain secrets; HC_SESSION is not a security boundary.
- Adding a remote machine gives local clients access to that account's commands and files and copies executable code there; trust the destination and any custom connection command.
- Building needs Rust, Zig 0.16, just and submodules, plus sh and ConPTY on Windows, which is costly in offline or restricted environments.
- Releases are gated to a single maintainer and no actual changelog content is in the packet, limiting version-history traceability.
FAQ
Is herdr-core a graphical terminal?
What happens to a running program if I close my viewer or drop SSH?
Are background processes guaranteed to be cleaned up when a terminal ends?
How does hc know an agent is working, done, blocked or in error?
Do I need a specific host setup?
Is herdr-core (hc) free?
Is herdr-core (hc) open source?
Is herdr-core (hc) safe to use?
Is herdr-core (hc) still maintained?
Who makes herdr-core (hc)?
What is herdr-core (hc)'s official website?
Thanks — we use this to improve the page.