Cli-ghost

One terminal. Multiple identities.

Created by Issam El Bani at VELTEIN

One command-line interface for Codex and Antigravity CLI (agy) accounts. List accounts and remaining quota, add OAuth logins, switch accounts, and launch sessions through the existing account-rotation tools.

This is an independent orchestration CLI, not a new OAuth implementation or request proxy. It delegates to codex-multi-auth and antigravity-swap. It does not read, copy, export, or upload OAuth credential files.

Install

From npm

Requires Node.js 18+ and Python 3.10+. The two account backends have their own requirements listed below. Cli-ghost bundles its Python core; no separate pip installation of Cli-ghost is needed.

npm install -g clighost
cli-ghost --help

Already have clighost installed? Upgrade with npm install -g clighost@latest, then run cli-ghost dashboard. The npm package keeps its original name; the display name is Cli-ghost, and both command names are available.

Or run without a global installation:

npx clighost status

If Python is not on PATH, set CLIGHOST_PYTHON to the Python 3.10+ executable.

On Windows, the first launch automatically creates a private Python environment under %LOCALAPPDATA%\Cli-ghost\python and downloads its terminal dependency (pywinpty). Your system Python packages are unchanged. Setup needs an internet connection once; subsequent launches reuse the environment. Changing the Python version creates a new compatible environment automatically. Help and version commands work without downloading dependencies.

You can also prepare the runtime explicitly:

cli-ghost setup
cli-ghost dashboard

Provider backends

Install the official Codex and Antigravity CLIs, then their account backends:

# Node.js >=22.19 is required by codex-multi-auth.
npm install -g codex-multi-auth

# Python >=3.12 is required by antigravity-swap.
pipx install antigravity-swap

cli-ghost doctor

From source with pipx

git clone https://github.com/ssassam/clighost.git
pipx install ./clighost
cli-ghost doctor

The earlier aam command remains a compatibility alias in Python installations. The npm package installs the cli-ghost command.

The upstream projects also offer other installation methods. Existing installations work: cli-ghost resolves commands from PATH, including privately installed runtimes.

Everyday commands

cli-ghost status                         # Both providers, cached quota
cli-ghost status codex
cli-ghost status --style plain           # Compact text output
cli-ghost status --no-color              # Matrix layout without colors
cli-ghost status agy --live               # Refresh Antigravity quota
cli-ghost status --json                   # Normalized JSON; no credential fields
cli-ghost check codex                     # Live authentication + inference/quota check
cli-ghost check agy                       # Refresh quota; renew login when needed
cli-ghost switch codex 2                  # Pin Codex account 2
cli-ghost switch agy 2                    # Change Antigravity's default account
cli-ghost run codex                       # mcodex with automatic rotation
cli-ghost run agy                         # aswap run with quota failover
cli-ghost run codex -- resume --last
cli-ghost run codex -- exec "Explain this project"
cli-ghost run agy -- --continue
cli-ghost run agy -- -p "Explain this project"

Status uses a Matrix-inspired green display with remaining-quota bars. Colors are disabled when output is redirected or NO_COLOR is set. Low quota appears in yellow or red; unknown quota shows question marks. The clighost command remains available as a compatibility alias.

Numbers in cli-ghost status are one-based and match the switch commands. Quota percentages mean remaining, including Antigravity reports whose upstream percentages mean used. Missing quota stays unknown. status --live --json writes live-check progress to stderr and JSON to stdout. Codex live checks consume some subscription quota.

Terminal dashboard

cli-ghost dashboard                      # Interactive dashboard, Codex tab
cli-ghost dashboard agy                  # Open on Antigravity
cli-ghost dashboard --interval 5          # Refresh cached reports every 5 seconds

Use Up/Down and Enter to select actions or switch accounts. Press C/G (or Tab) to change providers, A to add accounts, H for a live health/quota check, R to refresh reports, and Q to quit. Launching a provider opens its normal interactive session; exiting it returns to the dashboard.

Cached account and remaining-quota reports update every three seconds. H checks live quota; Codex checks can consume subscription quota. Active means the selected account, not proof that a task is running. Unknown quota stays unknown. Failed refreshes retain the last successful data and show an error. The dashboard needs an interactive terminal; use status --json for scripts. Windows console handling is implemented, but native Windows behavior has not yet been verified.

Add accounts

In an interactive terminal, login offers Add another account? [y/N] after each successful login and save. Use --once to skip the repeat prompt; redirected input also runs only once.

cli-ghost login codex                     # Choose Browser or Device code; offers another account
cli-ghost login agy                       # Print a Google sign-in link, save, and repeat
cli-ghost add codex                       # Start the Codex account assistant
cli-ghost add codex --browser             # Open browser OAuth without the method prompt
cli-ghost add codex --device-auth         # Use device-code OAuth without the method prompt
cli-ghost add agy                         # Same copy-link account assistant
cli-ghost add agy --current               # Save the account already signed in to agy
cli-ghost add agy --manual                # Use AGY's interactive sign-in screens

For Codex, the assistant (including Add in the dashboard) offers Browser and Device code. Press Enter for Browser: Codex opens the sign-in page and handles the local OAuth callback. Device code prints a link and a code to enter in your browser. Choose device code for remote/headless sessions or when the local callback cannot be reached. --browser and --device-auth select the method directly for add and login. With redirected input, Browser is the default; use --device-auth explicitly when needed. --once skips only the repeat prompt. Cli-ghost delegates authentication to Codex and does not handle OAuth tokens.

For Antigravity, the default flow is:

1. Cli-ghost starts AGY's remote OAuth flow in a temporary directory and prints its authorization link.
2. Open the link in the browser or profile for the Google account you want to add.
3. Complete sign-in and paste the code displayed by the browser into the terminal. Code input is hidden.
4. Once AGY writes the credentials, Cli-ghost closes the sign-in process, saves the account using aswap add --from-dir, removes the temporary directory, and offers another fresh link.

Use a separate link for each account. You do not need to enter or exit AGY's chat interface. AGY manages OAuth, PKCE and the token exchange; Cli-ghost does not embed OAuth client secrets. The assistant never clears your default login. Use cli-ghost switch agy N to activate a saved account.

Linux and macOS use Python's built-in terminal support. Windows link sign-in uses pywinpty, installed automatically by pip/pipx or by the npm launcher's private runtime setup. No separate pip command is needed for the npm installation. Native Windows sign-in has not yet been verified. If AGY cannot provide an isolated copy-link flow, the command stops and suggests --manual.

With --manual, file-based storage still uses a separate sign-in directory; exit AGY after signing in to save the account. Shared system keyrings may reopen the current account. Save it first with cli-ghost add agy --current, then use /logout inside AGY and sign in with the other account before exiting.

Adding the same account refreshes its stored credentials rather than creating another account. Google and ChatGPT accounts are separate pools; logging into Codex does not log into Antigravity.

Switching and continuity

Codex rotation works inside sessions launched with cli-ghost run codex. Calling plain codex does not enable that wrapper. cli-ghost switch codex N pins the selected account; use codex-ma unpin to return to automatic selection.

Antigravity keeps its credentials in memory. cli-ghost switch agy N affects new sessions. cli-ghost run agy uses aswap's quota-failover behavior: stop the session, copy its conversation to the next account, and restart with a continuation prompt. Saved project files remain in the same working directory. An unfinished tool action may be interrupted; this is not a guarantee of exact execution continuity. At least two healthy saved accounts are required to test failover.

Automatic health-check schedules remain the backend's settings. For Codex:

codex-ma account auto-prime 1 on
codex-ma account auto-prime 2 on

Those checks run every 15 minutes while the rotation router is running. The manager does not install background daemons, shell aliases, Telegram bots, or scheduled jobs. Use upstream commands for advanced provider-specific settings.

Another device

Clone this repository, install both backends, then sign in on that device. Accounts and backend settings do not sync through Git. OAuth snapshots are sensitive and must never be committed. This repository contains source code only.

Development

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v

For the npm launcher and package contents:

npm test
npm pack --dry-run

Tests use mocked backends and fake child processes; they do not make billable requests or change real logins. On Windows, run Python tests with Cli-ghost's private Python runtime (or install the project into a virtual environment) to include the pywinpty terminal integration check. Linux and macOS need no third-party Python runtime dependencies; Windows link sign-in uses pywinpty. Backend JSON schema changes may require adapter updates. Verified locally with codex-multi-auth 2.24.0 and antigravity-swap 0.3.1; automatic two-account Antigravity failover has not been verified locally.

On Windows, provider launches wait for completion and return the provider's exit code. Standard npm command wrappers are resolved to their Node.js scripts so prompt text is passed as literal arguments. Custom .cmd/.bat backend wrappers are rejected; use standard npm-installed backends or native executables.

If GitHub Actions cannot start because its budget is exhausted, the Linux checks can also run through Cloudflare Pages' GitHub integration. See the Cloudflare setup instructions. This runs independently of Actions and does not replace the Windows test matrix.

Support the creator

If Cli-ghost helps your workflow, you can support its development on Buy Me a Coffee.

Creator

Cli-ghost is created and maintained by Issam El Bani / VELTEIN. Follow @ssassam on GitHub.

MIT licensed. Not affiliated with OpenAI or Google.