Munchkin

Munchkin is a cross-platform multi-account manager for Codex, Gemini, and Qwen CLIs.

It stores OAuth-backed CLI sessions in an encrypted local vault, lets you switch between saved accounts instantly, verifies whether a saved session is still usable, tracks Codex quota state, and can route Codex commands through a lightweight quota-aware load-balancing layer.

Why Munchkin exists

Most CLI tools assume one active auth context per machine.

That is fine until you need separate accounts for:

• personal work
• professional work
• experiments
• shared or borrowed access
• backup accounts when quota is exhausted

Munchkin keeps that complexity out of your shell setup. Instead of logging in and out constantly, you save provider sessions once and move between them from one encrypted dashboard.

Highlights

Capability	What it does
Encrypted vault	Stores account snapshots locally behind a master password
Multi-provider support	Manages Codex, Gemini, and Qwen CLI sessions
Session health checks	Tells you whether a saved account is healthy, degraded, token-only, expired, or needs reauth
Fast switching	Applies a saved account back to the target CLI in one step
Active-session sync	Pulls the live currently logged-in session back into the vault
Codex quota tracking	Refreshes and caches Codex usage windows
Codex load balancing	Selects the best available Codex account before running a command
Backup and recovery	Exports and imports encrypted vault/state bundles
Interactive dashboard	Arrow-key menu-driven interface for day-to-day use
Release packaging	Windows installer plus macOS/Linux packaging pipeline

How it works

flowchart LR
  A["Provider CLI session"] --> B["Munchkin capture"]
  B --> C["Encrypted local vault"]
  C --> D["Account verification"]
  C --> E["Switch / restore"]
  C --> F["Quota-aware Codex selection"]
  F --> G["Run Codex command"]

Loading

For each provider, Munchkin captures the provider-specific local OAuth state, stores it encrypted, and reapplies it later when you switch.

Supported providers

Codex

• file-backed auth enforcement for deterministic switching
• session verification
• quota refresh
• process-level load balancing
• optional codex-lb bridge config for Codex config.toml

Gemini

• OAuth snapshot capture and restore from local cached credentials
• verification and switching support

Qwen

• OAuth snapshot capture and restore from local cached credentials
• verification and switching support

Quick start

Development

npm install
npm run build
npm link
munchkin

Windows package

npm run package:installer

Artifacts:

• build\package\munchkin.exe
• build\package\Munchkin-Setup.exe

macOS and Linux package

Run on the native platform:

npm install
npm run package:unix

Artifact:

• build/package/munchkin-<platform>-<arch>.tar.gz

Dashboard workflow

Launch:

munchkin

The dashboard covers:

• add/import/switch/rename/remove account flows
• session verification
• sync active account
• current/all Codex quota refresh
• vault export/import
• Codex load-balancer settings
• recent operational logs
• doctor diagnostics
• provider command execution

CLI examples

munchkin list
munchkin verify
munchkin verify -p codex -n main
munchkin use codex main
munchkin sync codex
munchkin quota --all
munchkin run codex -- exec "Reply with OK only."
munchkin lb enable
munchkin lb status
munchkin lb bridge enable --base-url http://127.0.0.1:2455
munchkin export-vault
munchkin import-vault C:\path\to\backup.json
munchkin logs --limit 20
munchkin doctor

Packaging and releases

Munchkin includes a release workflow at .github/workflows/release.yml.

It:

• builds on Windows, macOS, and Linux
• runs typecheck and tests
• packages native artifacts on each runner
• publishes a GitHub release automatically when a tag like v1.0.0 is pushed

Security model

• account snapshots are encrypted at rest in the local vault
• the master password is required to unlock the vault
• Munchkin does not prevent upstream providers from rotating or invalidating OAuth sessions
• a saved account can still become unusable later if the provider invalidates it elsewhere

Operational reality

Munchkin is robust, but OAuth sessions are not under its control.

Important implications:

• shared accounts are inherently fragile
• refresh tokens can be rotated upstream
• a saved session may exist but still require reauthentication
• verify should be used to confirm whether a saved account is actually usable

Project status

This project is designed to be practical first: a real local tool, not just a proof of concept.

Current state:

• Windows packaging is built and verified in this workspace
• cross-platform build and release automation is included
• native macOS/Linux artifacts are intended to be produced on native runners through GitHub Actions

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT, see LICENSE.