Stop waiting for your AI agent to finish. Run them all at once.
Each agent gets its own git branch and worktree. Nothing touches main until you say so.
You ask Claude Code to refactor auth. It works for 10 minutes. You wait. Then you ask it to add notifications. It works for 8 minutes. You wait. Then rate limiting. More waiting.
What if all three ran at the same time — each on its own branch — and you just picked the results?
$ agex create --prompt "Refactor auth to JWT"
$ agex create --prompt "Add push notifications"
$ agex create --prompt "Add API rate limiting"
# Go get coffee. Come back to:
$ agex summary --human
agex · 3 tasks · 3 completed
┃ ✓ a1b2c3 completed 12.4s 3/3 +47 -12 JWT auth
┃ ✓ d4e5f6 completed 9.2s 3/3 +31 -8 Push notifications
┃ ✓ g7h8i9 completed 15.1s 3/3 +62 -19 Rate limiting
$ agex accept a1b2c3 d4e5f6 g7h8i9 # merge all three
That's agex. Parallel AI agents, isolated branches, nothing touches main until you say so.
Works with Claude Code, Codex CLI, Copilot CLI, and any agent that runs shell commands.
# Install (pick one)
brew install ruban-24/tap/agex
npm install -g @ruban24/agex
# Start using it immediately — no setup required
cd your-project
agex create --prompt "Add JWT auth with refresh tokens"
agex create --prompt "Add session-based auth with Redis"That's it. agex create works in any git repo — no agex init needed. It bootstraps the workspace automatically on first use.
Want verification, agent hooks, or provisioning? Run agex init to configure them:
agex init # auto-detects project, sets up verify commands and agent skill filesThen just tell your agent:
"Use agex to try 2 different approaches to refactor the auth module, then verify both and merge the best one."
# Check in whenever you want
agex summary --human
# Verify, review, and ship the winner
agex verify <id> --human
agex review <id> --human
agex accept <id> --humanRequires Node.js >= 20 and git.
AI coding agents are fast — but they work on your branch, one task at a time. You're serializing work that could be parallel.
The real cost isn't the agent's time. It's yours — sitting idle while it finishes.
agex gives each agent its own git worktree and branch. They work simultaneously, can't interfere with each other, and nothing merges until you verify and approve.
For you: brew install and start creating tasks. Check in whenever you want with agex summary --human. No setup required — agex create bootstraps automatically in any git repo.
For your agent: JSON-first commands for every step — create, verify, compare, accept, reject. Drop in a skill file with agex init and your agent discovers the workflow automatically.
No cloud. No accounts. No team buy-in needed. Install it, use it. Everything lives locally.
You already use an AI coding agent (Claude Code, Codex, Copilot) and you've hit one of these walls:
- "I have 4 features to ship and my agent does them one at a time" — fan them all out in parallel
- "I want to try 3 approaches and pick the best" — verify all three, merge the winner, reject the rest
- "My agent broke main again" — every task is an isolated worktree, nothing merges until tests pass
- "I want Claude Code to dispatch subtasks to Codex or Aider" — multi-agent orchestration on one codebase
- Trivial single-file edits — just let your agent edit directly
- Strictly sequential tasks — if step 2 depends on step 1, parallelism can't help
- Non-git projects — agex requires git for worktree isolation
Monday morning. You have auth, notifications, and rate limiting to ship this week.
Without agex: you tell your agent to do auth. Wait 10 minutes. Then notifications. Wait 8 minutes. Then rate limiting. Three serial sessions, constant context switching, half your morning gone.
With agex:
# 9:00 — fan out all three
agex create --prompt "Refactor auth module to JWT with refresh tokens"
agex create --prompt "Add push notification service with Firebase"
agex create --prompt "Add Redis-backed API rate limiting"
# 9:02 — go review PRs, write docs, do anything else
# 9:15 — check in
agex summary --human
# All three finished. Two passed verification, one failed lint.
agex accept a1b2c3 # merge auth
agex accept d4e5f6 # merge notifications
agex retry g7h8i9 --feedback "Fix the ESLint errors in rateLimiter.ts"
# 9:20 — three features shipped, one retrying. You haven't written a line of code.This is how the author uses agex daily. Not for demos — for real work.
Git worktrees are great. agex uses them under the hood. But managing parallel agent work with raw worktrees means:
| Without agex | With agex |
 |
|
agex handles what raw worktrees don't:
- Environment setup — copies
.env, secrets, and untracked config files into each worktree - Dependency management — symlinks
node_modulesor runs setup commands automatically - Port conflicts — assigns unique
AGEX_PORTper task so dev servers don't collide - Automated verification — runs your test/lint/build suite before you even look at the results
- Comparison — side-by-side status, checks, and diff stats across all tasks
- Cleanup —
agex rejectoragex cleanremoves worktrees and branches in one step
Add --human to any command for colored terminal output:
Check on all tasks:
$ agex summary --human
agex · 3 tasks
3 tasks · 1 completed · 1 running · 1 failed
┃ ✓ abc123 completed 12.4s 3/3 +47 -12 · 4 files JWT approach
┃ ▶ def456 running 8.1s Sessions approach
┃ ✗ ghi789 failed 15.2s 1/3 +93 -41 · 14 files OAuth approach
Verify a task's results:
$ agex verify abc123 --human
abc123 · verification
✓ npm test (4.2s)
✓ npm run lint (2.1s)
✓ npm run build (6.1s)
All 3 checks passed (12.4s total)
Review changes:
$ agex review abc123 --human
abc123 · JWT approach · +47 -12 across 4 files · 3 commits
COMMITS
a1b2c3d refactor: extract auth middleware
d4e5f6a feat: add JWT token generation
b7c8d9e test: add auth middleware tests
FILES
M src/auth/middleware.ts +18 -4
M src/auth/token.ts +12 -2
A src/auth/jwt.ts +15 -0
M tests/auth.test.ts +2 -6
→ Full review: git diff HEAD...agex/abc123
Compare and decide:
$ agex compare abc123 def456 ghi789 --human
ID Status Checks Changes Duration Prompt
──────────────────────────────────────────────────────────
abc123 completed 3/3 +47 -12 12.4s JWT approach
def456 completed 3/3 +31 -8 9.2s Sessions approach
ghi789 failed 1/3 +93 -41 15.2s OAuth approach
──────────────────────────────────────────────────────────
3 tasks · 2 completed · 1 failed
agex init drops a skill file into your repo so your agent discovers agex automatically. Or install just the skill file with npx skills:
npx skills add ruban-24/agex --skill agex| Agent | Skill file location | Auto-discovered |
|---|---|---|
| Claude Code | .claude/skills/agex/SKILL.md |
Yes |
| Codex CLI | .agents/skills/agex/SKILL.md |
Yes |
| Copilot CLI | .github/skills/agex/SKILL.md |
Yes |
Any agent that can run shell commands works with agex via subprocess mode (--cmd). The skill files above teach agents the full agex workflow — when to use it, how to create tasks, verify, compare, and merge.
All commands output JSON by default — designed for agent consumption. Add --human for colored terminal output when you're checking in.
| Command | Description |
|---|---|
agex init |
Configure agex (optional — create works without it) |
agex create --prompt "..." [--issue <ref>] |
Create an isolated workspace (from prompt, GitHub issue, or both) |
agex exec <id> --cmd "..." [--wait] |
Run a command in a task's worktree |
agex run --prompt "..." --cmd "..." [--wait] |
Shortcut for create + exec |
agex start <id> |
Start dev server in task worktree |
agex stop <id> |
Stop dev server |
agex cancel [id] |
Kill a running or needs-input agent task |
| Command | Description |
|---|---|
agex status <id> |
Get detailed task info |
agex list |
List all tasks |
agex output <id> |
Show captured agent output |
agex summary |
Status breakdown of all tasks |
| Command | Description |
|---|---|
agex verify <id> |
Run verification checks |
agex review <id> |
Diff stats, commits, per-file changes |
agex compare <id1> <id2> ... |
Compare tasks side-by-side |
| Command | Description |
|---|---|
agex accept <id> |
Merge task branch into current branch |
agex reject <id> |
Remove task worktree and branch |
agex retry <id> --feedback "..." |
Retry a failed task with feedback |
agex answer <id> --text "..." |
Answer a question from a needs-input task |
agex clean |
Clean up all finished tasks |
Configuration reference
Create .agex/config.yml (or pass --verify to init):
# Commands to verify task results
verify:
- "npm test"
- "npm run lint"
- "npm run build"
# Files to copy into each worktree (e.g., secrets not in git)
copy:
- ".env"
- "config/local.json"
# Directories to symlink into worktrees (shared, not copied)
symlink:
- "node_modules"
# Commands to run after workspace creation
setup:
- "npm install"agex detects monorepos automatically (pnpm, npm/yarn workspaces, Lerna, Nx, Turborepo, Cargo workspaces, Go workspaces). When detected, agex init prints setup guidance and creates a template .agex/config.yml for you to customize instead of running auto-detection that doesn't understand workspace layouts.
If you skip agex init and go straight to agex create, you'll get a warning on first run with the same guidance.
# Example: pnpm monorepo with packages/api and packages/web
copy:
- .env
- packages/api/.env
- packages/web/.env
symlink: [] # avoid symlinking node_modules in monorepos — hoisting makes it fragile
setup:
- pnpm install # regenerates all node_modules correctly in the worktree
verify:
- pnpm run lint
- pnpm run test
- pnpm run buildWhat to know:
- Don't symlink
node_modulesin monorepos. Usesetup: pnpm install(oryarn install) instead — it regenerates dependencies correctly per the workspace layout. - List each
.envexplicitly. Auto-detection only finds the root.env, not ones nested in packages. - Worktrees are full repo checkouts. Each task gets the entire monorepo, not a single package. This is fine — your agent can be told to work on a specific package via the task prompt.
If no verify commands are configured, agex auto-detects from your project:
| File | Detected commands |
|---|---|
package.json |
npm test, npm run lint, npm run build |
Makefile |
make test |
pyproject.toml |
pytest |
Cargo.toml |
cargo test |
go.mod |
go test ./... |
Package.swift |
swift build, swift test |
project.yml (XcodeGen) |
xcodegen generate, xcodebuild build |
*.xcodeproj |
xcodebuild build |
.swiftlint.yml |
swiftlint |
Subprocess mode (CI, scripting, multi-agent)
You can also orchestrate agex directly. This is useful for CI pipelines, shell scripts, and dispatching multiple different agents on the same codebase.
Key flags:
--prompt "..."— describes the task (used for tracking and comparison)--cmd "..."— the command to run inside the isolated worktree (any CLI tool)--wait— block until the command finishes (without it, the task runs in the background)
# Fan out 3 different agents on the same task
agex run --prompt "JWT auth (Claude)" \
--cmd "claude -p 'refactor auth to use JWT'" --wait &
agex run --prompt "JWT auth (Codex)" \
--cmd "codex -q 'refactor auth to use JWT'" --wait &
agex run --prompt "JWT auth (Copilot)" \
--cmd "copilot-cli 'refactor auth to use JWT'" --wait &
wait
# Compare all three, accept the best
agex compare $(agex list --json | jq -r '.[].id' | tr '\n' ' ')
agex accept <best-id>
agex cleanEach task gets its own environment variables — AGEX_TASK_ID, AGEX_WORKTREE, and AGEX_PORT — so parallel processes can bind to different ports without conflicts.
MCP server for native tool discovery
If your agent or IDE supports Model Context Protocol, you can also expose agex as an MCP server. This is not required — skill files are the recommended path.
{
"mcpServers": {
"agex": {
"command": "agex-mcp",
"args": []
}
}
}Claude Code — add to .claude/settings.json or ~/.claude/settings.json
Cursor — add to .cursor/mcp.json
All CLI commands are exposed as MCP tools.
See CONTRIBUTING.md for development setup and guidelines.
If agex saves you time, star the repo — it helps others find it.