One CLI for every coding agent and every account on your machine. agx starts Claude Code, OpenAI Codex, Gemini CLI, pi, opencode and any agent you describe in config, on the right home and the right login, and shows you where every decision came from.
agx is an open-source command-line account and launch manager for AI coding agents, written in Go. It runs Claude Code, OpenAI Codex, Gemini CLI, pi and opencode on any of your accounts: several Claude Pro or Max plans, a Codex login, a Gemini API key, a client's account that must be used in the client's repository. It switches the agent's home folder and login per launch, binds accounts to project folders, shows plan usage across every home, finds and resumes conversations wherever they are stored, and passes models, settings, autonomy levels and environment variables the same way for every agent. Tokens come from gopass, a command or an environment variable and are never printed unless you ask with agx login token.
- Why agx
- Install
- Quick start
- Supported agents
- Commands
- Architecture
- Documentation
- Platforms
- FAQ
- Moved from khanakia/agx
- Contributing, security and license
You have two Claude plans, a Codex login, a Gemini key, and a client repository that must always run on the client's account. Every agent stores its login, settings and history in its own home folder, and each one picks a home from a different environment variable. Switching by hand means exporting the right variable, unsetting the ones that would outrank it, and remembering which account you are on.
agx makes that one command:
- Profiles name each home:
agx run --profile work. - Logins run any home on any account:
agx run --profile work --login carol, with the token taken from gopass, a command or a variable and never printed (onlyagx login tokenprints one, on request). - Folder bindings pick the account per repository, per agent: a plain
agx runin the client repository uses the client profile. - Usage across every home and login at once:
agx usage. - Teach your agent agx:
agx skill --installwrites a Claude Code skill listing every agx command and flag, generated from the binary. - Login pools move one Claude session between your and your teammates' accounts by itself as quotas fill:
agx run --login autoon apoollogin,agx pool pick --id autoto see the pick and why,! agx whoamiinside Claude to see the account in use. Every way to use a pool, as copy-paste recipes: Which pool command do I use? - Resume finds the home that stores a conversation:
agx resume --id 3f2a9c1e. - Every option reaches the agent the same way for every vendor: settings, typed options, environment, autonomy levels and raw flags.
What agx never does: guess, discover accounts behind your back, edit an agent's own settings files, refresh an OAuth token, print one unless you ask with agx login token, or run an agent with more autonomy than you asked for.
| agx | Exporting variables by hand | A switcher for one vendor | |
|---|---|---|---|
| Claude Code, Codex, Gemini CLI, pi, opencode and your own agents | yes, one set of commands | yes, a different variable and rule per agent | one vendor each |
| Account chosen per project folder | yes, per agent (agx project use) |
no, unless you add a per-folder tool | varies |
| Shows which source decided each value | yes (--dry-run) |
no | varies |
| Token kept out of your shell and output | yes: resolved at launch, set only in the agent's environment, [redacted] everywhere |
no: the token sits in your shell's environment | varies |
| Plan usage of every home at once | yes, for agents with plan usage (Claude Code, Codex) | no | varies |
| Resume a conversation on the home that stores it | yes (agx resume --id) |
no: you search each home | varies |
| Agent settings files left untouched | yes: options apply to one launch | yes | varies: some switch accounts by rewriting the agent's credential or settings file |
If you only ever use one account of one agent, you do not need agx. Once you have two homes, two accounts or two agents, agx is the one place that decides, and it tells you how it decided.
go install github.com/ubgo/agx@latest
agx versionThis needs Go 1.26.4 or newer and puts agx in $(go env GOPATH)/bin, which needs to be on your PATH.
Prebuilt binaries (macOS and Linux on amd64 and arm64, Windows on amd64) are on the Releases page, with a checksums.txt:
# macOS on Apple Silicon: swap darwin_arm64 for darwin_amd64, linux_amd64 or linux_arm64
curl -fsSLO https://github.com/ubgo/agx/releases/download/v0.4.16/agx_v0.4.16_darwin_arm64.tar.gz
curl -fsSLO https://github.com/ubgo/agx/releases/download/v0.4.16/checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
tar -xzf agx_v0.4.16_darwin_arm64.tar.gz agx && sudo mv agx /usr/local/bin/
agx versionA machine with Claude Code (homes ~/.claude and ~/.claude-work), Codex, Gemini CLI and pi installed, and no agx config yet. Every block below is real output from the example readme-tour, which the test suite runs on a fake machine, so it shows what agx prints today.
Write a config from the homes already on the machine:
$ agx config init --default-agent claude --discovered
wrote ~/.agx/config.jsonc (2 profiles)
$ agx profile list
PROFILE PROVIDER HOME ACCOUNT STATE LOGIN BILLING
*personal claude ~/.claude none home login plan
work claude ~/.claude-work none home login plan
Add a login whose token stays in gopass, then ask what a launch on it would do. --dry-run prints every decision with its source and starts nothing; the token is not even resolved, and the variable it fills reads [redacted]:
$ agx login add --name carol --agent claude --kind oauth-token --token-ref '${gopass:personal/claude/carol}'
added login carol (oauth-token, reference gopass)
$ agx run --profile work --login carol --model opus --dry-run
agx: warning: installed Claude Code version unknown; flags not checked
agent claude from profile work
profile work from --profile
home ~/.claude-work from profile work
login carol (not resolved: --dry-run) from --login
binary /usr/local/bin/claude version unknown from no install metadata
folder ~/projects/client from current folder
options model=opus from --model
run ~/.agx/runs/20261114-101500-k3x9 from AGX_RUN_ID=20261114-101500-k3x9
command claude --model opus from built by agentio
env set AGX_RUN_ID=20261114-101500-k3x9 from launch environment
set AGX_RUN_AGENT=claude from launch environment
set AGX_RUN_PROFILE=work from launch environment
set AGX_RUN_LOGIN=carol from launch environment
set AGX_RUN_HOME=~/.claude-work from launch environment
set CLAUDE_CODE_OAUTH_TOKEN=[redacted] from launch environment
set CLAUDE_CONFIG_DIR=~/.claude-work from launch environment
note installed Claude Code version unknown; flags not checked
(The version warning is there because the fake machine has no install metadata; on a real install that line shows the version and the range agx was tested with.)
Bind this folder to the work profile. A plain agx run here now uses it, and says so:
$ agx project use --profile work
~/projects/client: claude profile work
$ agx run --dry-run
agx: agent claude (folder binding ~/projects/client)
agx: profile work (folder binding ~/projects/client)
agx: warning: installed Claude Code version unknown; flags not checked
agent claude from folder binding ~/projects/client
profile work from folder binding ~/projects/client
home ~/.claude-work from profile work
login home login from default (no login named)
...
The same flags work for every agent. Here Codex starts at the ask autonomy level; the fake codex on the example machine prints the arguments it received:
$ agx profile add --name codex --agent codex --home ~/.codex
added profile codex: codex home ~/.codex (--home), login home login, billing plan, default (first codex profile)
$ agx run --agent codex --autonomy ask
agx: warning: installed codex version unknown; flags not checked against it
agent codex
argv [-s] [workspace-write] [-a] [on-request]
pwd ~/projects/client
...
Without --dry-run, agx replaces itself with the agent: the agent is the process you started, with nothing of agx left in between.
Resume a conversation on the home that stores it, whichever profile you are on:
$ agx conversation list
5 d ago claude work Review the API ~/projects/client 7b1d4e20
8 d ago claude personal Fix the parser ~/projects/client 3f2a9c1e
$ agx resume --id 3f2a9c1e --dry-run
agx: profile personal from home ~/.claude (default)
agx: warning: installed Claude Code version unknown; flags not checked
agent claude from conversation 3f2a9c1e-0000-4000-8000-000000000001
profile personal from home ~/.claude (default)
home ~/.claude from conversation 3f2a9c1e-0000-4000-8000-000000000001 (stored there)
login home login from default (no login named)
...
command claude --resume 3f2a9c1e-0000-4000-8000-000000000001 from built by agentio
...
More at a glance:
agx run # the default profile, the home's own login
agx run --profile work --login carol # the work home, carol's plan token
agx run --agent codex --autonomy ask # Codex at the ask autonomy level
agx run --profile work --dry-run # every decision and its source; starts nothing
agx new --name "pglite golang" # a timestamped scratch folder, agent started in it
agx resume --last # the newest conversation of this folder
agx usage # plan windows of every home
agx usage --cached # the last readings on disk, no network
agx doctor # config, references, binaries, homes, run folders| Agent | Plan usage | Conversations | Token login | Autonomy levels | Per-launch settings | Live login switch |
|---|---|---|---|---|---|---|
| Claude Code | yes | yes | oauth-token, api-key, api-key-helper |
all | yes | yes |
| OpenAI Codex | yes | yes | no (the home's own login) | all but accept-edits |
yes | no |
| Gemini CLI | no | yes | api-key |
all | no | no |
| pi | no | yes | api-key |
read-only, full |
no | no |
| opencode | no | yes (sessions before opencode 1.2.0; newer ones live in its database, not read yet) | no (its per-provider auth.json) |
full |
no | no |
| your own, by config | no | no | no (home login only) | per definition (autonomy_args) |
no | no |
The autonomy levels are default, read-only, ask, accept-edits and full (full needs --consent full-autonomy). A level an agent cannot express exactly is refused, never mapped to a more permissive one. Every missing capability is reported with its reason, never silently skipped: agx agent show --id gemini lists each capability, its cost and why it is missing, and agx agent list shows the agent versions each release was tested with.
Every command takes named flags only; a bare agx, or a bare group such as agx profile, prints help. The command reference lists every flag.
| Command | What it does |
|---|---|
agx run |
Start an agent in the current folder (or --dir); on a pool, --pool-only NAME keeps it on one member within its caps |
agx new |
Create a timestamped session folder and start an agent in it |
agx resume |
Continue a conversation on the home that stores it |
agx whoami |
Profile, login, home and run id of the current session; in a pool session the member in use, a --pool-only pin and the next member |
agx usage |
Plan usage, one row per configured home |
agx conversation |
Conversations stored in agent homes: list, show, move |
agx session |
Session folders made by agx new: list, clean, promote |
agx live |
Running live and pool sessions: list, show, switch the login, pin a pool member with --pool-only |
agx profile |
Profiles, a name for one home plus launch defaults: list, show, add, import, edit, remove, use |
agx login |
Logins, what a launch authenticates with: list, show, add, edit, remove, use, check, token |
agx pool |
Login pools: list, show their settings, pick (which member a pool uses now, and why; --pool-only NAME for one pinned member) |
agx project |
Folder bindings per agent: list, show, use, remove |
agx agent |
Known agents and their capabilities: list, show |
agx doctor |
Local checks: config, references, binaries, homes, run folders |
agx clean |
Delete run folders whose agent has ended |
agx config |
agx's own config file: init, show, path, check, set |
agx alias |
Shell aliases generated by shell-init: list, add, remove |
agx shell-init |
Print the shell layer for zsh, bash, fish or PowerShell |
agx completion |
Print a completion script |
agx skill |
Print a Claude Code skill covering every agx command; --install writes it to ~/.claude/skills/agx/ |
agx help |
Help; --json prints the command tree |
agx version |
Version, build provenance, components |
agx holds no vendor knowledge of its own. Everything about an agent (its home layout, logins, usage endpoints, conversations and launch flags) comes from agentio, so a capability an agent lacks is a typed reason, not a special case. Config files, references and command running come from textdata.
- Learning path: the guides in reading order
- Start from your goal: a table from what you want to the guide, example and decision guide
- Choosing guides: which option fits your case
- Feature index: every feature and where it is documented
- Getting started
- How agx decides
- Passing anything to an agent
- Logins
- Shell layer
- Output,
--fieldand exit codes - Config reference
- Command reference
- Troubleshooting
- Coming from v0.3
- Examples: scripted sessions the test suite runs
macOS and Linux. Windows builds are a preview: there agx stays as the parent of the agent (Windows has no exec), forwards Ctrl-C and returns the agent's exit code.
Claude Code, OpenAI Codex, Gemini CLI, pi and opencode are built in, and any other agent can be described in config under agents.<agent>.spec. Accounts are not limited: every home folder can be a profile, and every token (a Claude plan token, an API key, a key helper) can be a named login that runs on any home of an agent that accepts it.
agx never refreshes an OAuth token and prints one only when you ask: agx login token --id NAME writes that login's token to stdout for a pipe or an apiKeyHelper (refused on a terminal unless you add --reveal). Everywhere else token values read [redacted] in text, --json, --dry-run, errors and logs. A login normally holds a reference (${gopass:…}, $(…) or ${VAR}) that is resolved only when the agent launches, and the token goes to the agent through its environment, never on its command line. agx stores a token value only when you hand it one: a pasted token (agx login add --stdin or the hidden prompt) goes into ~/.agx/tokens.jsonc, written with mode 0600 and refused when group or others can read it, and a plain value you pass to --token-ref is written to config as typed (agx doctor lists such logins). See SECURITY.md.
agx login list says, in its DETECTED column: agx reads the token's public prefix (only the kind word is shown) and reports oauth-token for a setup-token billed to a plan, api-key for an Anthropic API key billed per use, or unknown. A gopass or $(…) reference is resolved for this only with agx login list --verify. An API key filed under kind: oauth-token is marked (mismatch), refused at launch and by the live-login key helper, and never picked by a pool, unless you allow it with --allow-api-key for one run or allow_api_key: true on the login. See Is a login billed per use?.
No settings file is edited: --setting, --option, --env and the rest apply to one launch only, through a file in that launch's run folder or the agent's own flags. agx writes into an agent home only when you ask for it, for example agx conversation move, or agx profile add linking the default home's shared files into a new home (--bare skips that).
From one documented chain: a flag wins, then AGX_LOGIN_<AGENT> and AGX_LOGIN for the login, then the folder's binding, then the profile's and the agent's defaults. Add --dry-run to see each value and its source; whenever something other than a flag decided, agx prints a note on stderr. The full order is in How agx decides.
No. Codex authenticates only through its home (codex login), and naming a stored login for Codex is refused. Use one Codex profile per account: agx profile add --name codex-work --agent codex --home ~/.codex-work, then log that home in with agx run --profile codex-work -- login (Codex's own codex login, run with that profile's CODEX_HOME).
Yes. A login of kind api-key-helper holds the command Claude Code runs to get its API key, and agx passes it as apiKeyHelper in a settings file for that launch only; your settings.json is not edited and the key itself never passes through agx:
agx login add --name console --agent claude --kind api-key-helper --helper-command 'gopass show -o work/anthropic-api-key'
agx run --profile work --login consoleTo use any agx login as the helper, wherever its token lives (gopass, a command, a variable, a pasted token), make the helper agx login token, which prints only that login's token. The login may be a plan token (oauth-token) or an API key: Claude Code accepts either from its helper, which is how --live-login delivers plan tokens:
agx login add --name console --agent claude --kind api-key-helper --helper-command 'agx login token --id work-key'--live-login uses the same mechanism to switch the account of a running Claude Code session. Flags and examples are in the login reference.
Yes, with environment variables; agx has no proxy setting of its own. Set them for one launch with --env or --env-file, or for every launch of a profile with agx profile edit --env; --no-env drops one your shell has set:
agx run --profile work --env HTTPS_PROXY=http://proxy.local:3128 --env NO_PROXY=localhost
agx run --profile work --env-file ./proxy.env
agx run --profile work --no-env HTTPS_PROXY
agx profile edit --id work --env HTTPS_PROXY=http://proxy.local:3128To send Claude Code to another endpoint (an LLM gateway, or a compatible provider such as Kimi) set ANTHROPIC_BASE_URL the same way, for example agx profile edit --id kimi --env ANTHROPIC_BASE_URL=https://api.moonshot.ai/anthropic (see Shared homes); for Codex set openai_base_url with --setting. agx's own requests (agx usage, login probes) follow HTTPS_PROXY, HTTP_PROXY and NO_PROXY from your shell. A value can be a reference such as '$(gopass show -o …)', resolved at launch and redacted in output, and --dry-run lists every variable the agent gets and where it came from. The details are in Launch options.
Not yet. Plan usage is read for Claude Code and Codex. Gemini CLI's quota comes from an API call whose responses are not recorded yet, and pi and opencode have no plan or quota of their own (they bill through each provider's key); each is listed with that reason instead of a number.
For Claude Code, yes: start it with --live-login, then agx live use --id <run> --login <name>; the agent picks up the new login at its next key refresh. The other agents have no setting that re-reads a login while they run, so agx agent show reports live switching as unsupported, with the reason.
Yes, with a login pool: a login of kind pool lists your own Claude logins and your teammates' shared ones, and agx run --login auto starts Claude with agx as its key helper. Each time Claude asks for a key (every minute by default), agx reads the members' usage (one small probe each, cached and shared by every session) and hands out the token of the member with the most room to lose before its weekly reset, using your own accounts almost fully and teammates' only up to their caps, and spreading several sessions over several accounts. agx pool pick --id auto shows the pick and why. To keep one session on one account but within its caps, add --pool-only NAME: it gets no key while that account is over a cap, rather than switching. It is Claude Code only. See Share a pool of Claude accounts.
Every rule is a config value with a default, printed with its source by agx pool show --id POOL: order (urgency: the most room to lose per hour first; or deadline), week_relax_window and week_relax_max (a member's weekly cap rises to 95 over the last 24 hours before its reset), max_sessions (4 sessions per member before the next), sticky and sticky_leave_ratio, the borrow window and the caps (own members 95/98, shared 50/70). There is no strategy switch: agx pool preset --name classic --id POOL writes the rules agx used before v0.4.16 as ordinary keys, and --name recommended writes the defaults. Heavy-use teams can lower teammates' weekly cap to 60 (agx login edit --id POOL --pool-group-cap-week shared=60). See How the pool chooses.
Yes. Claude reports a model's own weekly window only to a probe that asks with that model, so a pool probes with the model the session uses: agx run --model, the profile's model, or the model Claude's own settings choose (what /model saves), else the pool's probe_models. Such a window is an extra weekly cap for that model's sessions only: an account whose Fable week is full is skipped for Fable and still used for Opus. agx pool pick --id POOL --model fable shows it (fable week 80%). See per-model weekly windows.
Every way to use a pool, with the names of the example: your logins alice and bob, teammates' carol, derek and erin, and a pool auto.
-
Switch between accounts by usage. When to use it: the normal way; one session moves between accounts as quotas fill, using your own almost fully and teammates' only up to their caps.
agx run --login auto
-
Pin one account but keep its limits, for every run: a one-member pool. When to use it: a binding, profile or alias should always stay on carol and never go over her caps.
agx login add --name carol-only --agent claude --kind pool --pool-shared carol agx run --login carol-only
-
The same for one session, with no extra pool. When to use it: this run must stay on carol within her caps; the next one uses the pool as usual (more).
agx run --login auto --pool-only carol agx run --login auto --pool-only carol --pool-only-week 50 # and stricter for this run -
Pin one account and ignore its limits. When to use it: you must go on with carol whatever her usage (each rule she breaks is a warning).
agx run --login auto --pool-force carol
-
Change a running session. When to use it: a session is already open (
agx live listshows its RUN id).agx live use --id RUN --pool-only carol # stay on carol, caps enforced agx live use --id RUN --login carol # stay on carol, caps ignored agx live use --id RUN --login auto # back to the pool's rules
-
Leave one account out. When to use it: derek must not be used until you take him back (
--pool-enable derek).agx login edit --id auto --pool-disable derek
-
Lower one account's caps. When to use it: a teammate wants more of her quota kept for herself, for every run (
NAME=removes the entry again).agx login edit --id auto --pool-cap-short erin=40 --pool-cap-week erin=60 --dry-run agx login edit --id auto --pool-cap-short erin=40 --pool-cap-week erin=60
-
Which account is my session on? When to use it: inside Claude, whose
/statusonly saysapiKeyHelper.! agx whoami -
Why didn't it pick carol? When to use it: the pick surprises you; every member is listed with
READY,WAITorskip:and every reason (reading the report).agx pool pick --id auto agx pool pick --id auto --pool-only carol # just carol, with her reasons
| Switches account | Caps enforced | At the cap | |
|---|---|---|---|
agx run --login auto |
yes, by usage | yes | moves to another member; no key when none is usable |
--pool-only carol |
no | yes, the pool's; can be lowered for the run | no key until carol is under her caps |
one-member pool carol-only |
no | yes, that pool's | no key until carol is under her caps |
--pool-force carol |
no | no, each broken rule is a warning | Claude gets 429s from carol's account |
--login carol (or agx live use --login carol) |
no | no, never checked | Claude gets 429s from carol's account |
Every recipe is explained in Share a pool of Claude accounts.
Run ! agx whoami inside Claude. In a pool or --live-login session it shows in use: (the login whose key Claude got last) and next: when a switch is pending. Claude's /status only says apiKeyHelper, and Claude's own guess reads the keychain login, not the key it uses.
Windows builds are a preview until they are verified on a real Windows machine. Windows has no exec, so agx stays as the parent of the agent, forwards Ctrl-C and exits with the agent's exit code. See Troubleshooting.
Launching makes no network request of its own, unless you ask for --auto-profile (reads usage) or --auto-login (probes each login, which spends a few tokens). A session on a login pool probes the pool's members about once a minute, when its cached usage is older than the pool's usage_max_age. agx usage makes one request per home; agx usage --cached reads the last readings from disk. Every command's cost class is in the command reference.
No. This is a clean rewrite with new commands, flags and config, and nothing is converted automatically. Your agent homes and conversations are untouched; recreate profiles and logins with a few commands as shown in Coming from v0.3.
agx continues github.com/khanakia/agx v0.3 under a new module, github.com/ubgo/agx. v0.4 is a clean rewrite on agentio, so every agent works the same way, with named flags only, a typed JSONC config and --dry-run showing where every decision came from. There is no backward compatibility: v0.3 commands, flags, config.yaml and tokens.yaml are gone, and v0.3 is archived. Coming from v0.3 maps every old feature to its new command, and the changelog lists the changes.
- Contributing: build, tests, the docs gates and commit style
- Security policy: how to report a vulnerability and how agx handles tokens
- Code of conduct
- Changelog
- Apache-2.0