Skip to content

Commit d3a86d9

Browse files
Rtx09xRtx09x
committed
Initial release: Munchkin v1.0.0
0 parents  commit d3a86d9

32 files changed

Lines changed: 6605 additions & 0 deletions

‎.github/workflows/release.yml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: build-and-release
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
tags:
7+
- "v*"
8+
9+
jobs:
10+
build:
11+
strategy:
12+
fail-fast: false
13+
matrix:
14+
include:
15+
- os: windows-latest
16+
artifact: windows
17+
- os: ubuntu-latest
18+
artifact: linux
19+
- os: macos-latest
20+
artifact: macos
21+
runs-on: ${{ matrix.os }}
22+
steps:
23+
- uses: actions/checkout@v4
24+
25+
- uses: actions/setup-node@v4
26+
with:
27+
node-version: 22
28+
cache: npm
29+
30+
- name: Install dependencies
31+
run: npm ci
32+
33+
- name: Typecheck
34+
run: npm run check
35+
36+
- name: Test
37+
run: npm test
38+
39+
- name: Package
40+
run: npm run package:release
41+
42+
- name: Upload artifact
43+
uses: actions/upload-artifact@v4
44+
with:
45+
name: munchkin-${{ matrix.artifact }}
46+
path: build/package/*
47+
48+
release:
49+
if: startsWith(github.ref, 'refs/tags/v')
50+
needs: build
51+
runs-on: ubuntu-latest
52+
steps:
53+
- uses: actions/download-artifact@v4
54+
with:
55+
path: release-artifacts
56+
57+
- name: Flatten artifacts
58+
run: |
59+
mkdir -p release-upload
60+
find release-artifacts -type f -exec cp {} release-upload/ \;
61+
62+
- name: Publish release
63+
uses: softprops/action-gh-release@v2
64+
with:
65+
files: release-upload/*

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
node_modules/
2+
dist/
3+
.external/
4+
build/
5+
.munchkin-test/
6+
coverage/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Rudra
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Munchkin
2+
3+
Munchkin is a cross-platform OAuth account manager for Codex, Gemini, and Qwen CLIs.
4+
5+
It gives you an encrypted local vault for multiple accounts, fast switching, account verification, Codex quota tracking, backup/export flows, and an optional Codex load-balancing mode. The goal is simple: keep one clean machine setup and switch between saved CLI identities without reinstalling tools or reauthenticating every time.
6+
7+
## Features
8+
9+
- Encrypted vault protected by a master password
10+
- Multi-account support for:
11+
- Codex CLI
12+
- Gemini CLI
13+
- Qwen CLI
14+
- Import current sessions or add new accounts through the real provider login flow
15+
- One-step switching between saved accounts
16+
- Account verification with health states such as `healthy`, `token-only`, and `reauth-required`
17+
- Active-session sync back into the vault so refreshed sessions are not lost
18+
- Codex quota refresh and cached usage status
19+
- Codex process-level load balancing across saved accounts
20+
- Vault export/import for backup and recovery
21+
- Interactive dashboard with arrow-key menus
22+
- Structured operational logs
23+
- Packaged Windows installer and cross-platform release pipeline
24+
25+
## Why it exists
26+
27+
Most CLI tools assume one active auth context per machine. That breaks down fast when you use separate personal, work, testing, or shared accounts.
28+
29+
Munchkin solves that by storing provider-specific auth snapshots in an encrypted vault and applying them back to the right CLI when you switch.
30+
31+
## Supported providers
32+
33+
### Codex
34+
35+
- Managed file-backed auth snapshots
36+
- Session verification
37+
- Quota refresh
38+
- Optional load balancing
39+
- Optional bridge configuration for `codex-lb`-style proxy setups
40+
41+
### Gemini
42+
43+
- OAuth snapshot capture and restore from local cached credentials
44+
- Verification and switching support
45+
46+
### Qwen
47+
48+
- OAuth snapshot capture and restore from local cached credentials
49+
- Verification and switching support
50+
51+
## Installation
52+
53+
### Local development
54+
55+
```powershell
56+
npm install
57+
npm run build
58+
npm link
59+
```
60+
61+
Then run:
62+
63+
```powershell
64+
munchkin
65+
```
66+
67+
### Windows packaged installer
68+
69+
Build:
70+
71+
```powershell
72+
npm run package:installer
73+
```
74+
75+
Artifacts:
76+
77+
- `build\package\munchkin.exe`
78+
- `build\package\Munchkin-Setup.exe`
79+
80+
### macOS and Linux package
81+
82+
Build on the native platform:
83+
84+
```bash
85+
npm install
86+
npm run package:unix
87+
```
88+
89+
Artifact:
90+
91+
- `build/package/munchkin-<platform>-<arch>.tar.gz`
92+
93+
Archive contents:
94+
95+
- `munchkin`
96+
- `install.sh`
97+
- `uninstall.sh`
98+
99+
## Usage
100+
101+
### Dashboard
102+
103+
Run:
104+
105+
```powershell
106+
munchkin
107+
```
108+
109+
The dashboard includes:
110+
111+
- account add/import/switch/rename/remove
112+
- verification
113+
- sync active account
114+
- quota refresh
115+
- export/import backup
116+
- Codex load balancer controls
117+
- recent logs
118+
119+
### CLI commands
120+
121+
```powershell
122+
munchkin list
123+
munchkin verify
124+
munchkin verify -p codex -n main
125+
munchkin use codex main
126+
munchkin sync codex
127+
munchkin quota
128+
munchkin quota --all
129+
munchkin run codex -- exec "Reply with OK only."
130+
munchkin lb enable
131+
munchkin lb status
132+
munchkin lb bridge enable --base-url http://127.0.0.1:2455
133+
munchkin export-vault
134+
munchkin import-vault C:\path\to\backup.json
135+
munchkin logs --limit 20
136+
munchkin doctor
137+
```
138+
139+
## Packaging and releases
140+
141+
The repo includes a GitHub Actions workflow that:
142+
143+
- builds on Windows, macOS, and Linux
144+
- runs typecheck and tests
145+
- packages native artifacts per platform
146+
- publishes a GitHub release automatically when you push a tag like `v1.0.0`
147+
148+
Workflow file:
149+
150+
- [.github/workflows/release.yml](E:\Coding\munchkin\.github\workflows\release.yml)
151+
152+
## Security notes
153+
154+
- Account snapshots are encrypted at rest in the local vault
155+
- OAuth sessions can still expire or be rotated by upstream providers
156+
- Shared OAuth sessions are inherently fragile if the same account is used elsewhere
157+
- A saved account may exist but still require reauthentication; use `verify` to confirm health
158+
159+
## Operational notes
160+
161+
- Codex quota support is implemented for saved Codex accounts only
162+
- Gemini can use keychain-backed storage on some machines, which may limit how much local auth state can be captured
163+
- The optional `lb bridge` commands only modify Codex configuration; they do not embed the external `codex-lb` server
164+
- Windows artifacts were built and verified in this workspace
165+
- macOS and Linux artifacts are intended to be built on native runners through the release workflow
166+
167+
## License
168+
169+
MIT

‎munchkin.cmd‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
@echo off
2+
setlocal
3+
node "%~dp0dist\cli.js" %*

0 commit comments

Comments
 (0)