augpool

Pool multiple Augment Code credentials. Run in auto mode to balance spend through the least-used account, or lock every new session to one account.

Identity is always the full email. No short ids.

Install

The augpool binary must sit on a stable PATH that both your terminal and agent hosts (e.g. kandev boot scripts) can resolve. A project venv alone is usually not enough for agents.

Recommended — pipx

pipx install augpool
# → ~/.local/bin/augpool   (keep ~/.local/bin on PATH)

User install

python3 -m pip install --user augpool
# ensure ~/.local/bin is on PATH for login shells *and* GUI / agent processes

Editable (development)

git clone https://github.com/zeval/augpool.git
cd augpool
python3 -m pip install -e ".[dev]"

Editable installs place the console script in whichever environment’s bin/ you pip into (conda base, Homebrew Python, …). That only works for kandev if that bin/ is on the agent’s PATH.

Avoid for agent use:

python3 -m venv .venv && source .venv/bin/activate && pip install …

That works only while the venv is activated. kandev will not find augpool.

First things to do

Do these in order. Every example uses placeholders only (you@example.com).

1. Import your account (start here)

You need at least one credential in the pool. Easiest path: whatever auggie is already logged in as on this machine.

# After normal `auggie login` (or any existing ~/.augment/session.json)
augpool import --self --email you@example.com

Or point at a session file you already have:

augpool import --session ./session.json --email you@example.com

# stdin JSON
augpool import --session - --email you@example.com < session.json

# replace if that email is already in the pool
augpool import --session ./session.json --email you@example.com --force

Auggie session JSON looks like { "accessToken", "tenantURL", "scopes"? } (typical path: ~/.augment/session.json). The file has no email field, so --email is always required for --self / --session.

augpool list          # confirm you’re in the pool
augpool               # run auggie under the pool (= augpool run -- auggie)
augpool -p -q "ping"

2. Export your account (share with teammates)

# By email (preferred — no Analytics wait)
augpool export you@example.com
# → one line, unpadded base64url, shell-safe (no quotes):
# eyJlbWFpbCI6InlvdUBleGFtcGxlLmNvbSIs...

# Or the locked account (also works for a sole account in auto mode)
augpool export --self

Send that one token over a private channel. It is a full credential.

Optional shapes:

augpool export --json you@example.com    # pretty envelope
eval "$(augpool export --env you@example.com)"   # shell inject (history risk)

3. Import from other users (grow the pool)

They run step 2 and paste you a blob. You do not pass --email — it’s inside the blob.

augpool import eyJlbWFpbCI6InRlYW1tYXRlQGV4YW1wbGUuY29tLC4uLg
augpool import --force eyJ...    # overwrite if that email already exists

If they give you a session file instead of a blob, you supply their email:

augpool import --session ./teammate-session.json --email teammate@example.com
# same thing:
augpool add --email teammate@example.com --session ./teammate-session.json

augpool list          # ranked least-used first

Rules

Pass only one of blob / --self / --session.

Treat blobs and session files like passwords. Import others only with consent. Never commit them. Never paste them into public chat.

Blob shape (v2): { v, email, label, session } — unpadded base64url, no prefix.

Default: auggie wrapper

Bare augpool is augpool run -- auggie …:

augpool                              # interactive
augpool -p -q "hello"                # print mode
augpool --email you@example.com …    # force account
augpool list                         # subcommands still work

Selection order is explicit --email override → persisted lock → auto pool. Named accounts are fixed for that invocation and never fail over into the pool.

kandev / ACP

augpool --acp --allow-indexing
# equivalent:
augpool run -- npx -y @augmentcode/auggie --acp --allow-indexing

For --acp / --mcp, augpool does not buffer stdio: pick account → inject auth → os.exec the child so the host owns the protocol pipes.

Agent boot must resolve augpool on PATH (pipx, user install, or an env whose bin/ is always on PATH — not an unactivated venv).

Account selection mode

augpool mode                         # show current mode
augpool mode auto                    # choose best account for each new session
augpool mode you@example.com         # lock every new session to this account
augpool --email teammate@example.com # one-session override

Auto is the default and the upgrade mode for existing installations. A locked account must stay enabled and in the registry; switch to auto or another account before disabling or removing it. Locked and --email runs skip Analytics and return that account's error directly on rate limiting.

next and use were removed; mode replaces their account-selection role. Augpool still injects auth without changing ~/.augment/session.json. augpool restore remains available only to recover a backup created by an older release's use command; restoring does not change current mode.

Analytics ranking

Least-used score uses each account’s session token against:

GET https://api.augmentcode.com/analytics/v0/credit-usage-by-user

Credit window is the current UTC calendar month, from day 1 through today.

• Cache: ~/.augpool/cache/ (default TTL ~5 minutes)
• Auto-mode runs and ranked views refresh when stale
• Locked runs, --email overrides, and explicit exports skip refresh
• No Analytics access → local use counters

augpool refresh
augpool list --refresh

Usage dashboard

usage turns the pool's Analytics cache and local counters into a compact, Tokscale-inspired terminal view:

augpool usage
augpool usage --refresh       # pull Analytics first
augpool usage --json          # structured report for scripts
augpool usage --no-color      # also respects NO_COLOR

augpool usage
2026-08-01 → 2026-08-06 · updated 2m ago

3 accounts · 8.4k credits · 17 sessions

Sessions over time · 30d UTC · 12 tracked
07-08 ·····················▁··▃·█▂ 08-06
────────────────────────────────────────────────────────────────────────
● teammate@example.com                         1.8k  21.4%  locked
  █████████░░░░░░░░░░░░░░░░░░░░░░░░  6 sessions · used 4m ago

Credits are Augment Analytics consumption for the current UTC calendar month. Caches from a different month are refreshed even when still inside the normal TTL. Sessions are local account selections (run events, plus historical use events recorded by older releases); they are not Augment's vendor-side conversation count. The view also surfaces locked, cooldown, disabled, weight, last-used, cache, and partial-refresh information when available. Without Analytics data, bars fall back to local sessions.

Dated session tracking starts after installing this version; augpool does not assign older lifetime counts to invented dates. It keeps 90 days of per-account UTC daily buckets and shows the latest 30 days in the dashboard. --json includes daily totals and per-account counts for the same 30-day window.

Machine integrations

Augpool exposes a versioned, credential-free snapshot for dashboards and other local integrations:

augpool stats --json
augpool stats --json --refresh

The top-level object has schema_version: 2, mode, nullable locked_email, current-month cache freshness, window and refresh errors, plus ranked account rows with a locked flag. It deliberately excludes session paths, tenant URLs, notes, tokens, session JSON, and share blobs. A failed refresh preserves the last usable cache while reporting the new attempt errors.

Account settings can be changed without editing pool.json:

augpool update you@example.com --weight 2.5 --json
augpool update you@example.com --disable --json
augpool update you@example.com --enable --json

mode, import, remove, and update also accept --json. Send share blobs on stdin when another process invokes Augpool so the credential does not enter process arguments:

printf '%s\n' "$AUGPOOL_SHARE_BLOB" | augpool import - --json

Default augpool export EMAIL still prints one base64url credential token. Treat that stdout as secret: do not log, cache, or render it.

Commands

Layout

~/.augpool/
  pool.json            # registry, locked account, weights, settings
  state.json           # local uses, daily session history, cooldowns, locks
  cache/usage.json     # Analytics snapshot
  creds/<email>.json   # per-account session (mode 0600)
  backups/             # previous ~/.augment/session.json

Security

• Cred files are mode 0600
• Prefer augpool run over export --env
• Never commit creds/, session JSON, or share blobs
• A share blob is the full credential — rotate if it leaks

Tests

python3 -m pip install -e ".[dev]"
pytest -q

Limits

• Auth is fixed for one auggie process lifetime. Auto-mode failover restarts the child (appends --continue when safe); locked/override runs never fail over
• ACP / MCP protocol mode: single pick + exec (no mid-flight failover)
• MCP OAuth tokens are stored by Auggie per Augment account, separate from this pool