gx is an agentic development platform for desktop and mobile.
- Autonomous implementation. The ralph loop gives each ticket its own worktree and branch. It runs code review, spec review and verification before the work lands.
- Smart-zone aware agents. gx pauses and compacts a session before its context reaches the smart-zone ceiling.
- Design flow. A full UI takes an idea through a map of decisions and into tickets.
- Agent management. List, prompt, interrupt and resume agent sessions.
- Web UI and terminal UI. The web UI is the main interface, on desktop and mobile. It uses HTTPS and a one-time code from an authenticator app. A terminal UI is also available.
- Budget and notifications. A daily budget caps spend. Telegram or Slack tells you when an agent needs you.
- Resource monitoring. gx watches CPU, memory and disk space, and warns when disk space runs low.
- Learning loop.
gx evolvereviews a finished epic. Follow-ups collect bugs and ideas found along the way, and a triage step goes through them. - Built on popular skills. gx bundles adapted skills from Matt Pocock, Lauren Tan (pstack) and Cursor. See Credits.
- Git TUI. gx is also a git TUI for worktrees, staging, history and stashes.
I wrote the original version of the tool in Typescript a while ago but at some point I realized I wanted something a bit different and had Claude Code migrate it to Go with a lot of UI changes (see convert-to-go.md and go-migration-plan.md). It has since grown into the agent orchestrator described above.
- Browse all linked worktrees in a table with sync status (ahead / behind / diverged) and rebase status relative to main
- Sidebar showing the latest commit (with relative date), commits ahead/behind the remote tracking branch, rebase status relative to main, and uncommitted file changes
- Create, rename, clone, and delete worktrees interactively; select multiple with
spacefor bulk delete with a progress modal (optionally opening a new tmux session or window) - Yank files from one worktree and paste them into another
- Pull, push, and remote-update the selected worktree's branch; pull on a dirty worktree offers to stash first
- Rebase the selected worktree on main (
b), with optional stash-and-restore for dirty worktrees gx wt cloneclones using the.baredirectory trick for a clean layoutgx wt listandgx wt abs-pathfor scripting and shell integrationgx logfor commit history: amend (A), reword (rwopens$EDITOR), interactive rebase (ri), bump version (B), pull (p), and push (P) directly from the log; flashes and re-focuses the entry after amend or reword;ristashes dirty worktrees before launching rebase and prompts to pop the stash when done; commits are colored by status; filter history by file path and line range; yank commit hash (yh), subject (ys), or full message (ym) to clipboard; panel title shows the worktree root- Press
g pin any view (worktrees, status, log, commit) to open the GitHub PR for the current context in the browser; merged commits search by hash, unmerged commits use the branch PR gx showfor single-commit inspection with diff navigation; scroll percentage and search counter (⌕ N/M) shown in the diff panel titlegx statusinteractive status UI with file/hunk/line stage + unstage flows- Inline image diffs: image files are rendered directly in the status diff panel via the kitty graphics protocol on supported terminals (toggle with the
image-diffsconfig option) gx stashopens a Stash tab listing the repo's stashes in a split view — apply (a), pop (p), drop (d), or create (s) a stash, with the selected stash's diff alongside the list- Tabbed UI (worktrees, log, status, stash): switch with
1–4,g w/g l/g s/g S, or,/.; switching is flicker-free and tabs reload only when the repo actually changed gxopens status by default, whilegx worktrees/gx wtopen the worktree UI- Press
/to search and highlight matching worktrees by name or branch - Press
gto open the selected worktree in lazygit gx bumpcreates an annotated version tag with an interactive picker (or passmajor/minor/patchdirectly) and optionally pushesgx doctorchecks for and optionally fixes common configuration issues- Startup check for misconfigured fetch refspec with an option to fix automatically
- Scrollable error modal for any git failures
- See Changelog
gx status
gx wt (worktrees)
- Go 1.21+
- Git
- tmux (optional, for
NandTkeybindings) - A coding agent for the orchestrator: Claude Code is hosted by
gx serveritself on the PTY runner (the default); the headless runner is the other choice - macOS or Linux.
gx server installregisters a launchd agent (macOS only)
Using homebrew:
brew tap elentok/stuff
brew install --cask gxUsing go install:
go install github.com/elentok/gx@latestA go install build has no web UI, because webui/dist is built by make web-build and is not
committed. Use homebrew, a release binary, or make build for the web UI.
make installStart the server (it also installs the skill bundle) and check on it:
gx server start # detached; no-op if it is already running
gx server status # pid, build, web URL, setup code while setup is pending
gx server restart # after upgrading gx
gx server install # macOS: start at login and after a crash
gx server uninstall # macOS: undo install (stops the server, agent holders keep running)Work with tickets, then queue them from the tickets UI or from the CLI:
gx tickets # tickets UI (alias: gx tk)
gx tickets epic ... # create and manage epics
gx tickets add ... # add a ticket
gx tickets show <epic>/<id> # print a ticket, or an epic and its tickets
gx server queue ... # the server-wide queue
gx server one-off ... # a top-level ticket from a prompt, queued at onceRun gx tickets --help and gx server --help for everything else. Other useful commands:
gx agents list # interactive agent sessions
gx designs open ... # an epic's design session
gx budget # today's spend against the soft and hard limits
gx check # the project's format, lint, typecheck and test checks
gx merge # fast-forward an epic or branch onto trunkgx server status prints the web URL (gx server web-url prints just that). The server makes its
own root certificate on first start and serves HTTPS on the web port. Add every host name you use
to server.web.allowed-hosts before the first start, so the certificate covers it, and trust the
root certificate on each device (Settings has the iOS profile and the Mac .cer).
The first visit asks for the one-time setup code from gx server status, then a password of at
least 6 characters, then an authenticator app code. Each device gets its own web login, which ends
after 90 days without use. Set server.web.totp to false for password-only login.
gx server web-logins # list web logins
gx server web-revoke <id> # sign one out
gx server web-password # set a new password, signs everyone out
gx server web-reset-authenticator # clear the authenticator, prints a new setup code
gx server web-reset # clear everything, prints a new setup codeRun from inside any git repository or bare repo:
gxThis opens gx status by default. If launched from inside a worktree, the cursor starts on that worktree.
You can also run the TUI explicitly:
gx worktrees
gx wt
gx log
gx show HEAD
gx stashgx stash opens the Stash tab: a list of the repo's stashes alongside the selected stash's diff. Apply (a), pop (p), or drop (d) the selected stash, or create a new one (s); enter / l focuses the diff panel and t o toggles the split orientation.
Open the log pre-filtered to a single file (equivalent to the status gh mapping; follows renames so pre-rename history is included). The path is taken relative to your current directory:
gx log -f path/to/file.go
gx log --file path/to/file.go HEAD # optionally start at a refOpen the interactive staging UI:
gx statusStatus UI highlights:
- Status tree + split Unstaged/Staged diff panes
- Stage or unstage at file, hunk, or line level
- Visual line-range mode (
v) to stage/unstage selected blocks withspace - Discard changes with confirmation (
d) in status and diff views - Yank content/location/filename with
yy/yl/yf; yank for AI agent withya(wraps diff in a```diffblock with file/line context) - Status header shows branch sync at a glance (
✓,↑N,↓N,↑N ↓N) - Live search in status/diff with highlights and
n/Nnavigation - Vim-like navigation (
j/k,G,ctrl+u/ctrl+dco-scroll) across status, log, and commit views - Mouse wheel scrolling in diff panes (unstaged/staged, including fullscreen) and in log and commit views
- Toggle unified/side-by-side diff rendering with
s(supports hunk, line, and visual actions) - Adjust diff context for the current session with
[/] - File-to-file diff jumps with
,/. - Edit selected file in
$EDITORwithee; open in a horizontal split (es, stacked — like vim:split), vertical split (ev, side-by-side — like vim:vsplit), or new tab (et) - Jump to the top with
g - Open lazygit log with
ol - View the last command output with
oo - Pull/push/rebase/amend/bump actions directly in status (
p/P/b/A/B) with confirmations; push confirms first, then checks divergence if needed - Stash directly from status:
Sastashes all tracked changes (staged + unstaged),Ssstashes only staged changes — both prompt for an optional name first - Push divergence flow uses a menu (type to filter,
ctrl+n/ctrl+p+enter) with relative commit times - Push in status detects GitHub PR URLs and asks whether to open them
- Keyboard help overlay (
?) and full git-error overlay - Live action output overlay with cancellation (
ctrl+c) - Fullscreen diff hides the status pane
- Focus refresh keeps your diff scroll position
Clone using the .bare directory trick and bootstrap the initial worktree:
gx wt clone <repo-url> [directory]This creates:
my-repo/
.bare/ ← bare git repo
.git ← gitdir: ./.bare
main/ ← initial worktree
List worktree names or get the absolute path of one (useful for scripting):
gx wt list
gx wt abs-path <name>Push current worktree branch; gx confirms first, then checks for divergence before pushing:
gx pushRun the full test suite in a CI-like Ubuntu container:
make test-docker-ubuntuStash uncommitted changes, run a command, then auto-pop the stash on success (prompts to pop on failure):
gx stashify git rebase mainLaunch a command (or your $SHELL) into a tmux, kitty, herdr or Ghostty split or tab, falling back to running in place when no multiplexer is available:
gx term # shell, split below (default)
gx term --below nvim # nvim in a split below, in the current dir
gx term --right lazygit # lazygit side-by-side
gx term --tab npm test # npm test in a new tab
gx term --here ls # run in the current terminal (exec-replace)
gx term --cwd /some/dir lazygitDirections are named by visual outcome (--right/--below/--tab/--here), so the same flag produces the same layout on tmux and kitty (which use opposite hsplit/vsplit conventions internally). --below is the default. Splits need tmux, kitty with remote control enabled, herdr, or Ghostty on macOS (1.3.0+); on a plain terminal (or kitty without remote control) the command runs in place instead. So does Ghostty older than 1.3.0, or Ghostty when Automation permission is denied or macos-applescript is off. This way the same invocation works everywhere.
Ghostty is detected from TERM_PROGRAM=ghostty and driven through AppleScript:
- Ghostty needs
macos-applescript = truein its config. - macOS asks for Automation permission the first time gx controls Ghostty. Allow it.
- If a split fails, gx prints a short hint. Run
gx doctor --check-ghosttyfor a live, read-only probe. - On Linux, Ghostty is treated as a plain terminal.
An explicit command keeps its pane open if it fails; a bare shell does not. With no command, gx term opens $SHELL.
The headline use case is launching things from neovim. For example, open lazygit in a split below the editor:
nnoremap <leader>gg <Cmd>!gx term --below lazygit<CR>Manage config (create, edit, inspect):
gx config edit # open config in $EDITOR (creates it if missing)
gx config show # print the effective (merged) config as JSON, secrets redacted (--reveal shows them)
gx config get <key> # print one value, e.g. skills.code-review (secret keys need --reveal)
gx config defaults # print the built-in default config as JSONBump the version tag (interactive picker if no argument given):
gx bump
gx bump patch # or minor / majorCheck the repo for common configuration issues:
gx doctor
gx doctor --fix # interactively apply fixesPrint the current binary version:
gx versionGenerate a shell-completion script (bash, zsh, fish, or powershell):
gx completion fish | source # current session
gx completion zsh > ~/.zsh/_gx # persistInstall (or refresh, after upgrading gx) gx's built-in agent skill bundle for Claude and Codex:
gx skills install # install/upgrade for both agents
gx skills install --dev # link this checkout's skill directories
gx skills install --force <relative-path> # replace a specific detected conflict
gx skills uninstall # remove gx's managed copies
gx skills uninstall --force <relative-path> # remove a specific locally-modified fileEach target is reported as installed, updated, skipped (already up to date), conflicted
(locally modified or unrelated content is left untouched — pass --force <relative-path> to
override), or removed. gx server start and gx server restart run this install for you and
keep a --dev install linked to its recorded checkout. Claude discovers skills under
~/.claude/skills; Codex uses ~/.agents/skills. Switching mode or checkout requires force.
If a gx skill also exists under $CODEX_HOME/skills, install prints a warning: skills: line,
because Codex would find it twice; gx never deletes it. Changes retain recovery backups under gx's data directory. See skills/gx.md for
migration, ownership and recovery details.
gx can run agents under Codex as well as Claude. Codex 0.166.0 or newer is required.
- Pick the Default harness in Settings > Agents, or with the TUI "Default harness..." command. The
config key is
agents.default-harness(claudeorcodex). A ticket'sagent:frontmatter overrides it. gx codex doctorruns short canned Codex sessions and prints one PASS, FAIL, WARN or SKIP line per check. Run it after each Codex upgrade.--record <dir>saves the raw PTY frames and rollouts;--jsonprints the results as JSON.gx codex setupwrites the git approval rules that gx relies on. It shows the changes and asks first;--yesskips the question.- Codex reads gx's skills from
~/.agents/skills.gx skills installputs them there. - Codex runs on the PTY runner.
Optional config file at ~/.config/gx/config.json (run gx config edit to open it).
| Key | Type | Default | Description |
|---|---|---|---|
use-nerdfont-icons |
boolean | true |
Enable Nerd Font pill-shaped badges and icons throughout the UI. |
image-diffs |
boolean | true |
Render inline image diffs (via the kitty graphics protocol) in the status diff panel on supported terminals. |
stage-diff-context-lines |
integer (0–20) | 1 |
Number of context lines shown around each diff hunk in the staging view. |
input-modal-bottom |
integer | "N%" | "center" |
"5%" |
Vertical position of text-input overlays. An integer is a fixed line count from the bottom; a percentage string (e.g. "10%") is relative to screen height; "center" centers the overlay. |
name-aliases |
object | {} |
Map of exact worktree full-names to display aliases, applied before the normal dash-segment compression. |
execution-queue.max-agents-per-epic |
integer (≥1) | 2 |
Maximum agents that may run concurrently within one epic. |
execution-queue.max-one-off-agents |
integer (≥1) | 3 |
Maximum agents that may run concurrently across one project's one-off tickets. A project's project.json can override it. |
execution-queue.retry-storm-launches |
integer (≥1) | 3 |
Consecutive failed launches of one ticket before it is paused as retry-exhausted. |
execution-queue.spin-cycles |
integer (≥1) | 3 |
Pause/re-claim cycles of one ticket within spin-window before it is quarantined as spinning. |
execution-queue.spin-window |
duration string | "5m" |
Window for counting spin-cycles (Go duration, e.g. "90s"). Unparsable or non-positive values keep the default. |
execution-queue.waiting-slot-grace |
duration string | "10m" |
How long a waiting agent counts toward the slot caps before it releases its slot and stays alive. Unparsable or non-positive values keep the default. |
execution-queue.max-released-agents |
integer (≥0) | 5 |
Maximum waiting agents that hold a released slot at once, across projects. The next waiting agent keeps its slot. 0 disables release. |
agent-runner |
"auto" | "pty" | "headless" |
"auto" |
How gx hosts agents. auto picks the PTY runner (the default) when claude is on PATH. A stored herdr is read as auto, with a warning. Read when the server starts. |
runner-wait |
duration string | "5s" |
N, the wait the agent runners bound their guards by (busy guard, / idle-after-N, Interrupt). Go duration, e.g. "10s"; unparsable or non-positive values keep the default. Read when the server starts. |
budget.soft-limit |
dollars (float) | 20 |
Estimated API-equivalent-cost soft limit. Set to 0 to disable. |
budget.hard-limit |
dollars (float) | 30 |
Estimated API-equivalent-cost hard limit. Set to 0 to disable. Bumped up to soft-limit on load if it's set at or below a nonzero soft-limit. |
budget.notification-thresholds |
array of dollars (float) | [5, 10, 15] |
Estimated API-equivalent-cost thresholds at which a notification fires. Sorted and deduped on load. |
disk-space.warn-below |
size string | "20G" |
Free space below which gx warns. Sizes are decimal (G is 10^9 bytes); GiB is binary. "0" turns the warning off. Raised to clean-below if it is non-zero and lower. |
disk-space.clean-below |
size string | "10G" |
Free space below which gx runs the cleanup command. "0" turns cleaning off. |
disk-space.cleanup-command |
array of strings (argv) | ["go", "clean", "-cache"] |
The cleanup command, not a shell string. [] turns cleanup off. A project's project.json can replace it ([] turns it off for that project). |
server.web.allowed-hosts |
array of strings | [] |
Host names the web listener accepts besides IP literals and localhost (e.g. a MagicDNS name). Any other Host gets a 403. Reloads without a restart. |
server.web.files.roots |
array of strings | [] |
Extra folders the web UI may show files from, besides project repos, worktrees, the tickets store and temp folders. Edit with gx server files-roots add|remove. |
server.web.totp |
boolean | true |
Whether web login asks for an authenticator code besides the password. Reloads without a restart. |
agents.default-harness |
"claude" | "codex" |
"claude" |
The harness new sessions use. The server will not start when its program is not on PATH (under agent-runner auto or pty). A project's project.json can override it. Reloads without a restart. |
log.important-refs |
array | see below | Rules for highlighting important refs in the log view. Refs matching a rule get a bright colored badge and are sorted to the front; all others get a dim surface badge. |
log.hide-refs |
array of strings | [] |
Regular expressions matched against full ref names. Matching refs are hidden from the log view entirely. Takes priority over important-refs. |
Each rule is an object with:
patterns— list of regular expressions matched against the full ref namecolor— badge color: a named Catppuccin color (blue,green,yellow,orange,mauve,teal,red,surface) or a hex value (#rrggbb)
Rules are evaluated in order — the first match wins. The rule order also controls sort priority: refs matching earlier rules appear first in the badge list.
Default:
[
{
"patterns": ["^main$", "^master$", "^origin/main$", "^origin/master$"],
"color": "yellow"
},
{ "patterns": ["^v\\d"], "color": "blue" }
]Example config:
{
"$schema": "https://raw.githubusercontent.com/elentok/gx/main/docs/config-schema.json",
"use-nerdfont-icons": true,
"stage-diff-context-lines": 3,
"execution-queue": {
"max-agents-per-epic": 2
},
"budget": {
"soft-limit": 20,
"hard-limit": 30,
"notification-thresholds": [5, 10, 15]
},
"log": {
"important-refs": [
{
"patterns": ["^main$", "^master$", "^origin/main$", "^origin/master$"],
"color": "yellow"
},
{ "patterns": ["^v\\d"], "color": "blue" },
{ "patterns": ["prod", "staging"], "color": "#fab387" }
],
"hide-refs": ["^origin/HEAD$"]
}
}A project's project.json (in the ticket store) has its own schema. gx writes it into every
project.json it creates or rewrites:
{
"$schema": "https://raw.githubusercontent.com/elentok/gx/main/docs/project-schema.json"
}| Key | Action |
|---|---|
j / ↓ |
Move down |
k / ↑ |
Move up |
n |
New worktree |
N |
New worktree and open a tmux session (switches to it) |
T |
New worktree and open a tmux window |
space |
Toggle worktree selection for bulk operations |
d |
Delete selected worktree(s) (and their branches); shows progress modal for bulk deletes |
r |
Rename selected worktree and branch |
c |
Clone selected worktree (copies uncommitted files) |
y |
Yank files from selected worktree into clipboard |
p |
Pull selected worktree's branch (stash prompt if dirty) |
P |
Push selected worktree's branch (confirms before pushing) |
b |
Rebase selected worktree on main (stash prompt if dirty) |
g g |
Jump to the top of the worktree list |
g p |
Open the GitHub PR for the selected worktree in browser |
oo |
View output log of the last job |
ol |
Open lazygit log for the selected worktree |
ot |
Open a tmux session in the selected worktree |
/ |
Search worktrees by name or branch |
t |
Track remote branch (set upstream) |
R |
Refresh worktree list and statuses |
U |
Run git remote update and refresh |
? |
Toggle full help |
q / Ctrl+C |
Quit |
| Key | Action |
|---|---|
j / k |
Move down / up through stashes |
enter / l |
Focus the diff panel for the stash |
a |
Apply the selected stash |
p |
Pop the selected stash |
d |
Drop the selected stash |
s |
Create a new stash |
t o |
Toggle split orientation |
esc / q |
Return focus to the list / leave the tab |
| Key | Action |
|---|---|
| (type) | Filter and highlight matches |
ctrl+n |
Jump to next match |
ctrl+p |
Jump to previous match |
enter/esc |
Exit search, keep cursor position |
| Key | Action |
|---|---|
j / ↓ |
Move down |
k / ↑ |
Move up |
p |
Paste yanked files into selected worktree |
esc |
Cancel and clear clipboard |
make test # run all tests
make run # run without buildinggx bundles skills adapted from these projects. Each copy lives in skills/ with its upstream, author and MIT license. skills/gx.md lists every skill.
- Matt Pocock, from mattpocock/skills: to-tickets, tdd, implement, research, prototype, wayfinder, to-spec, domain-modeling and grilling. The merge-conflict skill started there too.
- Lauren Tan, from
pstackin cursor/plugins: unslop. - Eric Zakariasson, from
cursor-team-kitin cursor/plugins: thermo-nuclear-code-quality-review. - Anthropic, from
plugins/pr-review-toolkit/agents/in anthropics/claude-plugins-official (Apache-2.0): code-reviewer, silent-failure-hunter, type-design-analyzer, comment-analyzer and pr-test-analyzer. - Anthropic, from
.claude/commands/security-review.mdin anthropics/claude-code-security-review (MIT): security-review.

