{"id":50974392,"url":"https://github.com/coder11125/gmux","last_synced_at":"2026-06-19T06:02:27.197Z","repository":{"id":360936854,"uuid":"1252363073","full_name":"coder11125/gmux","owner":"coder11125","description":"gmux – tmux and git worktrees","archived":false,"fork":false,"pushed_at":"2026-05-28T13:07:08.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T14:22:22.571Z","etag":null,"topics":["ai-agents","aider","bun","claude-code","git","pi","subagents","tmux"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coder11125.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-28T12:53:54.000Z","updated_at":"2026-05-28T13:07:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/coder11125/gmux","commit_stats":null,"previous_names":["coder11125/gmux"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/coder11125/gmux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder11125%2Fgmux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder11125%2Fgmux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder11125%2Fgmux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder11125%2Fgmux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coder11125","download_url":"https://codeload.github.com/coder11125/gmux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder11125%2Fgmux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34519052,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","aider","bun","claude-code","git","pi","subagents","tmux"],"created_at":"2026-06-19T06:02:26.287Z","updated_at":"2026-06-19T06:02:27.191Z","avatar_url":"https://github.com/coder11125.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gmux – tmux + git worktrees for better simultaneous ai agents\n\nLaunch AI agent coding sessions in isolated git worktrees with live tmux monitoring and a full git overlay.\n\n```\ngmux my-feature \"Build a CLI game\" -A codex       # single OpenAI Codex agent\ngmux my-feature \"Build a CLI game\" -A pi          # single pi agent\ngmux my-feature \"Refactor auth\" -A aider -a 4     # 4 aider agents, 4 windows\ngmux my-feature \"Add tests\" -A claude-code -a 4 -p   # 4 claude-code agents, 1 window split 4 ways\ngmux list                                          # show tracked sessions\ngmux doctor                                        # repair stale state\ngmux attach my-feature                             # attach to a running session\ngmux diff my-feature                               # show everything the agent changed vs base branch\ngmux diff my-feature --stat                        # file-level summary only\ngmux update                                          # update gmux to latest version\ngmux git status                                    # show git status for active worktree\ngmux git diff                                      # show diff in a tmux pane\n```\n\n## Features\n\n### Tmux Integration\n- **Session management** — attach, detach, kill, rename sessions\n- **Window management** — create, kill, rename, swap, cycle, and set layouts\n- **Pane management** — split, resize, zoom, join, break panes into windows\n- **Copy mode** — use tmux copy mode (`Ctrl+b [`) for scrolling and text selection\n- **Mouse support** — click, drag, scroll, and resize panes with mouse\n- **Key bindings** — customizable prefix key and command bindings\n- **Status bar** — live session info, git branch, pane dimensions, and clock\n- **Pane synchronization** — type in multiple panes simultaneously\n\n### Git Overlay\n- **Branch display** — see the current git branch for each worktree in the status bar\n- **Diff viewer** — view diffs inline in a tmux pane\n- **Log viewer** — browse commit history with `--graph` and `--oneline`\n- **Blame** — see who last modified each line of a file\n- **Stash management** — push, pop, list, and drop stashes\n- **Conflict detection** — auto-detect merge conflicts and display them with ours/theirs markers\n- **Conflict resolution** — resolve conflicts with `--ours`, `--theirs`, or `--both`\n- **Ahead/behind indicators** — see how many commits you're ahead or behind upstream\n- **File status counts** — staged, unstaged, and untracked file counts at a glance\n\n## How it works\n\n1. `git worktree add -b gmux-\u003cname\u003e` — creates an isolated branch + worktree per agent so no two agents can clobber each other\n2. `ConfigProvisioner` — copies `.env`, lockfiles, runs `bun install` and `.gmux/provision.sh`\n3. `tmux new-window` — opens a new tmux window (or `split-window` with `-p`) with the worktree as its working directory\n4. `tmux send-keys` — dispatches the agent command (`pi`, `aider`, `claude-code`, etc.) into the pane\n5. `SessionStore` — persists state to `~/.gmux/sessions.json`\n6. `ProcessMonitor` — spawns one `gmux-monitor` (Go) process per session; it polls the pane's process tree every 500 ms and writes `idle` to stdout when the agent exits. Falls back to TypeScript polling at 2 s if the binary is not found. Renders a live `[● session]` status bar; teardown fires on idle (merge prompt, worktree removal, window kill).\n\nAny agent that accepts a prompt on the command line works out of the box — **OpenAI Codex**, **pi**, **aider**, **Claude Code**, and more.\n\n## Install\n\n**Prerequisites:** [Bun](https://bun.sh) and [Go](https://go.dev) (≥ 1.21)\n\n```sh\ngit clone https://github.com/coder11125/gmux\ncd gmux\nbun install\nbun run build    # compiles dist/gmux-monitor (Go), dist/gmux-update (Go), then dist/gmux (Bun)\n```\n\nOr link globally:\n\n```sh\nbun link\ngmux my-session \"Fix the bug\"\n```\n\n## Usage\n\n```\nUsage: gmux [options] [command] \u003csession-name\u003e \u003cagent-prompt\u003e\n\nArguments:\n  session-name           name of the agent session\n  agent-prompt           prompt to send to the agent\n\nOptions:\n  -V, --version          output the version number\n  -A, --agent \u003cname\u003e     agent command (overrides .gmuxrc)\n  -a, --agents \u003cnumber\u003e  number of agent instances (default: 1)\n  -p, --panes            show all agents in split panes (one window)\n  --auto-merge           skip merge prompt and auto-merge branches\n  -h, --help             display help for command\n\nCommands:\n  list [options]         List all tracked sessions\n  doctor [options]       Check session state against reality\n  attach \u003csession\u003e       Attach to a running session\n  detach                 Detach from the current session\n  kill \u003ctarget\u003e          Kill a session, window, or pane\n  rename \u003ctarget\u003e \u003cname\u003e Rename a session, window, or pane\n  window \u003caction\u003e        Manage tmux windows\n  pane \u003caction\u003e          Manage tmux panes\n  git \u003caction\u003e           Git overlay commands\n  scripts [name]         Run or list bundled management scripts\n  update [options]       Update gmux from GitHub\n  completion \u003cshell\u003e     Print shell completion script (bash or zsh)\n```\n\n### Subcommands\n\n| Command | Description |\n|---|---|\n| `list` | Table of tracked sessions. `--json` for raw output, `--verbose` for agent/pane/started columns. |\n| `doctor` | Cross-references JSON state against reality. Detects orphaned JSON entries, missing tmux panes, missing worktree dirs, and missing branches. Interactive repair prompt. `--json` outputs issues as JSON. |\n| `attach \u003csession\u003e` | Attach to a running session. Use `-r` for read-only mode. |\n| `detach` | Detach from the current session. Use `--all` to detach from all sessions. |\n| `kill --session \u003cname\u003e` | Kill a session and clean up its worktree. Use `--force` to skip confirmation. |\n| `kill --window \u003cid\u003e` | Kill a specific tmux window. |\n| `kill --pane \u003cid\u003e` | Kill a specific tmux pane. |\n| `rename session \u003cname\u003e` | Rename a tmux session. |\n| `rename window \u003cname\u003e` | Rename a tmux window. |\n| `window list` | List all windows in the current session. |\n| `window create \u003cname\u003e` | Create a new tmux window. |\n| `window swap \u003csrc\u003e \u003cdst\u003e` | Swap two windows. |\n| `window layout \u003ctype\u003e` | Set layout: `even-horizontal`, `even-vertical`, `tiled`, `main-horizontal`, `main-vertical`. |\n| `pane split -d horizontal` | Split the current pane horizontally. |\n| `pane split -d vertical` | Split the current pane vertically. |\n| `pane resize \u003cdir\u003e \u003camount\u003e` | Resize a pane by `up`/`down`/`left`/`right`. |\n| `pane zoom` | Toggle zoom on the current pane. |\n| `pane break` | Convert a pane into its own window. |\n| `pane join \u003csrc\u003e \u003cdst\u003e \u003cdir\u003e` | Join a pane into another window. |\n| `diff \u003csession\u003e [options]` | Show everything the agent changed in its worktree vs the base branch. `--stat` for summary, `--staged` for staged only, `--base \u003cbranch\u003e` to override auto-detected base, `--path \u003cpath\u003e` to restrict, `--no-pager` for raw stdout. |\n| `git status` | Show git status for the active worktree. |\n| `git diff` | Show diff in a tmux pane. |\n| `git log` | Show commit log in a tmux pane. |\n| `git blame \u003cfile\u003e` | Show blame for a file in a tmux pane. |\n| `git stash list` | List all stashes. |\n| `git stash push [-m msg]` | Create a stash. |\n| `git stash pop [index]` | Apply and remove a stash. |\n| `git commit -m \u003cmsg\u003e` | Create a commit in the active worktree. |\n| `git branch \u003cname\u003e` | Create and switch to a new branch. |\n| `git merge \u003cbranch\u003e` | Merge a branch into the current branch. |\n| `completion \u003cbash\\|zsh\u003e` | Print the shell completion script to stdout. Pipe to a file or source directly. |\n| `update` | Update gmux to the latest version from GitHub (`--force`, `--dry-run`, `--version`) |\n\n### Agent selection\n\nSet the agent via `-A`:\n\n```sh\ngmux my-session \"Build a game\" -A codex       # OpenAI Codex\ngmux my-session \"Build a game\" -A pi           # pi\ngmux my-session \"Build a game\" -A aider        # aider\ngmux my-session \"Build a game\" -A claude-code  # Claude Code\n```\n\nAny command that accepts a prompt as an argument works. Use `{prompt}` in `.gmuxrc` if the agent expects the prompt elsewhere (e.g., via flag).\n\nOr set a default in `.gmuxrc` (checked in `cwd` → repo root → `~/.gmuxrc`):\n\n```json\n{ \"agent\": \"aider --message\" }\n```\n\n### Multiple agents\n\n```sh\ngmux my-session \"Build a game\" -a 4              # 4 agents, 4 tmux windows\ngmux my-session \"Build a game\" -a 4 -p           # 4 agents, 1 window with 4 panes\n```\n\nEach agent gets its own unique branch (`gmux-my-session-a3f8c21a`) and worktree, zero file contention.\n\n### Provisioning\n\nFiles listed in `.gmuxignore` are skipped. These are always copied regardless:\n\n`.env`, `bun.lockb`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`\n\nIf `package.json` is detected in the worktree, `bun install` runs automatically.\n\nA user-defined hook at `.gmux/provision.sh` (in the source repo) runs after all copies, receiving the worktree path as `$1`.\n\n### Cleanup\n\nWhen a session finishes:\n1. Prompts to merge `gmux-\u003cname\u003e` into the current branch\n2. Removes the worktree via `git worktree remove`\n3. Prunes stale worktree metadata\n4. Kills the tmux window\n\nPass `--auto-merge` to skip the prompt and merge automatically.\n\n## Configuration\n\ngmux can be configured via `~/.gmux/config.json`:\n\n```json\n{\n  \"prefixKey\": \"C-b\",\n  \"mouseEnabled\": true,\n  \"status_bar\": {\n    \"showGitOverlay\": true,\n    \"showSessionInfo\": true,\n    \"showPaneInfo\": true,\n    \"showClock\": true,\n    \"refreshInterval\": 5000,\n    \"format\": \"{{session}} | {{branch}} {{status}} | {{pane}} | {{clock}}\"\n  },\n  \"gitOverlay\": {\n    \"enabled\": true,\n    \"showBranchInStatusBar\": true,\n    \"showDiffStat\": true,\n    \"autoRefreshInterval\": 10000,\n    \"diffViewerCommand\": \"delta\",\n    \"logViewerCommand\": \"tig\"\n  },\n  \"keyBindings\": [\n    { \"key\": \"r\", \"command\": \"refresh-client\", \"description\": \"Refresh tmux\" },\n    { \"key\": \"g\", \"command\": \"popup gmux git status\", \"description\": \"Git status popup\" },\n    { \"key\": \"d\", \"command\": \"detach\", \"description\": \"Detach session\" }\n  ],\n  \"hooks\": [\n    { \"event\": \"session-start\", \"command\": \"echo 'Session ${SESSION_NAME} started'\" },\n    { \"event\": \"git-commit\", \"command\": \"echo 'Commit in ${WORKTREE_PATH}'\" }\n  ]\n}\n```\n\n### Hook Events\n\n| Event | Description |\n|---|---|\n| `session-start` | Fires when a session is created |\n| `session-end` | Fires when a session ends |\n| `pane-create` | Fires when a pane is split |\n| `pane-kill` | Fires when a pane is killed |\n| `window-create` | Fires when a window is created |\n| `window-kill` | Fires when a window is killed |\n| `git-commit` | Fires after a commit is created |\n| `git-merge` | Fires after a merge completes |\n\n### Hook Context Variables\n\n- `${SESSION_NAME}` — current session name\n- `${WORKTREE_PATH}` — worktree path\n- `${BRANCH_NAME}` — git branch name\n- `${PANE_ID}` — tmux pane ID\n- `${WINDOW_ID}` — tmux window ID\n\n## Scripts\n\ngmux includes bundled scripts for session management, git automation, monitoring, and utilities. Most scripts are written in Python (session, monitoring, utility); only git automation scripts remain in Ruby.\n\n### Running Scripts\n\n```sh\ngmux scripts --list                    # list all available scripts\ngmux scripts \u003cscript-name\u003e [options]   # run a script\n```\n\n### Session Management\n\n| Script | Description |\n|---|---|\n| `cleanup` | Remove stale sessions/worktrees older than N days |\n| `health` | Check session health and repair issues |\n| `export` | Export session configuration (JSON/YAML/TOML) |\n| `stats` | Show session usage statistics |\n\n```sh\ngmux scripts cleanup --max-days 7 --dry-run\ngmux scripts health --repair --verbose\ngmux scripts export --all --format json --output sessions.json\ngmux scripts stats --json\n```\n\n### Git Automation\n\n| Script | Description |\n|---|---|\n| `auto-commit` | Auto-commit changes with smart messages |\n| `branch-cleanup` | Delete merged branches automatically |\n| `conflict-helper` | Interactive conflict resolution |\n| `pr-ready` | Prepare branch for PR (test, lint, push) |\n\n```sh\ngmux scripts auto-commit --all --conventional\ngmux scripts branch-cleanup --merged-only --dry-run\ngmux scripts conflict-helper --auto-resolve ours\ngmux scripts pr-ready --skip-tests --force\n```\n\n### Monitoring\n\nMonitoring scripts are implemented in **Python** for better logging, HTTP/webhook support, and external service integrations. Session and utility scripts have also been migrated to Python for richer stdlib support (`shutil`, `tarfile`, `platform`, `pathlib`). Only git automation scripts (`auto-commit`, `branch-cleanup`, `conflict-helper`, `pr-ready`) remain in Ruby.\n\n| Script | Description |\n|---|---|\n| `watcher` | Monitor agent output for errors (error pattern detection, logging) |\n| `notifier` | Send notifications on session events (webhook, Slack, Discord, Telegram, email, sound) |\n| `logger` | Capture tmux pane output to files (with rotation and compression) |\n\n```sh\ngmux scripts watcher --interval 5 --tail\ngmux scripts notifier --webhook https://hooks.example.com/... --sound\ngmux scripts logger --rotate --compress\n```\n\n### Utility\n\n| Script | Description |\n|---|---|\n| `backup` | Backup sessions and config files |\n| `restore` | Restore from backup |\n| `diagnostics` | System health check |\n\n```sh\ngmux scripts backup --compress --keep-count 10\ngmux scripts restore --list\ngmux scripts diagnostics --verbose\n```\n\n### Script Options\n\nCommon options for all scripts:\n\n| Option | Description |\n|---|---|\n| `--dry-run` | Show what would be done without doing it |\n| `--verbose` | Show detailed output |\n| `--force` | Skip confirmation prompts |\n| `--json` | Output as JSON |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoder11125%2Fgmux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoder11125%2Fgmux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoder11125%2Fgmux/lists"}