Documentation

Coderex v0.4.28 · updated 10 November 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, Antigravity, OpenCode, Muse Code, Grok Build 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, its agent mark lights up in the tab's colour, and clicking it takes you straight there. When the agent is asking you something, the dot fades in and out until you answer. With Needs You installed, the agent reports this itself the moment it happens.

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 access and you can reach the same session from a browser anywhere with the Web App, 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, Antigravity, OpenCode, Muse Code and Grok Build have a launcher built in, with their flags. Anything else that runs in a terminal works too, because a tab is a real shell.
How does Coderex know an agent needs me?
Install Needs You from an agent's Coderex Skills in the Agents panel. It adds hooks to that agent's own settings, so the agent tells Coderex the moment it asks for a permission, an approval or an answer, and when it finishes. The tab's dot pulses and its agent mark lights up in the tab's colour. Without the hooks, Coderex reads the agent's own terminal notifications, which some agents send late or not at all.
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 the Web App, because that needs to know which machines are yours.
Do my agents keep running when I close the window?
Yes. Closing a window only hides it, and clicking the Coderex icon brings it back with everything still running. Delete Window ends a window and its agents for good. Quitting Coderex ends them all, and opening it again brings each agent back in its tab, in the same conversation and with the same flags. You can turn that off in Settings ▸ Agents.
Which platforms can I run it on?
macOS on Apple Silicon, Linux on x86_64 through apt, a .deb or an AppImage, and Windows 10 and 11 with an installer (WSL distros open as tabs). Linux servers and arm64 Linux run the headless daemon and CLI.

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:

$ brew install --cask coderexapp/tap/coderex

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

On Ubuntu and Debian, install from the Coderex package repository, so apt upgrade keeps Coderex current with everything else:

$ curl -fsSL https://coderex.com/install.sh | sh -s -- --apt

On any other x86_64 desktop, the same installer without --apt installs the desktop app and the coderex command into your home directory, with no sudo. A .deb and an AppImage are also available. Either way the app appears in your launcher like any installed app, and coderex is on your PATH in a new terminal.

Windows

On Windows 10 and 11, run the installer, or install from PowerShell:

> irm https://coderex.com/install.ps1 | iex

It installs for your user only, into %LOCALAPPDATA%\Programs\Coderex, with no administrator prompt, and adds that folder to your user PATH so coderex works in a new terminal. The script checks the installer's SHA-256 before running it. WSL distros open as tabs of their own; see Workspaces & tabs.

Headless

On a Linux server, on arm64, or anywhere on Linux you want the daemon and CLI without the GUI, the installer picks the headless build by itself when there is no display. --headless forces it:

$ curl -fsSL https://coderex.com/install.sh | sh -s -- --headless

It installs a single coderex binary to ~/.local/bin. No sudo, nothing outside that directory, no background agents. The release metadata's signature is checked and the download's SHA-256 verified before anything is unpacked; a mismatch aborts without installing.

Headless runs on a desktop too: on a computer with a display the installer asks whether you want the desktop app or headless (--headless chooses without asking). To use the computer from the Web App, link it to your account and keep Coderex running with remote on. When the installer finishes it offers to do both: it runs coderex login, and once you approve the code in your browser, it asks whether Coderex should run in the background and start at boot. To do it by hand:

$ coderex login # link this computer; offers the next step
$ coderex daemon install # run in the background, remote on, start at boot
$ coderex remote pair # approve your browser the first time it connects

daemon install sets up a systemd user service, with no sudo. It also turns on linger, so the service keeps running after you log out. Where your distro does not allow that for your user, it prints the one sudo loginctl enable-linger command to run. coderex daemon status shows whether remote is on and whether Coderex starts at boot. coderex daemon uninstall removes the service.

Updating

The desktop app updates itself, and the coderex command with it. On a server, run:

$ coderex update # download, verify, replace, restart
$ coderex update --check # only say whether there is one

It checks the new version's signature the same way the installer does, replaces the binary, and restarts Coderex onto it. It asks first if that would end running agents. A server checks for updates every hour and says when it is behind: in coderex daemon status, and in the Web App's sidebar as "Update available", where Update Now runs coderex update there for you. An apt install updates with sudo apt update && sudo apt upgrade.

Rather read it first? Sensible, and the correct instinct with any curl | sh:

$ curl -fsSL https://coderex.com/install.sh -o install.sh
$ less install.sh && sh install.sh
VariableMeaning
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:

$ coderex ping
$ coderex --help # every command

Quick start

Start an agent, tell it what to do, and read what it said back:

$ SID=$(coderex agent start claude)
$ coderex send --surface "$SID" "fix the flaky test in auth"
$ coderex read --surface "$SID"

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:

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 (shown as "needs you"), meaning the tab has a notification you have not seen yet: its agent finished, or is waiting on you.

FlagScope
(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:

$ coderex status
My Workspace 1 ● 1 needs you ● 2 running ● 3 idle
My Workspace 2 ● 2 idle
 
● 1 needs you ● 2 running ● 5 idle

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

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

$ coderex send --surface "$SID" "npm test"
$ coderex send --no-enter "git commit -m "

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:

$ cat prompt.md | coderex send --surface "$SID"

Agents

Supported tools: claude, codex, agy (Antigravity), opencode, muse and grok. Anything else that runs in a terminal works in an ordinary tab; these are the ones the launcher knows the flags for.

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:

$ coderex agent start codex --yolo --search
$ coderex agent start --workspace "$WS" claude
FlagMeaning
--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. Takes --workspace, like agent start.

coderex agent list

Which agent CLIs are installed on this machine, and where.

When Coderex restarts, each tab that was running Claude Code, Codex, Antigravity or OpenCode starts it again in the same conversation, with the flags it had. The opening prompt is never sent again, and an agent you quit yourself stays quit. Turn it off in Settings ▸ Agents ▸ "Resume agents when Coderex restarts". The flags each agent starts with are set in Settings ▸ Agents, or per workspace in the Agents panel.

coderex agent wait --surface <id>

Waits until the agent in a tab stops working, then prints what happened: done (exit 0), needs-you (3), failed (4), exited (5) or timeout (6). For one agent waiting on another, in place of reading that tab's screen over and over. --next waits for the next turn to end, and --timeout sets the seconds to wait. It needs the tab's agent to report to Coderex: Claude Code started from the Agents panel or agent start does, unless Coderex hooks are turned off (the "Coderex hooks" box in Edit Flags, which adds --no-coderex-hooks to the flags), and so do Claude Code and Codex with Needs You installed. Hooks tell Coderex the moment an agent needs you or finishes; alerts and the queue rely on them.

Queue

Line up prompts for the agent in a tab. Coderex types the next one only when the agent reports that it finished its turn, it is still the program in the tab, and the terminal is quiet. Nothing is typed on a guess, and the queue pauses, saying why, if the agent fails, exits, is stopped by you, or you have left text unsent in its prompt box. Open the Queue module in the side panel, or use coderex queue. Everything a queued prompt can wait for is measured on your computer.

$ coderex queue add "run the tests and fix what fails"
$ coderex queue add "write the daily summary" --at 6:30pm --every weekdays
$ coderex queue add --file prompts/nightly.md --at 02:00 --no-agent-running --every day
$ coderex queue add "review the new commit" --on-commit --every each
$ coderex queue ls

coderex queue add <prompt>

Adds a prompt to the tab's queue (--surface, else this tab). With no condition it is sent when the agent finishes its turn. Give one condition, or two that both have to hold. --file <path> queues a file in place of a prompt, for one too long to type; it is read when the prompt is sent.

ConditionSends the prompt
--at <time>The next time the computer's clock reads that: 14:00, 2pm, 6:30pm
--in-minutes <n>Not before that many minutes from now
--after-tab <id>Once the agent in that tab has finished its turn
--tab-failed <id>Once the agent in that tab has stopped on an error or left
--tab-needs-you <id>Once the agent in that tab has waited for you for --waiting-minutes (5)
--command-exited <id>Once the command running in that tab has ended
--no-agent-runningWhile no agent in any other tab is working
--workspace-idleWhile no agent in another tab of this workspace is working
--after-turns <n>Once that many more turns have finished in the tab
--linked-repliedOnce a linked agent has replied to the tab
--when-freeWhile CPU and GPU are both under 30%
--cpu-under, --gpu-under, --mem-under <pct>While that reading is under the percentage
--tree-clean, --tree-dirtyWhile the tab's folder has no uncommitted change, or has one
--on-commit, --on-branch-changeOnce a commit has landed, or the folder is on another branch
--on-change <path>Once that file, or something directly in that folder, has changed
--port-open, --port-closed <port>While something on the computer listens on the port, or nothing does

--every <how> makes it repeat: hour, day, weekdays, a length such as 30m or 3h, or each for each time its condition comes about. A run missed while the computer slept happens once. --max-runs <n>, --for-hours <n>, --stop-on "<phrase>" (stop once the agent's closing words contain it) and --min-gap <minutes> say when a repeat ends.

coderex queue ls | rm <id> | pause | resume | clear

Show the queue, remove one entry, stop and start sending, or remove every entry. One-off prompts go in order and before any repeat that is due, so a frequent repeat cannot hold them back. Queues are saved and come back after a restart; one that comes back with one-off prompts waits for resume. An entry goes with its tab.

Linked agents

Link a second agent to the one you are working with and the first can consult it: ask a question, have it review the current diff, or hand it a task. Each linked agent runs in a tab of its own, so you can watch everything it does. The commands below are meant to be run by the primary agent from inside its tab, so --surface defaults to $CODEREX_SURFACE_ID throughout.

$ coderex agent link codex # open Codex linked to this tab
$ coderex agent ask --to codex --diff "does this deadlock?"
$ coderex agent delegate --to agy "port the parser to the new API"
$ coderex agent replies --wait

coderex agent link <tool>

Opens the agent in a new tab, linked to this one as an advisor. It sees the questions you send and any diff you attach, and answers back; it does not edit files unless asked to. Flags after the tool name go to the agent, as with agent start (coderex agent link codex -m gpt-5.4-codex). Put --surface before the tool name.

coderex agent unlink <tool>

Ends a link. The linked agent's tab stays open and is told it may work normally again.

coderex agent linked

Which agents are linked to this tab: the tool, its launch flags, and whether it is ready to receive a message. (agent list answers a different question: what is installed on this machine.)

coderex agent ask <question>

Sends a question to your linked agents and prints any replies that have already arrived.

FlagMeaning
--to <tool> Which linked agent. Repeatable. Leave it out to ask every linked agent, which suits a review (several models on one diff) and wastes effort on anything else.
--diff Attach git diff HEAD, staged and unstaged.
--wait Block until they reply or the timeout passes. Without it the call returns at once and answers arrive on a later replies.
--timeout <secs> How long --wait waits. Default 120.

coderex agent delegate --to <tool> <task>

Hands a task to a linked agent. Unlike ask, the linked agent edits files, runs commands and commits, in its own git worktree and branch, and you review the branch when it is done. Write the task so it stands on its own: the delegate starts in a fresh checkout and has not seen your conversation. It runs unattended, so it is launched with that agent's auto-approve flag, and an agent without one is refused rather than left waiting on a prompt nobody will answer.

coderex agent replies

Prints whatever your linked agents have sent back since last time. Takes --wait and --timeout, like ask. It is also how a link that has been lost gets reported.

coderex agent skill install | uninstall | status

Installs, removes or checks the coderex-agent skill (Coderex Agent in Coderex Skills): a short file, per agent, that teaches the primary agent these commands. Only agents installed on this machine get one. A linked agent needs nothing installed, because every message it receives carries its instructions. uninstall only removes files Coderex wrote, and install never overwrites a file it does not recognise.

Coderex Skills

Skills teach your agents what Coderex can do. Open them from the Coderex Skills button in an agent's section of the Agents panel. "What it teaches" shows each skill's text before you install it. Each is installed per agent, either for every project (System) or for just this one (This project, which shows in git). Removing one takes out only Coderex's own files. The same catalog is on the command line, and that needs no running app:

$ coderex skills list
$ coderex skills install coderex-notify --agent claude --agent codex
$ coderex skills remove coderex-notify --scope project
$ coderex skills remove-all # every Coderex skill, everywhere
FlagMeaning
--agent <a> claude, codex, agy, opencode, muse or grok. Repeatable. Leave it out for every agent installed here (install) or every agent that has it (remove).
--scope system (the default) or project. remove also takes old, a copy that 0.4.5 wrote into AGENTS.md or GEMINI.md.
--project <dir> The project folder for project scope. Default: the current folder.
SkillWhat it teaches
coderex-agentCoderex Agent: link other agents, ask them for a review, hand them work. See Linked agents.
coderex-needs-youNeeds You: the agent tells Coderex the moment it needs you or finishes. See below.
coderex-notifyNotify Me: notifications on your computer and phone for whatever you ask, each with its own sound.
coderex-phonePhone-Friendly: short questions and updates that fit a phone screen.
coderex-dev-serversDev Servers: servers and watchers run in their own named tab.
coderex-run-watchRun & Watch: long builds and tests run in a tab you can watch.
coderex-share-previewShare Preview: open a local dev server on your phone through a private link.
coderex-screenLook at the Screen: check what a tab really shows before saying it works.
coderex-tabsTidy Tabs: tabs named and coloured by task, closed when done.
coderex-fresh-startFresh Start: near a full context, write a handoff note and carry on in a fresh agent.
coderex-resourcesResource Aware: check how busy the machine is before heavy jobs.

Needs You

Needs You is not a file the agent reads. Instead it adds hooks to the agent's own settings, so the agent tells Coderex the moment it asks for a permission, an approval or an answer, and when it finishes its turn. The tab lights up and you are notified at once. It installs for System only. Removing it takes out only Coderex's entries and keeps everything else in the file. Outside a Coderex tab the hooks do nothing.

AgentWhere
Claude Code~/.claude/settings.json
Codex~/.codex/hooks.json. Codex asks once, at startup, whether to trust them.
OpenCode 1.x~/.config/opencode/plugins/coderex.js. Restart OpenCode after installing.
Muse Code~/.config/muse/settings.json. Restart Muse after installing.
Grok Build~/.grok/hooks/coderex.json
$ coderex skills install coderex-needs-you --agent claude

The hooks run coderex hook <agent> needs-you|done. It reads the agent's hook input on stdin, prints nothing and always exits 0, so it can never get in the agent's way. When a hook and the agent's own terminal notification report the same thing, you are notified once.

Workspaces & tabs

$ coderex workspace new --title "Acme"
$ coderex workspace delete --workspace "$WS"
$ coderex tab new --workspace "$WS"
$ coderex tab new --title "tests" # beside this tab, in its folder
$ coderex tab set --title "API server" --color "#4f9cf9"
$ coderex tab close --surface "$SID"
$ coderex tab new --wsl Ubuntu # Windows: a tab in a WSL distro

Run from inside a tab with neither --workspace nor --pane, tab new opens the new tab beside that tab, in its folder. --pane opens it in a particular pane, and --title names it. On Windows, --wsl <distro> opens it in that WSL distro, named as wsl --list shows it.

tab set names or colours a tab, the calling one unless you pass --surface. --title "" gives it its automatic name back, and --color none clears the colour. A name you set is kept, even when an agent runs in the tab.

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 the tab, the Dock and any open web app session show it, and your phone too once you have been away from the computer for a couple of minutes: turn that on in the web app's Settings ▸ Notifications. On an iPhone, add the web app to the Home Screen first.

$ npm test && coderex notify "tests green"
$ coderex notify --title "Deploy" --body "shipped v2"
$ coderex notify --sound Dink "deploy finished"
$ coderex notifications # list
$ coderex notifications clear

notifications accepts --workspace and --surface to filter.

--sound plays Bump, Correct, Dink, Electro or Two Note instead of the sound chosen in Settings, or None for silence, so an agent can use a different one for each kind of event. A notification that asks for something (a permission, an approval, "action required", or text ending in a question mark) counts as needs you, and anything else counts as done. Settings ▸ Notifications ▸ When to Notify chooses which of the two makes a banner and a sound. Mute Notifications on a tab or workspace keeps the dot but stays silent.

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, Antigravity 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:

FlagMeaning
--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 watch --surface "$CODEREX_SURFACE_ID"
$ coderex watch --type notification --type surface_activity

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.

FlagMeaning
--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.
--surface <id> Which tab. Defaults to $CODEREX_SURFACE_ID.
--interval <ms> How often to check. Default 400.

coderex exec

Send, wait for it to finish, print the screen. One call instead of three.

$ coderex exec "npm test"

Takes the same --surface, --timeout and --interval as wait, and --ansi to keep the screen's colours.

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.

A tunnel stays open after you close the browser that opened it. Its page pauses after 15 minutes with no one viewing it, so a forgotten tab does not use remote hours, and carries on by itself when someone looks at it again. The tunnel closes when its link expires after 8 hours, when you revoke it, or when Coderex stops on that machine. A closed tunnel whose link has not expired can be reopened from the web app under the same link.

$ coderex tunnel ls
$ coderex tunnel close <slug>
$ coderex tunnel close --all

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

$ coderex remote devices
$ coderex remote disconnect <pin-key>
$ coderex remote revoke <pin-key>
$ coderex remote revoke --all
$ coderex remote pair # approve a new device
CommandEffect
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: the daemon install service, daemon start, nohup, or one the GUI spawned. If remote is off, it says so instead of waiting. 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

$ coderex settings get
$ coderex settings set font_size 14
$ coderex settings set theme coderex-light
$ coderex window ls | new | close <id>
$ coderex tab resize --rows 40 --cols 120

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, and turning on remote access moves it into a background daemon. On Linux and Windows the app always runs it as a background daemon for your user (on Windows, with an icon in the system tray). On a server you run the daemon directly:

$ coderex serve # headless engine + socket
$ coderex serve --remote # also join the E2E-encrypted relay
$ coderex login # link this machine to your account

Manage a running daemon from anywhere:

$ coderex daemon start | stop | restart | status
$ coderex daemon start --remote # also reachable from the Web App
$ coderex daemon install | uninstall # Linux: start at boot
CommandEffect
start [--remote] Starts the daemon in the background. --remote also takes remote sessions, once coderex login has linked the computer. If a daemon is already running with remote off, it says so and how to restart it.
restart [--remote] Stop, then start. If remote was on, it stays on.
status Whether it is running, with how many agents, whether remote is on, and whether it starts at boot. Piped, the raw JSON, which includes "remote".
install Linux: runs coderex serve --remote as a systemd user service that starts at boot. It asks first if a daemon is already running agents, because moving to the service restarts it. With the service installed, start, stop and restart go through it.
uninstall Stops the service and removes it. Only a service Coderex wrote is removed.

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:

$ coderex status

…and this is for your script, with no flag to remember:

$ coderex status | jq '.windows[].workspaces[] | select(.attention > 0) | .title'

Exit status is 0 on success. On failure it tells you which kind, so a script can decide whether retrying makes sense:

ExitMeaning
1The app answered, but the command failed.
2You mistyped the command (clap usage error).
3Could not reach the app. It is probably not running.
4The app was reached but did not answer, or a wait timed out.
5That workspace, tab or surface does not exist.
6A parameter was missing or unparseable.
Error codeMeaning
parse_errorThe request wasn't valid JSON.
invalid_requestMalformed 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.
internalThe app failed to handle it.

If the app isn't running you get coderex: could not reach app at <path> on stderr and exit 3.

Shell completions

Generated from the command tree itself, so the script cannot name commands that no longer exist.

$ eval "$(coderex completions zsh)" # or bash
$ coderex completions fish > ~/.config/fish/completions/coderex.fish

These complete subcommand names. Completing tab and workspace ids needs a running daemon to enumerate them, and is not implemented yet.

Global flags

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

VariableMeaning
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, exec, wait, tab close, tab set, agent stop and the linked-agent commands.
CODEREX_WORKSPACE_ID The calling workspace. Used when --workspace is omitted by tab new, workspace delete, agent start and agent update. (Run from a tab with neither flag, tab new opens beside the calling tab instead.)
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?

$ coderex status | jq -r '.windows[].workspaces[].tabs[] | select(.status=="attention") | .title'

Nudge every idle agent

$ coderex status | jq -r '.windows[].workspaces[].tabs[] | select(.status=="idle") | .surface_id' \
  | while read -r sid; do
    coderex send --surface "$sid" "continue"
  done

Ping me when the agent finishes

Run this inside the tab. No ids needed, the environment supplies them:

$ npm run build && coderex notify "build done" || coderex notify "build FAILED"

Know the moment Claude Code or Codex needs you

$ coderex skills install coderex-needs-you --agent claude --agent codex

Archive a tab's output

$ coderex history --surface "$SID" --lines 500 > run.log
$ coderex screenshot --surface "$SID" --out run.png