aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md239
1 files changed, 239 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..2e9e157f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,239 @@
+<p align="center">
+ <img src="assets/logo.png" alt="herdr" width="120" />
+</p>
+
+<h1 align="center">herdr</h1>
+
+<p align="center">herd your agents.</p>
+
+<p align="center">
+ <a href="https://herdr.dev">herdr.dev</a> · <a href="#install">install</a> · <a href="#usage">usage</a>
+</p>
+
+---
+
+herdr is a terminal workspace manager for AI coding agents. it runs inside your existing terminal — ghostty, alacritty, kitty, wezterm, even inside tmux. a single rust binary that gives you workspaces, tiled panes, and intelligent agent state detection.
+
+you keep your terminal. herdr keeps track of your agents.
+
+<p align="center">
+ <img src="assets/screenshot.png" alt="herdr screenshot" width="900" />
+</p>
+
+## philosophy
+
+every tool in this space is building more. desktop apps, electron wrappers, web dashboards — all trying to replace your terminal with their own environment.
+
+herdr takes the opposite approach. it's a tool that lives where you already work. it sits alongside tmux, inside your terminal emulator, part of your existing workflow. it does one thing well: lets you run multiple coding agents in parallel and know when they need you.
+
+the terminal is already a great environment for coding agents. what's been missing is awareness — seeing at a glance which agent is idle, which is working, and which needs your input. herdr adds that layer.
+
+## how it works
+
+herdr embeds real terminal emulators using PTY and vt100 parsing. each pane is a full terminal — your shell, your agent, your tools, exactly as they'd run anywhere else.
+
+the sidebar shows your workspaces. each workspace can have multiple tiled panes. the agent detection system reads terminal output in real time and determines what state each agent is in:
+
+- **●** red — agent is waiting for your input
+- **●** yellow — agent is working
+- **●** blue — agent finished (you haven't looked yet)
+- **○** green — agent is idle, you've seen it
+
+when an agent finishes work in a background workspace, its dot turns blue. you see it at a glance and switch over. it just reads the terminal.
+
+## supported agents
+
+herdr detects agent state by identifying the foreground process and reading terminal output patterns. the following agents have been tested:
+
+| agent | idle | busy | waiting |
+|-------|------|------|---------|
+| [pi](https://pi.dev) | ✓ | ✓ | ✓ |
+| [claude code](https://docs.anthropic.com/en/docs/claude-code) | ✓ | ✓ | ✓ |
+| [codex](https://github.com/openai/codex) | ✓ | ✓ | ✓ |
+| [droid](https://factory.ai) | ✓ | ✓ | ✓ |
+| [amp](https://ampcode.com) | ✓ | ✓ | — |
+| [opencode](https://github.com/anomalyco/opencode) | ✓ | ✓ | ✓ |
+
+detection heuristics also exist for these agents but haven't been fully tested yet. if you use them and run into issues, please [open an issue](https://github.com/ogulcancelik/herdr/issues):
+
+- [gemini cli](https://github.com/google-gemini/gemini-cli)
+- [cursor agent](https://cursor.com/cli)
+- [cline](https://github.com/cline/cline)
+- [kimi](https://kimi.ai)
+- [github copilot cli](https://cli.github.com)
+
+for any other CLI agent, herdr still works as a workspace manager — you get workspaces, panes, and tiling. a hook system for custom agent state reporting is coming soon.
+
+## install
+
+```bash
+curl -fsSL https://herdr.dev/install.sh | sh
+```
+
+or download the binary directly from [releases](https://github.com/ogulcancelik/herdr/releases).
+
+requirements: linux or macos.
+
+### update
+
+herdr checks for updates automatically in the background. when a new version is ready, you'll see a notification in the UI — just restart to apply. you can also update manually:
+
+```bash
+herdr update
+```
+
+## usage
+
+launch herdr:
+
+```bash
+herdr
+```
+
+herdr starts in **navigate mode**. press `n` to create your first workspace, type a name, press enter. you're in **terminal mode** with a shell ready.
+
+press `ctrl+s` (the prefix key) to switch back to navigate mode. from there you can manage workspaces and panes.
+
+### navigate mode (prefix: ctrl+s)
+
+| key | action | configurable |
+|-----|--------|:---:|
+| `n` | new workspace | |
+| `N` | rename workspace | |
+| `d` | close workspace | |
+| `1`-`9` | switch to workspace by number | |
+| `↑` `↓` | select workspace | |
+| `enter` | open selected workspace | |
+| `v` | split pane vertically | ✓ |
+| `-` | split pane horizontally | ✓ |
+| `h` `j` `k` `l` | navigate between panes | |
+| `tab` | cycle panes | |
+| `f` | toggle fullscreen | ✓ |
+| `x` | close pane | ✓ |
+| `r` | enter resize mode | |
+| `b` | toggle sidebar collapse | |
+| `q` | quit | |
+
+keys marked ✓ can be changed in `~/.config/herdr/config.toml` under `[keys]`. the prefix key is also configurable.
+
+### resize mode
+
+| key | action |
+|-----|--------|
+| `h` `l` | resize width |
+| `j` `k` | resize height |
+| `esc` | exit resize mode |
+
+### mouse
+
+- click a workspace in the sidebar to switch
+- click a pane to focus it
+- drag split borders to resize
+- right-click a workspace for context menu
+- scroll in sidebar to navigate workspaces
+- click `«` / `»` at the sidebar bottom to collapse/expand
+
+### terminal mode
+
+you're in a real terminal. everything works — your shell, vim, htop, ssh, anything. press the prefix key (`ctrl+s`) to go back to navigate mode.
+
+## configuration
+
+config file: `~/.config/herdr/config.toml`
+
+generate the default config with all options:
+
+```bash
+herdr --default-config
+```
+
+```toml
+[keys]
+# prefix key to enter navigate mode
+prefix = "ctrl+s"
+
+# pane controls (in navigate mode)
+split_vertical = "v"
+split_horizontal = "-"
+close_pane = "x"
+fullscreen = "f"
+
+[ui]
+# accent color: hex (#89b4fa), named (cyan, blue), or rgb(r,g,b)
+accent = "cyan"
+
+# ask for confirmation before closing a workspace
+confirm_close = true
+```
+
+### environment variables
+
+| variable | description |
+|----------|-------------|
+| `HERDR_LOG` | log level filter (default: `herdr=info`) |
+
+logs: `~/.config/herdr/herdr.log`
+
+## session persistence
+
+herdr saves your workspace layout, pane working directories, and focused pane on exit. when you restart, everything is restored. sessions are stored at `~/.config/herdr/session.json`.
+
+use `--no-session` to start fresh.
+
+## how agent detection works
+
+herdr doesn't require hooks or agent-side configuration. detection works by:
+
+1. identifying the foreground process of each pane's PTY (via `/proc` on linux, `proc_pidinfo` on macos)
+2. matching the process name against known agents
+3. reading terminal screen content and applying per-agent heuristics to determine state
+
+this means detection works with any supported agent, installed any way, with zero setup. if it runs in a terminal, herdr can see it.
+
+the heuristics are pattern-matched against each agent's actual terminal output — prompt boxes, spinners, "waiting for input" messages, tool execution indicators. detection runs on a separate async task per pane, polled every 300-500ms, decoupled from terminal rendering.
+
+## what's coming
+
+- **notification hooks** — a socket API so any agent or script can report its state to herdr. for agents without built-in detection, wire up a simple hook.
+- **native notifications** — OS-level notifications when an agent needs attention and herdr isn't in focus.
+- **agent API** — `herdr create`, `herdr split`, `herdr send` — so agents and scripts can manage herdr workspaces programmatically.
+
+## built with agents
+
+i had never written rust before starting this project. herdr was built almost entirely through AI coding agents — the same ones it's designed to manage. i supervised the architecture and specs, agents wrote the code.
+
+this is a proof of concept in more ways than one. it's a functional tool, but it's also a statement about what's possible right now. if you can build a terminal multiplexer in a language you don't know, by directing the same agents the tool is built for — that says something about where we are.
+
+there will be rough edges. if you hit one, [open an issue](https://github.com/ogulcancelik/herdr/issues). that's why it's open source.
+
+## cli
+
+```
+herdr launch herdr
+herdr update download and install the latest version
+herdr --version print version
+herdr --default-config print default configuration
+herdr --no-session start without restoring or saving sessions
+herdr --help show help
+```
+
+## building from source
+
+```bash
+git clone https://github.com/ogulcancelik/herdr
+cd herdr
+cargo build --release
+./target/release/herdr
+```
+
+## testing
+
+```bash
+just test # unit tests (157 tests)
+just test-integration # LLM-based integration tests
+just test-all # both
+```
+
+## license
+
+AGPL-3.0 — free to use, modify, and distribute. if you distribute a modified version, you must open-source your changes under the same license.