Documentation
Coderex v0.3.8 · updated 21 September 2026
What Coderex is, how to install it, and the full reference for the
coderex command that scripts and agents drive it with.
What is Coderex?
Coderex is a terminal built for running several AI coding agents at once. The agents are the ordinary command line tools you already use, Claude Code, Codex, Gemini CLI, OpenCode and anything else that runs in a shell. Coderex is not an AI assistant and never talks to a model itself. It gives those tools somewhere to live.
Starting a dozen agents is easy. The hard part is knowing which one is waiting on you, so that is what Coderex is built around. Sessions group into workspaces down the side, each one a tab you can name, color and collapse. An agent that finishes or gets stuck raises a notification, the tab grows a dot, and clicking it takes you straight there.
Everything the app can do it can also do over a local socket, which is
what the coderex command below speaks. That means a script,
or another agent, can list your tabs, read a screen, type into a shell
and start new agents. Your terminals run on your own machine; turn on
Remote Control and you can reach the same session from a browser
anywhere, encrypted end to end.
FAQs
- Is Coderex an AI tool?
- No. It runs agents, it does not contain one. There is no model behind Coderex and no prompt going anywhere. The agents are programs you install yourself and pay for yourself.
- Which agents work with it?
- Claude Code, Codex, Gemini CLI and OpenCode have a launcher built in, with their flags. Anything else that runs in a terminal works too, because a tab is a real shell.
- Does Coderex see my code?
- No. Your terminals run on your own computer. A remote session is encrypted end to end between your machine and your browser, so the relay that carries it cannot read what it passes on.
- Do I need an account?
- Not for the desktop app, which is free forever and asks for nothing. You only sign in to use Remote Control, because that needs to know which machines are yours.
- Do my agents keep running when I close the window?
- With Remote Control on, yes. The app then runs as a client of a background daemon that owns the sessions, so closing the window leaves them running. With it off, everything stops with the app.
- Which platforms can I run it on?
- macOS on Apple Silicon, and Linux on x86_64 as an AppImage. Servers and arm64 Linux run the headless daemon and CLI. Windows is not ready yet.
Install
The CLI ships inside the desktop app. Installing Coderex links
coderex into ~/.local/bin (Homebrew links it
into its own bin instead), so it is on your
PATH in a new terminal. Grab the signed
.dmg, or use Homebrew:
The full name is deliberate: it taps and trusts in one step. Homebrew
won't load a cask from a third-party tap until you trust it, so the
shorter brew install --cask coderex would actually need
three commands (tap, trust, then install).
Linux
The desktop app ships as an AppImage for x86_64, on Wayland and X11. Make it executable and run it — there is no installer:
It registers a desktop entry and icon on first run, so it appears in your launcher and dock like any installed app.
The AppImage carries the app only. Unlike the macOS build it does
not put coderex on your PATH, because
an AppImage is mounted at a temporary path that disappears when the app
exits — a link into it would break the moment you quit. For the
CLI on the same machine, run the headless installer below; the two share
one socket and one set of tabs.
Headless
On a server, on arm64, or anywhere you want the daemon and CLI without the GUI, install the headless build. Same binary, no app:
It installs a single coderex binary to
~/.local/bin. No sudo, nothing outside that directory, no
background agents. The download's SHA-256 is verified against a published
checksum before anything is unpacked; a mismatch aborts without installing.
Rather read it first? Sensible, and the correct instinct with any
curl | sh:
| Variable | Meaning |
|---|---|
CODEREX_INSTALL_DIR | Where to put the binary. Default ~/.local/bin. |
CODEREX_VERSION | Pin an exact version instead of the latest stable. Only reaches releases that carry signed metadata. The installer will not install a build whose signature it cannot check. |
Verify it's wired up:
Quick start
Start an agent, tell it what to do, and read what it said back:
agent start opens a new tab, launches the agent
in it, and prints that tab's surface id, which is why command substitution
works. Every later command takes that id via --surface.
How it works
The app (or the headless coderex serve daemon) listens on a unix
socket. The CLI sends one JSON-RPC request per invocation and prints the
result.
The socket path resolves in this order:
$CODEREX_SOCKET_PATH, if set.-
Otherwise a socket inside a per-uid private directory with mode
0700:$XDG_RUNTIME_DIRon Linux (systemd already makes it per-user and 0700), else<temp_dir>/coderex-<uid>/.
Every terminal Coderex opens gets $CODEREX_SOCKET_PATH and its
own ids injected into the environment. A script running inside a
tab can therefore call coderex with no flags at all, since it
already knows which tab it is. See Environment.
Inspect
coderex ls
Prints the workspace → pane → tab → surface tree.
coderex status
Reports each tab as idle, running (a
foreground program is live in it), or attention, meaning the tab
rang BEL, which is the signal coding agents emit when they're
blocked on you.
| Flag | Scope |
|---|---|
(none) | Every workspace across all windows, plus a totals line. |
--workspace <id> | One workspace's rollup, with a per-tab breakdown. |
--surface <id> | A single tab. Mutually exclusive with --workspace. |
On a terminal you get the readable view:
Pipe it anywhere and you get the raw JSON-RPC result instead, same for every command. See Output & exit codes.
coderex read
Prints a tab's current screen. --ansi keeps the
colour escapes; without it you get plain text.
coderex history
Prints a tab's scrollback. --lines <n> limits
it to the last n lines.
coderex screenshot
| Flag | Meaning |
|---|---|
--format | png (default), json, or ansi. |
--out <path> | Write the PNG to a file instead of stdout. |
Drive a tab
coderex send
Types text into a tab's shell and presses Enter. Pass
--no-enter to leave the line uncommitted.
Everything after the flags is passed through verbatim, so hyphens and quotes survive.
With no text and a pipe on stdin it reads the input instead, which is how a
multi-line prompt reaches an agent without fighting shell quoting or
ARG_MAX:
Agents
Supported tools: claude, codex,
gemini, opencode.
coderex agent start <tool>
Opens a new tab, launches the agent, prints the new surface id. Flags after the tool name are handed to the agent itself:
| Flag | Meaning |
|---|---|
--workspace <id> |
Where to open the tab. Defaults to $CODEREX_WORKSPACE_ID,
else the selected workspace. Must come before the tool name.
|
--no-check | Skip the pre-flight "is this agent installed?" check. Also goes before the tool name. |
coderex agent stop
Terminates the agent's foreground process; the tab stays open.
Defaults to $CODEREX_SURFACE_ID.
coderex agent update <tool>
Runs the agent's own self-update in a new tab and prints its surface id.
coderex agent list
Which agent CLIs are installed on this machine.
Workspaces & tabs
workspace delete and tab close do
not prompt, because confirmation dialogs are GUI-only. Scripts get
exactly what they asked for.
Notifications
coderex notify raises a notification in the app, attributed to
the calling tab automatically. Put it at the end of a long job and your phone
lights up.
notifications accepts --workspace and
--surface to filter.
Resources & usage
coderex resources
System, GPU, and per-process usage. Narrow it with --workspace or
--surface.
coderex usage
AI-agent model and context usage. Claude reports per tab; Codex, Gemini, and
OpenCode report their newest session. --json gives the raw
payload instead of the formatted view; --surface limits Claude to
one tab.
coderex watch
Subscribes to the event stream and prints each event as it arrives, one JSON object per line. Useful as the input to a supervisor loop.
Unfiltered it is a firehose for the whole window: periodic
resources_changed and usage_changed events arrive
whether or not anything happened. Two flags narrow it:
| Flag | Meaning |
|---|---|
--surface <id> |
Only events naming that tab. Window-wide events such as
state_changed carry no surface and are dropped.
|
--type <kind> |
Only these kinds, as they appear in the event field:
pty_output, notification,
state_changed, surface_activity, and so on.
Repeatable.
|
coderex wait
Blocks until a tab reaches a state, so a script does not have to poll. Exits
0 when it does and 4 if it times out, and prints the
state it reached.
| Flag | Meaning |
|---|---|
--for idle | Nothing is running in the tab. The default. |
--for attention | The tab is asking for something. |
--for done |
Either of the above. Use this after starting a command: an agent that
raises a notification reads as attention while its
program is still up, so --for idle would keep waiting.
|
--timeout <secs> | 0, the default, waits indefinitely. |
coderex exec
Send, wait for it to finish, print the screen — one call instead of three.
This reports what the screen shows once the program stops.
It is not the program's exit status, which the CLI cannot see through a
PTY — so coderex exec "npm test" will not tell you whether the
tests passed.
Tunnels
A tunnel makes a port on your machine reachable at a public URL. Anyone holding the link can reach it for as long as it is open, so being able to ask what is currently exposed matters.
tunnel ls shows each tunnel's slug, port, and how long it has
been open. A slug together with --all is refused rather than
resolved one way or the other.
Remote devices
| Command | Effect |
|---|---|
disconnect | Ends the live session. The device stays paired and can reconnect. |
revoke | Ends the session and drops the device from the trust set, so it must pair again. |
coderex remote pair is for a daemon running detached — systemd,
nohup, or one the GUI spawned. A daemon started in a terminal
prompts on its own stdin instead. Start it before connecting
the browser: approval requests are pushed events, not a queue, and each
expires after 120 seconds.
Settings & windows
Values are parsed as JSON when they can be, so 14 is a number and
true a boolean, while a bare word such as
coderex-light stays a string. Nothing needs quoting.
tab resize exists because a headless caller has no window to
drag.
Daemon
Terminals are hosted by an engine. On macOS the desktop app runs it in-process by default; turning on Remote Control moves it into a background daemon so your sessions keep running with the window closed. On a server you run the daemon directly:
Manage a running daemon from anywhere:
daemon stop ends every agent the daemon owns. The
coderex binary is GUI-free and builds on any platform,
including a headless Linux box.
Output & exit codes
Commands print human-readable output when stdout is a terminal and the raw JSON-RPC result when it isn't. So this is for you:
…and this is for your script, with no flag to remember:
Exit status is 0 on success. On failure it tells you which
kind, so a script can decide whether retrying makes sense:
| Exit | Meaning |
|---|---|
1 | The app answered, but the command failed. |
2 | You mistyped the command (clap usage error). |
3 | Could not reach the app. It is probably not running. |
4 | The app was reached but did not answer, or a wait timed out. |
5 | That workspace, tab or surface does not exist. |
6 | A parameter was missing or unparseable. |
| Error code | Meaning |
|---|---|
parse_error | The request wasn't valid JSON. |
invalid_request | Malformed request envelope. |
invalid_params | A parameter was missing or unparseable, e.g. a bad surface id. |
not_found | The workspace or surface doesn't exist. |
internal | The app failed to handle it. |
If the app isn't running you get
coderex: could not reach app at <path> on stderr and exit
1.
Shell completions
Generated from the command tree itself, so the script cannot name commands that no longer exist.
These complete subcommand names. Completing tab and workspace ids needs a running daemon to enumerate them, and is not implemented yet.
Global flags
| Flag | Meaning |
|---|---|
--json | Print the raw JSON-RPC result even on a terminal. Piping already does this; the flag is for reading exactly what a script would get. |
--socket <path> |
Talk to a different app instance, overriding
$CODEREX_SOCKET_PATH.
|
Both work before or after the subcommand.
Environment
Coderex injects these into every terminal it opens, so scripts running inside a tab are self-locating.
| Variable | Meaning |
|---|---|
CODEREX_SOCKET_PATH | Overrides the socket location. Read by both the app and the CLI. |
CODEREX_SURFACE_ID |
The calling tab. Used when --surface is omitted by
send, read, history,
screenshot, tab close, and
agent stop.
|
CODEREX_WORKSPACE_ID |
The calling workspace. Used when --workspace is omitted by
tab new, workspace delete, and
agent start.
|
CODEREX_PANE_ID | The calling pane. |
CODEREX_WINDOW_ID | The calling window. |
coderex status deliberately ignores the
$CODEREX_* fallback, so the bare form is always the
every-workspace aggregate rather than "whichever tab I happen to be in".
Recipes
Which agents are blocked on me?
Nudge every idle agent
Ping me when the agent finishes
Run this inside the tab. No ids needed, the environment supplies them: