README
¶
nerdr
website · install · quick start · docs
Run a team of coding agents, each in its own Git worktree, and review their work, all in one terminal.
A new tab with Codex, the repositories and their status lights, Claude's changes in the review panel, the tests in a terminal, Codex reviewing Claude's work, and the waiting list taking you to the agent with a question.
- One task, one tab. Each tab gets a branch and a worktree from the
latest
main, and the agent you pick. Start from an issue, a pull request or another tab's branch. Tabs and worktrees → - See who needs you. Status lights show which agents work, wait for input or are done; the waiting list takes you to them. Progress →
- A workbench per tab. Terminals, more agents and code reviews beside the agent, in the same worktree. Agents message each other and share out the work. The workbench →
- Review before you merge. Word-level diffs, the agent's notes on why, guided walkthroughs, and a second agent that reviews the work and sends findings back. Code review →
- From task to merge. Commit, push, open pull requests, hand review comments and failing CI to the agent, and close the tab when it is merged. GitHub →
- Your agents, as they are. Claude Code, Codex, Copilot, opencode, Cursor, Gemini and Antigravity, with their own settings, in a sandbox if you like. Agents →
- Your own scripts as plugins. Custom scripts (like rebuilding Docker or
seeding a database) that agents can run with parameters, or that you can
run directly in
F5. Plugins → - Keyboard and mouse. Every command has a key after
ctrl+q, and most can be clicked. Keys →
Install
On Linux or macOS:
curl -fsSL https://nerdr.app/install.sh | sh
or with Homebrew, brew install nerdr-dev/tap/nerdr, or with Go 1.27 or
newer, go install github.com/nerdr-dev/nerdr/cmd/nerdr@latest. The
binaries are also on the releases page.
You need git and at least one coding agent on your PATH. Sign in to gh
for pull requests, CI and issues. See install
for the details and for building from source.
Start it in the folder that holds your repositories:
cd ~/develop
nerdr
Pick one or more repositories, name a branch, choose an agent, and it starts
working. Press ctrl+q ? to find any command. See the
quick start.
Docs
Everything lives at nerdr.app:
about · concepts · tabs and worktrees · the workbench · agents together · code review · review panel · configuration · keyboard · plugins · remote machines · security
Inspired by herdr
nerdr builds on herdr's status lights, mouse controls and rules for detecting an agent's state; see NOTICE. Run nerdr inside herdr to keep agents running when you detach, or on another machine.
Development
make build # ./nerdr
make test # unit tests
make e2e # the real binary in a pseudo-terminal with a fake agent
The docs site is in docs/; see
Development.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
nerdr
command
Command nerdr runs coding agents in tabs, each in its own git worktree, with a live review of what they change beside them.
|
Command nerdr runs coding agents in tabs, each in its own git worktree, with a live review of what they change beside them. |
|
internal
|
|
|
agents
Package agents knows the coding-agent CLIs nerdr can run in a tab: which are installed, how to start one, and how to pick its conversation up again after the machine has been restarted.
|
Package agents knows the coding-agent CLIs nerdr can run in a tab: which are installed, how to start one, and how to pick its conversation up again after the machine has been restarted. |
|
app
Package app is nerdr's screen: a row of tabs, each an agent working in its own git worktrees, with the review panel beside it.
|
Package app is nerdr's screen: a row of tabs, each an agent working in its own git worktrees, with the review panel beside it. |
|
awake
Package awake keeps the machine from going to sleep, and its screen from going dark, while nerdr asks it to: while an agent works, say.
|
Package awake keeps the machine from going to sleep, and its screen from going dark, while nerdr asks it to: while an agent works, say. |
|
browser
Package browser opens a URL — a pull request, a comment, a CI run — in the user's browser.
|
Package browser opens a URL — a pull request, a comment, a CI run — in the user's browser. |
|
clean
Package clean makes text an agent wrote safe to draw on the terminal.
|
Package clean makes text an agent wrote safe to draw on the terminal. |
|
codereview
Package codereview is a second agent reviewing the work of a tab's own.
|
Package codereview is a second agent reviewing the work of a tab's own. |
|
config
Package config reads ~/.config/nerdr/config.toml.
|
Package config reads ~/.config/nerdr/config.toml. |
|
denied
Package denied keeps what nerdr was turned down when it tried: a program it ran that said so (permission denied, a sandbox's "BLOCKED by sandbox", a proxy's Forbidden), a file or socket it could not make for lack of permission.
|
Package denied keeps what nerdr was turned down when it tried: a program it ran that said so (permission denied, a sandbox's "BLOCKED by sandbox", a proxy's Forbidden), a file or socket it could not make for lack of permission. |
|
detect
Package detect classifies what a coding agent is doing from what it has drawn on its screen: working, blocked on a question, or idle at its prompt.
|
Package detect classifies what a coding agent is doing from what it has drawn on its screen: working, blocked on a question, or idle at its prompt. |
|
editor
Package editor opens a file, or a whole worktree, in the user's editor.
|
Package editor opens a file, or a whole worktree, in the user's editor. |
|
github
Package github fetches pull-request status (reviews, checks, comments) for a worktree's checked-out branch via the `gh` CLI, the same way the git package shells out to `git` — no API tokens to manage, it uses whatever `gh auth` session the user already has.
|
Package github fetches pull-request status (reviews, checks, comments) for a worktree's checked-out branch via the `gh` CLI, the same way the git package shells out to `git` — no API tokens to manage, it uses whatever `gh auth` session the user already has. |
|
gitsafe
Package gitsafe runs git in folders an agent can write to.
|
Package gitsafe runs git in folders an agent can write to. |
|
handoff
Package handoff is what a tab's new agent is told of the old one's work when the user switches the agent (ctrl+q a s).
|
Package handoff is what a tab's new agent is told of the old one's work when the user switches the agent (ctrl+q a s). |
|
herdr
Package herdr connects nerdr to herdr when it runs in a herdr pane.
|
Package herdr connects nerdr to herdr when it runs in a herdr pane. |
|
hooks
Package hooks lets herdr's agent integrations report to nerdr.
|
Package hooks lets herdr's agent integrations report to nerdr. |
|
input
Package input splits what is typed between the agent in the active tab and nerdr itself.
|
Package input splits what is typed between the agent in the active tab and nerdr itself. |
|
launch
Package launch starts a program with a window of its own — a browser, an editor — apart from nerdr.
|
Package launch starts a program with a window of its own — a browser, an editor — apart from nerdr. |
|
order
Package order reads the reading order an agent recorded for the change it made: which files carry the change, which ones only follow from it, and what the whole thing is for.
|
Package order reads the reading order an agent recorded for the change it made: which files carry the change, which ones only follow from it, and what the whole thing is for. |
|
plugin
Package plugin reads the plugins that add to nerdr: small programs, each in a folder of its own with a plugin.toml saying what it is for, what it takes and how to run it.
|
Package plugin reads the plugins that add to nerdr: small programs, each in a folder of its own with a plugin.toml saying what it is for, what it takes and how to run it. |
|
proc
Package proc keeps the programs nerdr runs for itself — git, gh, the agents' CLIs asked for their conversations, notifications — off its terminal.
|
Package proc keeps the programs nerdr runs for itself — git, gh, the agents' CLIs asked for their conversations, notifications — off its terminal. |
|
prompts
Package prompts keeps the user's saved prompts: text they type into an agent again and again ("commit, push and open a pull request"), picked from a list with the prefix + l or in F3 rather than written out each time.
|
Package prompts keeps the user's saved prompts: text they type into an agent again and again ("commit, push and open a pull request"), picked from a list with the prefix + l or in F3 rather than written out each time. |
|
safefile
Package safefile reads and writes nerdr's managed files (skills, hooks and plugins) without following symbolic links inside a worktree, blocking on named pipes, or overwriting hardlinked files in place.
|
Package safefile reads and writes nerdr's managed files (skills, hooks and plugins) without following symbolic links inside a worktree, blocking on named pipes, or overwriting hardlinked files in place. |
|
spinoff
Package spinoff is how an agent hands parts of its work to new tabs.
|
Package spinoff is how an agent hands parts of its work to new tabs. |
|
state
Package state saves which tabs are open, so nerdr can be started again after a restart and carry on where it was: the same tabs, in the same worktrees, each agent resuming its conversation.
|
Package state saves which tabs are open, so nerdr can be started again after a restart and carry on where it was: the same tabs, in the same worktrees, each agent resuming its conversation. |
|
store
Package store holds what agents record about a change: where the file lives, and how a line is appended to it safely.
|
Package store holds what agents record about a change: where the file lives, and how a line is appended to it safely. |
|
term
Package term runs a program in a pseudo-terminal and keeps a virtual screen of what it has drawn, so a tab can show the agent and nerdr can read that screen to tell what the agent is doing.
|
Package term runs a program in a pseudo-terminal and keeps a virtual screen of what it has drawn, so a tab can show the agent and nerdr can read that screen to tell what the agent is doing. |
|
usage
Package usage reads how much of their accounts' rate limits the agents have used, and how full each agent's context window is, from what the agents themselves say: codex writes its limits into its conversation logs, and claude gives them to its status line, which nerdr sets to `nerdr hook statusline` (see StatusLine).
|
Package usage reads how much of their accounts' rate limits the agents have used, and how full each agent's context window is, from what the agents themselves say: codex writes its limits into its conversation logs, and claude gives them to its status line, which nerdr sets to `nerdr hook statusline` (see StatusLine). |
|
walkthrough
Package walkthrough keeps the guided walkthrough an agent wrote of the change it made, and turns it into a page to read it in.
|
Package walkthrough keeps the guided walkthrough an agent wrote of the change it made, and turns it into a page to read it in. |
|
watch
Package watch tells when a worktree's change may have moved: a file in it written, created or removed, the index or HEAD updated, or a note or reading order recorded.
|
Package watch tells when a worktree's change may have moved: a file in it written, created or removed, the index or HEAD updated, or a note or reading order recorded. |
|
why
Package why reads the rationale behind a change from notes the agent wrote while making it.
|
Package why reads the rationale behind a change from notes the agent wrote while making it. |
|
workspace
Package workspace finds the repositories nerdr can work on and creates and removes the git worktrees each tab runs in.
|
Package workspace finds the repositories nerdr can work on and creates and removes the git worktrees each tab runs in. |
|
Package skills holds the agent skills nerdr ships — how an agent explains a finished change for the review panel when asked (nerdr-explain), how to split its work off into new tabs (nerdr-spinoff), and how to hand its work to the agent its tab is switched to (nerdr-handoff), and how to have a second agent review its work (nerdr-request-review), how to send a message to another agent of the same tab and start more (nerdr-send), how to see and use the rest of nerdr (nerdr-tools), and how to find and run the user's plugins (nerdr-plugins) — and puts them where each agent looks for skills.
|
Package skills holds the agent skills nerdr ships — how an agent explains a finished change for the review panel when asked (nerdr-explain), how to split its work off into new tabs (nerdr-spinoff), and how to hand its work to the agent its tab is switched to (nerdr-handoff), and how to have a second agent review its work (nerdr-request-review), how to send a message to another agent of the same tab and start more (nerdr-send), how to see and use the rest of nerdr (nerdr-tools), and how to find and run the user's plugins (nerdr-plugins) — and puts them where each agent looks for skills. |
Click to show internal directories.
Click to hide internal directories.