Content
# Gemini Account Switcher (Rust)
> A high-performance Rust extension for [Gemini CLI](https://github.com/google/gemini-cli) that adds multi-account support with an intelligent background watcher for quota management.
---
## Why?
Gemini CLI typically allows one Google account at a time. For heavy workloads, you can hit the free tier quota quickly. This tool allows you to:
- **Rotate multiple accounts** to bypass single-account limits.
- **Switch instantly** via slash commands inside your Gemini session.
- **Background Monitor** logs in real-time to detect `RESOURCE_EXHAUSTED` errors and prompt for an immediate switch to your most "rested" account.
## Features
- **MCP Integration**: Fully compliant Model Context Protocol server exposing account tools.
- **Smart Auto-Switch**: Automatically identifies the account with the most remaining quota when you get blocked.
- **Background Watcher**: Real-time log monitoring with native desktop notifications.
- **Session Safety**: Automatically backs up your active session before every switch.
- **Native Performance**: Single binary, low memory footprint, and blazing fast file operations.
## Architecture
1. **MCP Server (`mcp`)**: Handles tool calls from Gemini CLI (list, save, switch, delete).
2. **Watcher (`watch`)**: A background loop that scans logs, tracks usage, and provides the interactive switch UI.
---
## Installation
### 1. Build from Source
```bash
cargo build --release
```
The binary will be generated at `target/release/gemini-account-switcher-rs`.
### 2. Register the Extension
Link the extension to your Gemini CLI by ensuring your `gemini-extension.json` exists in the project root:
```json
{
"name": "GeminiAccountSwitcherRs",
"version": "0.1.0",
"mcpServers": {
"accountSwitcher": {
"command": "/absolute/path/to/target/release/gemini-account-switcher-rs",
"args": ["mcp"]
}
}
}
```
---
## Usage
### Step 1: Save your accounts
Inside Gemini CLI, save your current session under a name:
```
/accounts:save main
/accounts:save secondary
```
### Step 2: Start the Watcher
In a separate terminal window, keep the watcher running:
```bash
./target/release/gemini-account-switcher-rs watch
```
### Watcher Output Example
```text
╔══════════════════════════════════════════════════╗
║ Gemini Account Switcher — Watcher (Rust) ║
╚══════════════════════════════════════════════════╝
👤 Current account: main
📊 Today's usage:
main: 847 requests — OK
secondary: 12 requests — OK
👁️ Watching Gemini CLI logs for quota errors...
```
When quota exhausts, the watcher prompts you:
```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️ QUOTA EXHAUSTED: main
Switch to: secondary (12 requests used today)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Switch now? (y/n): y
✅ Switched to secondary. Please restart your Gemini CLI session.
```
---
## How It Works
### Account Storage
Gemini CLI stores credentials in `~/.gemini/`. This tool creates a profile for each account in `~/.gemini-accounts/<name>/` and swaps the files (`oauth_creds.json`, etc.) whenever you switch.
### Quota Detection
The watcher polls `~/.gemini/tmp/*/logs.json` every 5 seconds. It uses high-performance stream reading to detect `RESOURCE_EXHAUSTED` strings without re-reading the entire log file every time.
### Selection Logic
When a switch is needed, the tool scans all saved accounts that aren't marked as "Exhausted" today and picks the one with the lowest `daily_requests` count.
---
## File & Folder Locations
| Item | Location |
| :--- | :--- |
| **Saved accounts** | `~/.gemini-accounts/` |
| **Usage tracker** | `~/.gemini-accounts/_usage_tracker.json` |
| **Session backup** | `~/.gemini-accounts/_previous_session/` |
| **Gemini CLI logs** | `~/.gemini/tmp/*/logs.json` |
---
## License
Apache License 2.0
