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
0600permissions 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.
Metadata
Release files for agentctx 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentctx-0.6.0.tar.gz | 10.0 kB | Without provenance | Details for agentctx-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentctx-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for agentctx-0.6.0-py3-none-any.whl |
Total release size: 21.7 kB
Release files / agentctx-0.6.0.tar.gz
| Download URL | agentctx-0.6.0.tar.gz |
|---|---|
| Size | 10.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
55718b17641a3ad99dc5bb89635057ec0ecf384f147d4590dd12b2decdeb8e27
|
|
BLAKE2b-256 checksum How to use checksums |
d6da7fc0fd51a85e73336ce77ce113e24b4f4b43031b4a96c733dcbdc7ed0e5f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.3.2 CPython/3.14.6 Darwin/24.1.0
|
Release files / agentctx-0.6.0-py3-none-any.whl
| Download URL | agentctx-0.6.0-py3-none-any.whl |
|---|---|
| Size | 11.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6da9a105009c92929ac25f9af19a45b9689b37cec97563cbb8aa5d7f371c74e6
|
|
BLAKE2b-256 checksum How to use checksums |
883d67596ef075603cba6b818ebfe02d7de3fab6a40ceb31804a4b453497bece
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.3.2 CPython/3.14.6 Darwin/24.1.0
|
Security for agentctx 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.