Installation

Requirements

Tested requirements: Linux, Bun 1.4.4, and Codex CLI 0.167.2. Authentication uses an experimental RPC; other versions require verification. Browser launching is implemented for macOS but has not been tested. Windows is not supported by this prototype.

The prototype requires file-based authentication. Set the following in ~/.codex/config.toml:

cli_auth_credentials_store = "file"

If you previously used the keyring, sign in again through the official login flow in this mode before using the plugin. The installer does not change this setting or extract credentials from the keyring.

Automatic installation

With Git, Bun, and the official Codex CLI already installed, clone the repository and run the installer:

git clone https://github.com/eduardoaugustolb/codex-accounts.git
cd codex-accounts
./install.sh

No separate dependency-install step is needed. The script runs bun install --frozen-lockfile, builds and copies the CLI, TUI, backend, and plugin, registers the installed plugin with Codex, and starts the official daemon and local backend. It does not install Git, Bun, or the official Codex CLI, or configure file-based authentication for you.

The equivalent command, after cloning and entering the repository, is bun run setup; it also installs project dependencies automatically.

Explicit dependency installation

If you prefer to run dependency installation yourself, use this alternative from a fresh checkout:

git clone https://github.com/eduardoaugustolb/codex-accounts.git
cd codex-accounts
bun install --frozen-lockfile
bun run setup

Setup checks dependencies again using the frozen lockfile. Both entry points perform the same complete installation and preserve the official codex binary.

Installed command

The installer places codex-accounts in ~/.local/bin. For only the manager command, use ./install.sh --cli-only or bun run install:cli after cloning and entering the repository; these also install project dependencies.

The installer copies the built marketplace into ${XDG_DATA_HOME:-$HOME/.local/share}/codex-accounts/cli/releases and creates an executable launcher. It works from any directory and does not depend on keeping this checkout in place. Bun must remain installed. Existing managed installations are updated; unrelated commands at the target path are never overwritten. Previous releases are retained so running backends can finish using them.

If ~/.local/bin is not in your PATH, add it through your shell configuration. The installer prints a POSIX-shell command for the selected directory and does not edit shell startup files. Custom locations are supported with ./install.sh --bin-dir /path/to/bin --data-dir /path/to/app-data.

codex-accounts                    # Open the TUI in an interactive terminal
codex-accounts tui                # Explicit TUI command
codex-accounts --help
codex-accounts usage work --json
codex-accounts switch personal

Rerun ./install.sh or bun run setup after updating the checkout to update the complete application. The command name is a launcher for this manager; the official codex command is preserved.

Open codex, enter /hooks, and review and trust all four Codex Accounts hooks. Then start a new conversation. Trust is tied to the plugin contents, so an update may require another review. Do not use --dangerously-bypass-hook-trust: this option disables daemon reuse in Codex 0.167.2.

Updating without a checkout

Once installed with the current installer, run from any directory:

codex-accounts update
codex-accounts restart

The updater clones the official repository’s latest main into a temporary directory and runs its installer. Git and Bun must be available. It preserves custom binary/data directories, manager-only installation mode, saved accounts, and preferences. It does not run git pull in your working checkout. The temporary source is removed after success or failure. This currently installs the latest source version rather than a tagged release.

Running backends and conversations are preserved during installation. Restart the backend when ready, review changed hooks in Codex /hooks, and reopen codex-accounts panel. Installations created before update metadata was introduced need one ./install.sh run from the existing checkout first; later updates use codex-accounts update. A source invocation of update is rejected because it has no managed installation target.