Skip to content
ubgoPublic

About

One CLI for every coding agent and every account: run Claude Code, OpenAI Codex, Gemini CLI and pi on any home and login, bind accounts to project folders, see plan usage and resume conversations. Tokens from gopass, never printed.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

agx

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.

Go 1.26.4+ License: Apache-2.0 Platforms: macOS, Linux, Windows preview Status: pre-release Go Reference

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.

Contents

Why agx

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 (only agx login token prints one, on request).
  • Folder bindings pick the account per repository, per agent: a plain agx run in the client repository uses the client profile.
  • Usage across every home and login at once: agx usage.
  • Teach your agent agx: agx skill --install writes 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 auto on a pool login, agx pool pick --id auto to see the pick and why, ! agx whoami inside 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.

How it compares

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.

Install

go install github.com/ubgo/agx@latest
agx version

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

Quick start

A 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

Supported agents

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.

Commands

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

Architecture

agx architecture: you and your scripts on top, agx resolving and launching, agentio and textdata, then agent homes, binaries and usage endpoints

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.

Documentation

Platforms

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.

FAQ

Which agents and accounts can agx run?

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.

Does agx store, print or refresh my OAuth token?

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.

Is this login billed per use?

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

Does agx change my agent's settings or homes?

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

How does agx pick the account in a folder?

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.

Can I use a token login with Codex?

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

Can agx use a Claude Code apiKeyHelper?

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 console

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

Can I run an agent through a proxy or an API gateway?

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:3128

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

Does agx usage show Gemini CLI, pi or opencode usage?

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.

Can I switch the account of a session that is already running?

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.

Can agx move a running Claude session between accounts automatically?

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.

How does a pool decide, and can I change it?

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.

Does a pool see per-model limits such as Fable's own week?

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.

Which pool command do I use?

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.

  1. 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
  2. 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
  3. 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
  4. 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
  5. Change a running session. When to use it: a session is already open (agx live list shows 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
  6. 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
  7. 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
  8. Which account is my session on? When to use it: inside Claude, whose /status only says apiKeyHelper.

    ! agx whoami
  9. Why didn't it pick carol? When to use it: the pick surprises you; every member is listed with READY, WAIT or skip: 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.

Which account is my Claude session on?

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.

Does agx work on Windows?

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.

Does agx use the network or my quota?

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.

I used agx v0.3. Does my setup carry over?

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.

Moved from khanakia/agx

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, security and license

About

One CLI for every coding agent and every account: run Claude Code, OpenAI Codex, Gemini CLI and pi on any home and login, bind accounts to project folders, see plan usage and resume conversations. Tokens from gopass, never printed.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages