agentctx

agentctx is a kubectx-like CLI for saving and switching local Codex auth profiles.

It manages copies of ~/.codex/auth.json under ~/.agentctx and atomically swaps the active auth file when you switch profiles. When saving the current auth via =., the profile name is derived from the user's email claim in the JWT. Token contents are never printed.

Install

pipx install agentctx

For local development:

poetry install
poetry run agentctx --help

Usage

agentctx                 # list profiles or open fzf selector when interactive
agentctx work            # switch to profile
agentctx login           # run Codex browser login and save auth as JWT email profile
agentctx -               # switch to previous profile
agentctx -c              # show current profile
agentctx =.              # save/rename current Codex auth as JWT email profile
agentctx user@example.com=. # same, but validate name matches JWT email
agentctx prod=work       # rename profile
agentctx -d old-profile  # delete profile
agentctx -u              # unset current marker
agentctx -V              # show version

Long aliases:

agentctx --current
agentctx --unset
agentctx --version

CRUD-style subcommands are intentionally not part of the public CLI.

Storage

~/.agentctx/
  profiles/
    <email-or-name>/
      auth.json
      metadata.json
  backups/
    auth-<timestamp>.json
  current
  previous
  lock

Active Codex auth remains:

~/.codex/auth.json

Security behavior

• validates JSON before saving or switching;
• rejects symlinks and non-regular auth files;
• writes auth files atomically with temporary files in the target directory;
• uses 0600 permissions for active, profile, and backup auth files where supported;
• creates backups before switching profiles;
• never prints token contents.

Development

poetry check
poetry run pytest
poetry build

Publish

make publish

make publish bumps the minor version, syncs agentctx.__version__, runs checks/tests, builds a clean dist/, and publishes with poetry publish.