# Docs · Gerdr

> How to install and use Gerdr, and what it can do: a desktop app for Claude Code / Codex that runs a whole crew of agents at once, builds your own panels, and lets you keep steering from your phone.

Contents

- [01Install](#install)
- [02Getting started](#start)
- [03What it does](#features)
- [04Custom panels](#panels)
- [05Phone & remote access](#remote)
- [06Shortcuts](#keys)
- [07More](#more)

DOCS / DOCUMENTATION

# 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.

You don't really need these docs

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.

1Install

[Download and install](#install)

Or send this to your Claude Code / Codex and let it install it:

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.

Copy this text

2For the rest, just ask

Tell any agent in Gerdr, for example:

Switch to the dark themeInstall the quota meter add-onMake a weekly-report panel for this projectAdd another Claude accountChange the prefix key to ctrl+a

01

## Install

01

Install the agents you want to use

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.

02

Download Gerdr

Everything is in the latest [GitHub Release](https://github.com/gerdr-dev/gerdr/releases/latest):

- **macOS:** `Gerdr-x.y.z-mac-arm64.dmg` for Apple silicon (M1 and later), `mac-x64.dmg` for 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](#remote) first.
- **Browser:** once the command line is installed, any browser can open it (see the next step).

03

Open it

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.

02

## 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.

03

## What it does

One window, a whole crew of agents

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 hand work to each other

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 right in the chat

Images, videos and PDFs from the agent show in the conversation, and clicking a file path opens it. No hunting around in other apps.

Beyond Claude and Codex

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.

[Custom panels\
\
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 →](#panels) [Keep going from your phone\
\
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 →](#remote)

A UI your agent can change

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.

[Add-ons, skills, MCP\
\
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 →](/addons.md)

Agents hear about the outside world

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.

Drive several computers

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.

04

## 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".

What's in a panel

- **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

01

Have the assistant build one from scratch

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:

Make a board listing every running agent in this project and what it's doing. Mark the stuck ones red, and take me to one when I click it.

It writes the page and the functions; you see the result on the left right away. Not happy? Keep talking.

02

Install one someone else made

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](https://github.com/topics/gerdr-panel) topic on GitHub. Installed panels can be updated, and your own changes and data stay.

03

Have an agent install it from the command line

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
```

Example: the Superagent board

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](https://github.com/gerdr-dev/gerdr-panel-superagent), and it's a one-click install from the recommended list.

05

## 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](https://github.com/gerdr-dev/gerdr/blob/main/README.md#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)

01

Install Tailscale on both

Install Tailscale on the computer and the phone, and sign both into the same account.

02

Turn on direct access in Gerdr

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
```

03

Add a DNS record

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.

04

Open it on the phone

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.

Why it connects with no other setup: the domain itself points at the Tailscale address, and Tailscale on the phone is a system VPN, so connections from both the browser and the app go through it to your computer. Conversely, with Tailscale off on the phone the address won't open (at home the Android app can still use the LAN). The address carries `: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.

06

## 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 |

07

## More

- **Full guide:** [the README on GitHub](https://github.com/gerdr-dev/gerdr/blob/main/README.md), 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](https://github.com/gerdr-dev/gerdr/blob/main/docs/API.md).
- **Add-ons:** [what's in the add-on store, and how to write your own](/addons.md).
- **What changed in each version:** [the changelog](/changelog.md).
- **Found a problem?** Open an issue on [GitHub Issues](https://github.com/gerdr-dev/gerdr/issues).

> Full page index: [/llms.txt](/llms.txt)
