Kiro Account Pool Manager

Kiro Account Pool Manager (kiro-pool)

Key Features

• Unlimited Accounts ($N$): Connect 2, 5, 10, or 50+ Google accounts with independent session tokens.
• Ultra-Lightweight (~50 KB / account): Uses symlink templating to share heavy engine runtimes (node, bun, tui.js, run/). 50 accounts use ~2.5 MB instead of 50 GB.
• Automatic Quota Failover: Detects HTTP 429, ThrottlingError, or quota exhaustion and immediately retries the prompt with the next available account.
• Intelligent Cooldown: Automatically benches throttled accounts for 60 minutes and resumes them once their rate limit resets.
• Pool Health Dashboard: View all enrolled Google accounts, active status, cooldown timers, and request counts via kiro-pool status.
• Zero Impact on Default CLI: Your official kiro-cli installation and default primary account remain 100% untouched.

How It Works

Kiro CLI stores authentication tokens in an unencrypted SQLite table at $XDG_DATA_HOME/kiro-cli/data.sqlite3.

kiro-pool wraps your installed kiro-cli binary, dynamically injecting isolated environment variables (XDG_DATA_HOME, KIRO_HOME, XDG_RUNTIME_DIR) per command:

flowchart TD
    A[You run: kiro-pool chat --no-interactive 'Prompt'] --> B[kiro-pool Orchestrator]
    B --> C[1. Read state & pick next healthy account]
    B --> D[2. Bench throttled accounts in cooldown window]
    B --> E[3. Inject isolated XDG & KIRO environment triple]
    E --> F[Execute official kiro-cli binary]
    F --> G{Execution Result}
    G -- Success --> H[Return response to stdout]
    G -- Throttled 429 / RateLimit --> I[Mark account in 60m cooldown]
    I --> J[Auto-retry with next available account]
    J --> F

(See docs/INTERNAL_ARCHITECTURE.md for full reverse-engineered details.)

Quickstart

1. Installation

Clone and run the installer:

git clone https://github.com/MishraShardendu22/kiro-account-pool-manager.git
cd kiro-account-pool-manager
./install.sh

Ensure ~/.local/bin is in your PATH (default in Ubuntu and most distributions).

2. Enroll Accounts

You can enroll accounts in two ways:

Option A: One-Click Import (Recommended)

Log in normally via standard kiro-cli login in your browser, then import it into a permanent pool slot:

kiro-cli login
kiro-pool import acc1

Repeat for any other Google or GitHub account—each imported session is permanently isolated and protected from being overwritten.

Option B: Direct Enrollment

kiro-pool add acc1
kiro-pool add acc2

Tip

Why Stock Kiro Was Limited to 2 Accounts: In default unmanaged kiro-cli, session credentials are stored in a single SQLite table (auth_kv) with only one key for social login (kirocli:social:token) and one for AWS Builder ID (kirocli:builder-id:token). Logging into a second Google account in stock Kiro simply overwrote the file on disk! With kiro-pool's isolated sandboxes, you can run an unlimited number of accounts simultaneously. Server-side tokens do not expire or invalidate each other.

3. Check Pool Status & Prune Unhealthy Accounts

# View active accounts, OAuth provider, and health
kiro-pool status

# Clean up / remove any accounts that lost authentication or were logged out
kiro-pool prune

# Set any pooled profile as your active default for standard 'kiro-cli'
kiro-pool switch acc1

Example Output:

Kiro Multi-Account Pool Status
============================================================================
Profile        Email                            Auth State           Used  
----------------------------------------------------------------------------
01             work.dev@gmail.com               Ready (Google)     16    
upsc           personal.code@gmail.com          Ready (Github)     14    
acc3           experimental@gmail.com           Cooldown (45m)     8     
acc4           old.dev@gmail.com                Login Required     2     
============================================================================
Tip: 1 account(s) require re-login. Run kiro-pool prune to remove them from rotation.

Unattended & Headless Safety

kiro-pool is designed for autonomous agents, CI/CD runners, and background subtasks:

1. Pre-flight Auth Filtering: Before any prompt is executed, kiro-pool inspects the profile's SQLite session. If an account is logged out or unauthenticated, it is automatically skipped—it will never block your terminal.
2. Same-Provider Auto-Failover: When an account hits quota limits or HTTP 429 throttling, kiro-pool marks it in a 60-minute cooldown and immediately retries on another healthy account from the SAME provider before falling back to other providers.
3. Headless Safety Guard: If an account's token is revoked mid-flight and kiro-cli attempts to launch an interactive browser callback (localhost:3128), kiro-pool catches it immediately, skips the expired profile, and transparently retries on the next healthy account.
4. Automated Playwright Login: For headless server environments, scripts/auto_auth_playwright.py is included to automate device flow logins via Chromium.

Usage

A. Non-Interactive Task Prompts (Automatic Rotation)

Every prompt automatically alternates across your account pool:

# Prompt 1 -> Uses acc1 (Google)
kiro-pool chat --v3 --model claude-haiku-4.5 --no-interactive "Scaffold a FastAPI application"

# Prompt 2 -> Uses acc2 (Google)
kiro-pool chat --v3 --model claude-haiku-4.5 --no-interactive "Write pytest integration tests"

# Prompt 3 -> Explicitly target a specific provider if desired
kiro-pool --provider google chat --v3 --no-interactive "Generate Dockerfile"

If an account hits a rate limit or requires authentication, kiro-pool automatically benches that account and reroutes the prompt to a backup account of the same provider without failing.

B. Interactive Chat Session (TUI)

kiro-pool chat

• Launches an interactive terminal UI session using the next available account.
• That specific multi-turn conversation will stay on that account until you exit (Ctrl+C or /quit).
• Running kiro-pool chat again picks the next account in rotation.

C. Convenient Shell Alias

Add this alias to your ~/.bashrc or ~/.zshrc:

alias kiro="kiro-pool"

Now you can run:

kiro status
kiro switch 01
kiro chat --no-interactive "Review PR #42"

Command Reference

Practical Tradeoffs & Honest Evaluation

Where kiro-pool Genuinely Shines

1. Free Frontier Model Compute: Access AWS-backed models (Claude 3.5 Sonnet, Claude Haiku 4.5, Qwen Coder) using standard Google and GitHub accounts without paying for OpenAI or Anthropic API subscriptions.
2. Quota Multiplication: By pooling 3–10 accounts, you multiply daily usage allowances and avoid single-account rate limit blocks.
3. Disposable Background Sub-agents: Perfect for offloading heavy, secondary tasks (e.g., analyzing large git diffs during PR reviews or generating boilerplate unit test suites) without consuming your primary AI coding assistant's context window or paid token budget.

Practical Friction Points to Know

1. Daemon Cold-Start Latency: The official kiro-cli engine spawns background runtimes (kas, node, bun) and runs local SQLite synchronization. This introduces an intrinsic 5–8 second startup latency before output streams. It is best suited for batch prompts and background delegation rather than instant sub-second queries.
2. Session Maintenance Overhead: Google and GitHub OAuth device tokens periodically expire. While kiro-pool protects headless automation by auto-skipping expired profiles (and provides kiro-pool prune), maintaining a large pool of 10+ accounts requires occasional re-enrollment (which can be automated using scripts/auto_auth_playwright.py).
3. Execution Model: kiro-pool acts as a prompt runner and tool execution pipeline. It is not an autonomous IDE agent with native workspace tree indexing.

Running Tests

The test suite runs using Python's native unittest framework (zero third-party dependencies):

python3 -m unittest discover -s tests -v

Frequently Asked Questions

Why did default Kiro CLI feel limited to at most 2 accounts?

In unmanaged kiro-cli, authentication tokens are stored in a single SQLite table (auth_kv) that has only two fixed keys: kirocli:social:token (Social Login: Google OR GitHub) and kirocli:builder-id:token (AWS Builder ID). When you logged into a second Google account in vanilla kiro-cli, it immediately overwrote kirocli:social:token in SQLite, wiping out the first Google account. With kiro-pool, every profile has its own sandboxed SQLite database (~/.local/share/kiro-profiles/<name>/kiro-cli/data.sqlite3), completely removing this constraint.

Does adding or using another account expire or invalidate my previous account?

No. AWS CodeWhisperer/Kiro generates independent OAuth refresh tokens and AWS profile ARNs tied to the specific account identity. The backend has no link between separate Google accounts; each has its own independent refresh cycle and lifetime. They remain active concurrently.

Does this modify my default kiro-cli?

No. Standard kiro-cli continues to use your primary default account (~/.local/share/kiro-cli/data.sqlite3). However, if you want standard kiro-cli to switch to any account in the pool, you can conveniently run kiro-pool switch <name>.

Can one open chat window switch accounts mid-conversation?

No. Kiro's cloud runtime anchors conversation threads to the user's Profile ARN. Alternating accounts per message within a single unbroken conversation thread causes backend rejection (InvalidConversationId). Rotation happens per prompt or per session.

How do tokens refresh?

Kiro CLI automatically refreshes expired tokens in the background using each profile's independent .refresh.lock and SQLite database. No manual re-login is required.

Contributing

Contributions are warmly welcomed! Please read our Contributing Guide and Code of Conduct.

License

MIT License. See LICENSE for details.