Docs
Gerdr is a desktop app for Claude Code and Codex: one window for a whole crew of agents, where you see at a glance who's working and who's waiting on you, and keep steering from your phone when you're away. Free and open source.
All you need is to install Gerdr, and an AI can do that too. After that, whatever you want to set up or use, just ask an agent inside Gerdr: it knows every Gerdr setting and feature, and makes the change for you.
Install Gerdr (https://github.com/gerdr-dev/gerdr) on this computer for me: follow the install instructions in its README, download the right package for my system, install it and open it. If Claude Code or Codex isn't installed or logged in, install it too and tell me how to do the login step.
Install
Gerdr doesn't ship a model of its own; it drives the Claude Code and Codex on your computer. Install them and log in to each once:
curl -fsSL https://claude.ai/install.sh | bash # Claude Code, then run `claude` once to log in npm i -g @openai/codex # Codex, then `codex login`
Only want to use an API like GPT or DeepSeek? That works too: Gerdr has a built-in Gerdr Agent; enter the endpoint and key in Settings.
Everything is in the latest GitHub Release:
- macOS:
Gerdr-x.y.z-mac-arm64.dmgfor Apple silicon (M1 and later),mac-x64.dmgfor Intel; drag it into Applications. If the first launch says the developer can't be verified, right-click it in Finder → Open. - Windows:
windows-x64-setup.exe. The installer isn't signed; if SmartScreen stops it, click More info → Run anyway. - Android:
android.apk. It connects to the Gerdr on your own computer, so set up remote access first. - Browser: once the command line is installed, any browser can open it (see the next step).
Just open the desktop app. Or start the server from the command line and use it in a browser:
gerdr # start the server and print a link with a token gerdr --open # start the server and open the browser gerdr url # print the login link again
The app and the command line can run side by side and see the same sessions. On macOS, turn on Settings → General → Run in background, and agents keep running after you quit the app with ⌘Q.
Getting started
- Start a session: pick an agent and a folder, and go. Below that you'll find the folder's earlier sessions (including Claude Code / Codex sessions started in a terminal); click one to pick it up.
- Talk: Enter sends, Shift+Enter starts a new line; type / for slash commands; paste or drop images straight in.
- Talk while it works, or interrupt: send messages while the agent is working and they join the turn that's already running; Esc interrupts.
- Approvals and questions are cards: approve a command or an edit, answer a multiple-choice question, in one click.
- Rewind: hover over something you said and click ↺ to go back to before it; your words return to the input box to edit and resend. Only the conversation rewinds; files aren't restored.
- Splits: press ctrl+b, release, then v to split side by side or - to split top and bottom, one agent per pane. Whichever is waiting on you is marked in the sidebar and on its pane; ctrl+b o jumps straight there.
- Terminal: ctrl+b t opens one alongside, in the current folder; it survives reloads and follows you to your phone.
What it does
Splits, tabs and workspaces keep a dozen agents tidy. You see at a glance who's working and who's waiting on you, and one key takes you there. Coming from herdr? Same keys, and your layouts import as they are.
Agents can start new sessions, hand out tasks, wait for replies and read the results. Say Claude is editing a page and asks Codex to draw a picture meanwhile; Codex reports back when it's done.
Images, videos and PDFs from the agent show in the conversation, and clicking a file path opens it. No hunting around in other apps.
Several accounts of one agent side by side: when one runs out of quota, switch and keep talking. Plug in any ACP agent (Gemini CLI, OpenCode…), or call the GPT / DeepSeek / Claude APIs directly.
Besides code, every project can have panels of its own: a board, a daily report, a dashboard… A panel is a set of pages with its own assistant. Have an agent build one the way you want it, or install one someone else made.
Learn more →Away from your desk, open the same Gerdr on your phone: check progress, chime in, tap approvals. At home the Android app connects directly over the LAN and gets background notifications.
Learn more →Gerdr's interface is source code. Want a new button, a shortcut, something shown differently? Just tell the agent; it's live as soon as it's saved, no release needed. Break it and an unbreakable rescue panel gets you back.
One-click installs from the add-on store (quota meter, today's spend, saved phrases, Slack…); skills and MCP servers can be global or for one project only.
Learn more →MR comments, finished pipelines and chat messages are recorded as events; panels and sessions can subscribe to them, and replies go back where they came from.
Use another computer's Gerdr from this one: start sessions there, watch its terminals, read its files, and move a conversation over to carry on.
Custom panels
On each project's rail on the left, besides Code (where you write code), you can have a few panels. A panel is a small app: its page on the left, its own assistant on the right. Buttons on the page hand tasks to the assistant, like "write this week's progress up as a weekly report".
- Pages: plain React pages with no build step, refreshed the moment they change; they work on phones too.
- Local functions: code that runs on your computer: read files, call APIs, start new agent sessions. Buttons on the page call them.
- How the assistant works: written in the panel's skills, in your own words; the assistant follows them.
- Schedules and triggers: run every day at a set time, or carry on by itself when an MR gets a comment or someone @-mentions you in chat.
- Its own data and settings: kept in the panel's folder; updating the panel leaves them alone.
Three ways to get a panel
Click the + under the panel buttons on the rail → "New blank panel", then just tell the assistant on the right what you want, for example:
It writes the page and the functions; you see the result on the left right away. Not happy? Keep talking.
The same + has a list of recommended panels, installed with one click; you can also paste any GitHub repository URL. Published panels carry the gerdr-panel topic on GitHub. Installed panels can be updated, and your own changes and data stay.
Whatever you can do in the UI, an agent can do too; just ask. These are the commands it uses:
gerdr panel install owner/repo # install a panel published on GitHub gerdr panel new report # create a blank panel gerdr panel update # update gerdr panel icon report kanban # change its icon
A panel that hands out work for you: write tasks as cards, and it starts agents on them, keeps an eye on progress, and tells you when one is done, stuck, or needs your call. The code is at gerdr-dev/gerdr-panel-superagent, and it's a one-click install from the recommended list.
Phone & remote access
From outside, you go through a cloud relay, encrypted all the way to your own computer; the relay only ever passes ciphertext along. A new device gets in the first time with a pairing code (only someone at the computer can make one), then adds a passkey, so later devices don't need a trip back to the computer.
- Pairing: Settings → Remote access → make a pairing code, scan it with your phone and you're in. A code works once, within 5 minutes.
- Passkey: in Gerdr on your phone, Settings → Remote access → add a passkey.
- Sign out a device: click Sign out in Settings, or run
gerdr remote revoke. - Android app: the same interface as the web, faster at home over a direct LAN connection, with background notifications.
The first time, connect this computer to a relay; the steps are in the README's remote access section. Rather not use a relay? See direct access below.
Direct access: Tailscale or frp instead of the relay
Gerdr only serves one port (7878 by default) with your domain's certificate, under the same pairing-code and passkey rules as the relay; how the phone reaches this computer is up to your own network. You still need a certificate (passkeys only work over HTTPS), but it's issued over DNS, so your computer doesn't have to be reachable from the internet.
With Tailscale (nothing exposed to the internet)
Install Tailscale on the computer and the phone, and sign both into the same account.
Settings → Remote access → Direct access: enter your domain (e.g. gerdr.example.com), leave Port in the address empty, and connect. Then under Certificate below, pick your DNS provider and enter its API credentials; the certificate is issued and renewed by itself.
Rather not click through the UI? Run one command in the computer's terminal instead; it does exactly the same (writes the config, and the running Gerdr picks it up at once; an agent setting this up for you uses it too):
gerdr remote direct gerdr.example.com \ --dns cloudflare \ --env CLOUDFLARE_DNS_API_TOKEN=your-token
An A record: gerdr.example.com → 100.x.y.z, this computer's Tailscale address (shown on the settings page). Only devices in your Tailscale network can reach it.
With Tailscale on, open https://gerdr.example.com:7878 on the phone and scan a pairing code to get in. Enter the same address in the Android app.
:7878 because macOS won't let an ordinary program take port 443 on a specific address.With frp or a router's port forward
In Direct access, set Port in the address to 443 (with the command, add --url-port 443 to the one above), point the A record at the frps machine (or your public IP), and the address is https://gerdr.example.com. frps needs vhostHTTPSPort = 443; add this to frpc:
[[proxies]] name = "gerdr" # pass TLS through untouched; never the https2http plugin type = "https" customDomains = ["gerdr.example.com"] localIP = "127.0.0.1" localPort = 7878 # optional: let Gerdr see the real client IP transport.proxyProtocolVersion = "v2"
- Firewall: the first time, macOS may ask whether Gerdr may accept incoming connections. Click Allow, or the phone can't get in, and nothing tells you why.
- Passkeys in the Android app: with a port in the address, the app can't use a passkey directly (Android only checks the app on 443), so sign-in is approved in the browser instead; or enter the code on the computer under Settings → Remote access → Approve app sign-in.
Shortcuts
Same as tmux / herdr: press ctrl+b, release, then a key from the table below. Works with a Chinese input method on too; all of them can be changed in Settings → Shortcuts.
| v / - | Split side by side / top and bottom |
| h j k l or arrows | Move between panes |
| z | Zoom / restore the current pane |
| x | Close the current pane |
| o | Jump to the session waiting on you |
| u / d | Previous / next session that needs you |
| c / n / p | New tab / next / previous |
| 1 … 9 | Jump to tab N |
| shift+n / w | New workspace / switch workspace |
| g | Session list |
| t | Open a terminal |
| : or ⌘K | Command palette |
| ? | All shortcuts |
More
- Full guide: the README on GitHub, including configuration, environment variables and building from source.
- HTTP API: for scripts, wristbands and other programs that want to watch sessions, send messages or approve things, see docs/API.md.
- Add-ons: what's in the add-on store, and how to write your own.
- What changed in each version: the changelog.
- Found a problem? Open an issue on GitHub Issues.