← all projects
Dev Tool

Claude-Molph

A local proxy that auto-rotates between multiple Claude accounts for Claude Code — mid-session, without restarting. Intercepts requests via ANTHROPIC_BASE_URL and swaps OAuth tokens when an account hits its usage threshold.

Solves multi-subscription token-juggling for Claude Code: a transparent local proxy that monitors per-account usage (5-hour / 7-day) and hot-swaps OAuth tokens at a threshold so a session never stalls on a rate limit.

TypeScript
Node.js

Problem Statement

Heavy Claude Code users with multiple Claude subscriptions hit usage limits mid-session — and the only fix is to stop, swap credentials, and restart, losing flow. There's no built-in way to pool several accounts and fail over automatically when one runs hot.

Proposed Solution

Claude-Molph is a local proxy that sits between Claude Code and Anthropic. Claude Code is pointed at it via ANTHROPIC_BASE_URL=http://localhost:9119; the proxy intercepts every request and injects the OAuth token of the currently-active account. A background monitor watches each account's usage and, when the active one crosses a threshold, swaps to a fresher account on the fly — Claude Code never notices, the conversation continues, and a different account simply starts paying.

Full Solution Details

  • Proxy server (molph-proxy) — listens on localhost:9119, intercepts Claude API requests, injects the active account's OAuth token, and handles token refresh automatically.
  • Usage monitor (background thread) — polls GET api.anthropic.com/api/oauth/usage per account, tracks five_hour and seven_day utilization, and triggers a switch at the configured threshold.
  • Account pool — JSON of accounts (name, access/refresh tokens, live usage), an active pointer, and settings (switch_threshold, metric, strategy).
  • Strategies — round-robin, least-used, or priority.
  • Keychain integration — pulls the existing Claude Code OAuth token from the macOS Keychain (security find-generic-password -s "Claude Code-credentials").
  • CLI — molph init/add/list (accounts + OAuth login), start/stop/status (proxy daemon), switch <name> / next (manual control), config threshold|metric|strategy (tuning).

Technical Documentation

The key insight is that Claude Code honors ANTHROPIC_BASE_URL, so a local proxy can transparently re-author the Authorization header per request. Molph runs as a daemon: the proxy forwards requests upstream with the active account's bearer token (refreshing it as needed), while a separate monitor thread polls the official OAuth usage endpoint (anthropic-beta: oauth-2025-04-20) for five_hour/seven_day utilization and flips the active account when the chosen metric exceeds switch_threshold under the chosen strategy. Tokens are sourced from the OS keychain and stored in the account pool; refresh tokens let the proxy keep access tokens current without manual re-login.

Tech Stack

Node.js + TypeScript (proxy daemon + CLI), OAuth (token injection + refresh), Anthropic OAuth usage API, macOS Keychain integration.

System Design

Claude Code  (ANTHROPIC_BASE_URL=http://localhost:9119)
        │  every request
        ▼
  molph-proxy ── inject Authorization: Bearer <active account token>
        │  (refresh token as needed) ──► api.anthropic.com
        ▲
        │ active account
  Account Pool {personal[95%], work[23%], ...}  ◄── Usage Monitor (thread)
        │  threshold hit (metric: five_hour/seven_day)   polls /api/oauth/usage
        └── strategy: least-used | round-robin | priority → switch active
  Tokens sourced from macOS Keychain · CLI: init/add/start/switch/next/config

Smart Architectural Decisions

  • ANTHROPIC_BASE_URL interception is the whole trick. Rather than patching Claude Code, Molph exploits an officially-supported env var to become a transparent man-in-the-middle for its own accounts — zero changes to the client, fully reversible.
  • Usage-driven, not error-driven switching. Polling the real OAuth usage API and switching at a threshold (before the limit) means sessions never hit a hard 429 mid-thought — proactive, not reactive.
  • Pluggable strategies. least-used / round-robin / priority let the user optimize for fairness, longevity, or a preferred account.
  • Keychain-sourced tokens + auto-refresh. Reading existing credentials from the OS keychain and refreshing tokens keeps the UX login-free and the tokens valid without manual intervention.
  • Daemon + CLI split gives a clean operational model (background proxy, foreground control).

Impacts

Lets a multi-subscription power user run Claude Code indefinitely across accounts without ever stopping to swap credentials — uninterrupted flow, automatic failover, and full manual override when wanted.

Demonstrated Skills

Proxy/network engineering (transparent request interception, header rewriting, upstream forwarding); OAuth token lifecycle (injection, refresh, keychain sourcing); polling/monitoring + threshold policies and selection strategies; CLI + daemon design; deep, practical understanding of how Claude Code authenticates.

Notes

  • Clever, low-footprint hack done the right way: exploiting the supported ANTHROPIC_BASE_URL to transparently swap your own tokens — no client patching, fully reversible — shows sharp systems thinking.
  • Proactive reliability: switching on a usage threshold (polling the real OAuth usage API) rather than waiting for a 429 demonstrates he designs for the failure before it happens.
  • Real auth-internals fluency: OAuth refresh + macOS Keychain sourcing + per-request header rewriting is non-trivial and verifiable competence.
  • Tasteful product surface: pluggable strategies (least-used/round-robin/priority) and a clean daemon+CLI split.
  • Note: this is a personal/dev tool with a documented design (no public repo linked); great as a 'how does Claude Code auth actually work' interview story. (Strictly for the author's own accounts.)
← back to all projects
Ask me anything