Skip to content
elentokPublic

About

Agentic development platform for desktop and mobile

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

6,948 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

gx

CI

gx

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 evolve reviews 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.

Disclaimer

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.

Git TUI

  • 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 space for 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 clone clones using the .bare directory trick for a clean layout
  • gx wt list and gx wt abs-path for scripting and shell integration
  • gx log for commit history: amend (A), reword (rw opens $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; ri stashes 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 p in 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 show for single-commit inspection with diff navigation; scroll percentage and search counter (⌕ N/M) shown in the diff panel title
  • gx status interactive 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-diffs config option)
  • gx stash opens 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
  • gx opens status by default, while gx worktrees / gx wt open the worktree UI
  • Press / to search and highlight matching worktrees by name or branch
  • Press g to open the selected worktree in lazygit
  • gx bump creates an annotated version tag with an interactive picker (or pass major/minor/patch directly) and optionally pushes
  • gx doctor checks 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

Screenshots

gx status

screenshot-status

gx wt (worktrees)

screenshot-wt

Requirements

  • Go 1.21+
  • Git
  • tmux (optional, for N and T keybindings)
  • A coding agent for the orchestrator: Claude Code is hosted by gx server itself on the PTY runner (the default); the headless runner is the other choice
  • macOS or Linux. gx server install registers a launchd agent (macOS only)

Installation

Using homebrew:

brew tap elentok/stuff
brew install --cask gx

Using go install:

go install github.com/elentok/gx@latest

A 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 install

Usage

Agent orchestrator

Start 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 once

Run 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 trunk

Web UI

gx 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 code

Git TUI

Run from inside any git repository or bare repo:

gx

This 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 stash

gx 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 ref

Open the interactive staging UI:

gx status

Status 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 with space
  • Discard changes with confirmation (d) in status and diff views
  • Yank content/location/filename with yy / yl / yf; yank for AI agent with ya (wraps diff in a ```diff block 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 / N navigation
  • Vim-like navigation (j/k, G, ctrl+u/ctrl+d co-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 $EDITOR with ee; 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: Sa stashes all tracked changes (staged + unstaged), Ss stashes 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 push

Run the full test suite in a CI-like Ubuntu container:

make test-docker-ubuntu

Stash uncommitted changes, run a command, then auto-pop the stash on success (prompts to pop on failure):

gx stashify git rebase main

Launch 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 lazygit

Directions 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 = true in 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-ghostty for 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 JSON

Bump the version tag (interactive picker if no argument given):

gx bump
gx bump patch   # or minor / major

Check the repo for common configuration issues:

gx doctor
gx doctor --fix   # interactively apply fixes

Print the current binary version:

gx version

Generate a shell-completion script (bash, zsh, fish, or powershell):

gx completion fish | source            # current session
gx completion zsh > ~/.zsh/_gx         # persist

Install (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 file

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

Codex

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 (claude or codex). A ticket's agent: frontmatter overrides it.
  • gx codex doctor runs 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; --json prints the results as JSON.
  • gx codex setup writes the git approval rules that gx relies on. It shows the changes and asks first; --yes skips the question.
  • Codex reads gx's skills from ~/.agents/skills. gx skills install puts them there.
  • Codex runs on the PTY runner.

Configuration

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.

log.important-refs

Each rule is an object with:

  • patterns — list of regular expressions matched against the full ref name
  • color — 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 bindings

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

Stash tab

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

Search mode (after /)

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

Paste mode (after y + confirm)

Key Action
j / ↓ Move down
k / ↑ Move up
p Paste yanked files into selected worktree
esc Cancel and clear clipboard

Development

make test   # run all tests
make run    # run without building

Credits

gx bundles skills adapted from these projects. Each copy lives in skills/ with its upstream, author and MIT license. skills/gx.md lists every skill.

About

Agentic development platform for desktop and mobile

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Contributors

Languages