agentctx

README

agentctx

Switch accounts. Keep using your CLI.

agentctx manages accounts and shows subscription quota for Claude Code and Codex. Select an account with agentctx, then keep working with the normal claude and codex commands. It does not host a chat interface, send prompts, or run an agent loop.

The preview is rendered from the actual list layout using illustrative data. Wide terminals show a compact table for many accounts; narrower terminals use cards.

Install

Requires Go 1.26.5 or later and the native claude and/or codex CLI. macOS and Linux are supported build targets.

go install github.com/kkamji98/agentctx/cmd/agentctx@latest

Add Go's binary directory to your PATH. Enable native account selection and Tab completion in your shell:

# Zsh: add this line to ~/.zshrc
source <(agentctx init zsh)

# Bash: add this line to ~/.bashrc
source <(agentctx init bash)

The shell integration forwards the normal claude and codex commands to the selected profile. Their arguments, terminal interfaces, prompts, permissions, and output remain native. Selection is read when a new CLI process starts.

View your accounts

agentctx
agentctx accounts
agentctx accounts list

Existing local profiles appear automatically as claude-local and codex-local when their native configuration directories exist. No additional login is needed to inspect these profiles.

The list supports many registered profiles, such as claude-a1, claude-a2, claude-a3, codex-c1, and codex-c2.

The example data is illustrative. The list shows sign-in status, plan, quota bars, reset times, and the age of the displayed result. Colors are enabled on a terminal; NO_COLOR=1 disables them.

The normal listing refreshes missing, unknown, expired, or older-than-30-second quota. Fresh cached results are reused. Options:

agentctx accounts --refresh   # Force a fresh lookup
agentctx accounts --cached    # Read cached values only; no network queries
agentctx accounts --json      # Machine-readable output

If a refresh fails, previous quota values retain their original timestamp and are marked stale. A missing value is never treated as unused quota.

Register and select accounts

agentctx accounts add claude claude-a1
agentctx accounts add claude claude-a2
agentctx accounts add claude claude-a3
agentctx accounts login claude-a1
agentctx use claude-a1
claude

For Codex:

agentctx accounts add codex codex-c1
agentctx accounts add codex codex-c2
agentctx accounts login codex-c1
agentctx use codex-c1
codex

Account names are local labels. Each added account has its own native login/configuration directory. Choose the intended account in the native login flow. Existing local configuration is available through the *-local profiles; it is not copied into a newly registered profile.

Selection is independent for each provider:

agentctx current
agentctx use claude-local
agentctx use codex-local

A selection change applies to the next native CLI process. It does not change authentication inside a process that is already running. Automatic migration of a running conversation is not implemented. Use the native CLI's own history/resume features when needed.

Rename an account

agentctx accounts rename claude-a3 claude-a30

Renaming changes the label and selection metadata while keeping the native configuration directory in place. This preserves directory-bound login state, including macOS Keychain lookup. Close that profile's native CLI before renaming it.

Remove an account

agentctx accounts remove claude-a2
# Alias:
agentctx accounts rm claude-a2

Removal unregisters the account and moves its managed profile into removed/ under the state directory. Shared history is retained. If the removed account was selected, that provider returns to its original local profile.

An account in use through shell integration cannot be removed until its native CLI exits. The built-in claude-local and codex-local profiles belong to the native applications and cannot be removed through agentctx.

Removal does not revoke the native login or erase Keychain entries. The archive is retained for recovery and can contain sensitive native state. Keep it private. To restore an archived registration, close relevant native processes and move its directory back to its original storage directory (the parent of home recorded in its account metadata) before selecting it.

Tab completion

Shell integration includes completion for commands, flags, providers, and account names:

agentctx <Tab>                    accounts, use, current, ...
agentctx use <Tab>                registered and local profiles
agentctx accounts login <Tab>     available account labels
agentctx accounts remove <Tab>    removable registered accounts

Completion reads local metadata only. It never performs a quota lookup or login.

For completion without native command integration:

# Zsh: put this file in a directory on fpath, then run compinit
agentctx completion zsh > /path/on/fpath/_agentctx

# Bash
source <(agentctx completion bash)

How quota lookup works

• Codex: native account/read and account/rateLimits/read JSON-RPC requests.
• Claude Code: native auth status --json, followed by the native /usage screen in a PTY. Probes use safe mode and disable tools. The probe waits for the native prompt and never types into onboarding or trust dialogs.
• Matching Claude logins: if an added profile requires first-run setup, the viewer may use an already initialized local login only after the native status reports the exact same non-empty user email and organization ID. Identity metadata is compared in memory and is not cached or logged.

Authentication and quota are shown separately. setup-required means the selected profile needs its native first-run setup. Select it and run claude normally to complete that flow. signed-out, timed-out, and unsupported-view distinguish other failures.

The native CLIs own credentials and refresh behavior. agentctx never reads or copies credential files or Keychain contents. Native lookup formats can change between versions; current compatibility was checked with Claude Code 2.1.263 and Codex CLI 0.153.4.

Storage

State defaults to ~/.local/share/agentctx; override it with AGENTCTX_HOME.

accounts/<storage-id>/account.json   # Registered profile metadata
accounts/<storage-id>/quota.json     # Non-secret quota cache
accounts/<storage-id>/home/          # Native configuration and login state
active.json                   # Selected account for each provider
providers/                    # Shared history for managed profiles
removed/                      # Archived profiles
locks/                        # Native process and registry locks

The built-in local profiles reference the usual ~/.claude and ~/.codex directories. Managed Claude profiles share their projects directory; managed Codex profiles share history and the native SQLite index. Native defaults and managed profiles keep separate authentication.

Do not commit or attach the state directory to an issue. It may contain credentials and native conversation history. agentctx is a local tool with no hosted service.

Development

git clone https://github.com/KKamJi98/agentctx.git
cd agentctx
go fmt ./...
make check

Tests cover selection, renaming, removal, native argument/input forwarding, quota freshness, terminal rendering, completion, and subprocess cleanup. Default tests use synthetic data and no model inference. GitHub Actions runs on macOS and Linux.

The optional Codex initialization smoke check uses an isolated signed-out profile:

AGENTCTX_NATIVE_SMOKE=1 go test ./internal/agentctx -run '^TestNativeCodex' -v -count=1

To regenerate the synthetic README preview after changing the list layout:

AGENTCTX_UPDATE_EXAMPLES=1 go test ./internal/agentctx -run '^TestREADMEAccountExample$'

See CONTRIBUTING.md. Native Windows and fish integration are not implemented.

Migration from 0.1

The initial custom conversation console has been removed. The agentctx claude, agentctx codex, sessions, and resume commands no longer start or manage conversations. Select an account with agentctx use NAME, load shell integration, and run the original native CLI. Existing account registrations, login state, and history are preserved.

Acknowledgments

The Claude quota parser and PTY probe were adapted from aiquota, under MIT. No aiquota installation is required.

References: Codex authentication, Codex app-server, Claude authentication, and Claude sessions.

Independent project; not affiliated with Anthropic or OpenAI. Licensed under MIT.