Agent Runtime · Herdr, Inc.

Herdr
Cheat Sheet

“The runtime your coding agents live on — laptop, desktop, or a box you rent.” Herdr là background server giữ terminal của AI coding agent chạy liên tục — sống qua mất mạng, đóng nắp máy, restart. Multiplexer “mouse-first” quen thuộc như tmux (prefix Ctrl+b), nhận diện sẵn 19 agent CLI: Claude Code, Codex, Cursor…

Quick Start Tính năng CLI & API Agents Keybindings Config Official Docs ↗ GitHub ↗

Open source · Apache 2.0

Tổng quan

Herdr là gì?

Một runtime dạng server giữ các phiên terminal thật luôn mở để coding agent làm việc liên tục mà không cần bạn ngồi canh. Herdr theo dõi agent nào đang chạy, bị chặn hay rảnh, cho agent tự tách pane & gọi lẫn nhau qua CLI/socket, và khôi phục layout sau khi restart máy. Từ máy nào có bàn phím cũng reconnect lại được. Backed by Y Combinator, phát hành dưới Apache 2.0.

Always running

Terminal vẫn sống khi bạn đóng nắp máy hay mất mạng. Detach client thì server vẫn chạy nền, process không dừng.

Agent status visibility

Hiện agent nào đang working, blocked hay idle. Trạng thái roll-up lên tab & workspace, nhảy thẳng tới pane cần chú ý.

Agent-native API

Agent tự split pane, khởi động agent khác và giao tiếp qua CLI herdr hoặc raw socket (pane.split, agent.wait…).

Universal compatibility

Chạy Claude Code, Codex, Cursor, opencode, Grok… 19 agent CLI không cần chỉnh sửa. Session & layout tự khôi phục sau khi restart.

Khác gì cmux? cmux là app terminal GUI chạy local trên macOS (Ghostty, browser tích hợp) — đóng app là process dừng. Herdr là server chạy nền mọi nơi (laptop, desktop, VPS thuê): agent vẫn chạy tiếp khi bạn detach, đóng máy hay mất mạng, và reconnect được từ máy khác.

Features

Tính năng chính

Always-on serverCore

Detach client, đóng nắp máy hay rớt mạng — server vẫn chạy, process không dừng. Đây là mức bền nhất.

Status detectionAgent

Tự phát hiện agent đang working, blocked hay idle; roll-up lên tab & workspace, không phải hunt pane nào đang kẹt.

Agent-native APIControl

CLI & raw socket hợp nhất. Agent phối hợp bằng block thật (agent.wait) thay vì mô phỏng keystroke.

Runs unmodifiedZero wrapper

Binary agent hiện có chạy nguyên xi — không cần lớp wrapper, không đổi lệnh quen thuộc.

Reconnect mọi máyRemote

Attach lại phiên đang chạy từ bất kỳ máy nào có bàn phím. Bắt đầu ở laptop, tiếp tục trên desktop.

Layout restoreSession

Khôi phục workspace/tab/pane sau khi restart; agent tự resume, pane history replay (experimental).

Mouse-firstUX

Click để focus, kéo viền để resize, right-click mở menu. Không cần học shortcut để bắt đầu — vẫn có prefix kiểu tmux khi cần.

19 agents sẵn cóCompat

Claude Code, Codex, Cursor, Pi, opencode, Grok, Copilot, Hermes… nhận diện out-of-the-box qua hooks hoặc screen-manifest.

Getting Started

Quick Start

Install (macOS/Linux)

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

Hoặc brew install herdr · mise use -g herdr. Windows (beta): irm https://herdr.dev/install.ps1 | iex.

Launch

herdr

Chạy từ thư mục project bất kỳ → Herdr tạo hoặc attach vào default background session. Bạn không phải quản lý socket.

Chạy agent trong pane

claude
codex
pi
opencode

Gõ tên agent CLI trong pane bất kỳ. Herdr tự phát hiện & theo dõi trạng thái. Detach: Ctrl+b rồi q.

Reference

CLI & Socket API

Mọi thao tác đều có subcommand herdr tương ứng, hoặc gọi trực tiếp qua raw socket theo dot-notation (pane.split, layout.export…). Target pane dạng w1:p1 hoặc --current.

Workspaces & tabs

workspace create--cwd ~/project --label api

tab create--label logs

statusTổng quan trạng thái hiện tại

api snapshotSnapshot toàn bộ state

api schema [--json]Schema của socket API

Panes — layout

pane split w1:p1--direction right

pane run w1:p2"npm test"

pane resize--direction right --amount 0.1

pane swap--direction right --current

pane zoom--on --current

pane neighbor--direction right --current

Panes — đọc output

pane read --source recent--lines 50

pane read --source visible--lines 80

pane read --source detectionVùng agent-detection

pane layout --currentCây layout hiện tại

Raw socket methods

pane.split · pane.readTách & đọc pane

pane.send_text · send_keysGửi text / phím

pane.focus · move · swapĐiều hướng pane

layout.apply · layout.exportÁp / xuất layout

events.subscribe · waitNghe/chờ event

Agents

Agent integration

Herdr tự phát hiện các agent phổ biến: Claude Code, Codex, Cursor Agent CLI, OpenCode, Grok CLI, GitHub Copilot CLI, Devin CLI, Kimi Code CLI, Pi, OMP và nhiều CLI khác. Trạng thái xác định qua lifecycle hooks (agent được tích hợp) hoặc screen-manifest detection (phân tích buffer terminal). Gemini CLI & Cline được phát hiện nhưng ít được kiểm thử hơn.

Integration & attach

integration install claudeCài hook cho agent

integration statusKiểm tra version integration

agent attach reviewerAttach thẳng vào agent terminal

agent attach reviewer --takeoverAttach & chiếm quyền điều khiển

Label, wait & debug

agent rename w1:p1 reviewerĐổi tên hiển thị

agent rename reviewer --clearXóa nhãn

agent wait w1:p1 --until doneChờ agent xong (hoặc blocked)

agent explain <target>Giải thích trạng thái phát hiện

Báo metadata thủ công cho source ngoài luồng: herdr pane report-agent w1:p1 --source custom:indexer --agent docs-bot --state working. Cập nhật lại manifest: herdr server update-agent-manifests.

Reference

Keybindings

Prefix mặc định là Ctrl+b (tương thích workflow tmux). Nhấn prefix rồi phím lệnh. Xem toàn bộ binding với prefix+?. Đổi trong [keys] của config, rồi herdr server reload-config. Không cần học shortcut để bắt đầu — click chuột cũng được.

Panes & tabs

prefix+vSplit sang phải

prefix+minusSplit xuống dưới

prefix+cTab mới

prefix+nTab kế tiếp

prefix+pTab trước đó

Workspaces & client

prefix+wĐiều hướng workspace

prefix+shift+nWorkspace mới

prefix+qDetach client (server vẫn chạy)

prefix+?Hiện mọi keybinding

Mouse-first: click pane/tab/workspace/agent để focus, kéo viền split để resize, right-click mở context menu.

Config

Cấu hình

Định dạng TOML tại ~/.config/herdr/config.toml (Linux/macOS) hoặc %APPDATA%\herdr\config.toml (Windows). Chạy herdr --help để xem đường dẫn thực tế, sửa xong reload bằng herdr server reload-config.

[keys]Prefix

Đổi prefix: prefix = "ctrl+b". Mỗi action nhận mảng shortcut, ví dụ next_tab = ["prefix+n", "ctrl+alt+]"].

[theme]Look

name = "catppuccin" hoặc dùng màu terminal. Tự đổi sáng/tối với auto_switch = true + light_name/dark_name.

[ui.sidebar]Layout

Bố trí sidebar Agent/Space bằng mảng rows với token state_icon, workspace, tab, agent.

[ui.toast]Notify

Chọn kênh toast: herdr, terminal, system hoặc off; đặt vị trí (vd bottom-right).

[terminal]Shell

Đặt shell mặc định: default_shell = "nu". Các tùy chọn scrollback & nâng cao xem Config reference.

[session]Persist

Bật replay lịch sử pane: [experimental] pane_history = true. Tắt auto-resume agent: resume_agents_on_restore = false.

Session

Session persistence

Điểm Herdr khác hẳn một terminal GUI local: detach không giết process. Có hai mức — ngắt kết nối (server vẫn sống) và restart máy (process buộc dừng, chỉ khôi phục được layout).

Detach / mất mạng — server vẫn chạy

Agent & process đang chạyChạy tiếp

Output & scrollbackGiữ nguyên

Layout pane / tab / workspaceGiữ nguyên

Reconnect từ máy khácĐược

Sau khi restart máy / server

Layout pane / tab / workspaceKhôi phục

Agent tự resumeCó (config)

Pane history replayExperimental

Live process in-memoryKhông

Dừng hẳn server: herdr server stop. Nâng cấp mà giữ tiến trình đang chạy (experimental): herdr update --handoff.

Examples

Dùng thực tế

herdr — agent runtime

# Khởi động / attach default session

$herdr

# Tạo workspace riêng cho service api

$herdr workspace create --cwd ~/project --label api

# Split pane rồi chạy test trong đó

$herdr pane split w1:p1 --direction right

$herdr pane run w1:p2 "npm test"

# Chờ agent xong việc trước khi bước tiếp

$herdr agent wait w1:p1 --until done

# Đọc 50 dòng output gần nhất của pane

$herdr pane read w1:p2 --source recent --lines 50

Resources

Tài liệu & cộng đồng

WebsiteHome

Landing, installer & tổng quan tính năng.

herdr.dev

Official DocsRead

Quick start, install, agents, session state, configuration, socket API.

herdr.dev/docs

GitHubSource

Mã nguồn, releases, issues. Backed by Y Combinator · Apache 2.0.

github.com/herdrdev/herdr

Install one-linerQuick

Cài nhanh trên macOS/Linux.