{"id":50774482,"url":"https://github.com/kydoimos97/cc-credentials-manager","last_synced_at":"2026-06-11T22:01:05.424Z","repository":{"id":363937088,"uuid":"1265576265","full_name":"Kydoimos97/cc-credentials-manager","owner":"Kydoimos97","description":"Credentials Manager for Claude Code — multi-token OAuth rotation, rate-limit auto-rotation, session tracking, and autonomous runner","archived":false,"fork":false,"pushed_at":"2026-06-11T01:27:01.000Z","size":96,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T02:21:13.086Z","etag":null,"topics":["automation","claude","claude-code","credentials-manager","oauth","python","textual"],"latest_commit_sha":null,"homepage":"https://github.com/Kydoimos97/cc-credentials-manager","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kydoimos97.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-10T22:41:30.000Z","updated_at":"2026-06-11T01:27:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Kydoimos97/cc-credentials-manager","commit_stats":null,"previous_names":["kydoimos97/cc-credentials-manager"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Kydoimos97/cc-credentials-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kydoimos97%2Fcc-credentials-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kydoimos97%2Fcc-credentials-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kydoimos97%2Fcc-credentials-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kydoimos97%2Fcc-credentials-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kydoimos97","download_url":"https://codeload.github.com/Kydoimos97/cc-credentials-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kydoimos97%2Fcc-credentials-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34219510,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","claude","claude-code","credentials-manager","oauth","python","textual"],"created_at":"2026-06-11T22:01:04.382Z","updated_at":"2026-06-11T22:01:05.412Z","avatar_url":"https://github.com/Kydoimos97.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Credentials Manager for Claude Code\n\n[![CI](https://github.com/Kydoimos97/cc-credentials-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/Kydoimos97/cc-credentials-manager/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/cc-credentials-manager)](https://pypi.org/project/cc-credentials-manager/)\n[![Python](https://img.shields.io/pypi/pyversions/cc-credentials-manager)](https://pypi.org/project/cc-credentials-manager/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nManages multiple Claude Code OAuth tokens across subscriptions, auto-rotates on\nrate limit without losing session context, and tracks per-credential usage via\nhooks. Includes an interactive TUI and a drop-in autonomous runner (`claude-auto`).\n\n## Prerequisites\n\n- **Python 3.11+**\n- **uv** — https://docs.astral.sh/uv/getting-started/installation/\n- **Claude Code CLI** — `npm install -g @anthropic-ai/claude-code` (the `claude` binary must be on PATH — the Agent SDK calls it as a subprocess)\n\n## Install\n\n```bash\nuv tool install cc-credentials-manager\n```\n\nOr directly from GitHub:\n\n```bash\nuv tool install git+https://github.com/Kydoimos97/cc-credentials-manager.git\n```\n\nThis puts two binaries on PATH: `cc-creds` and `claude-auto`.\n\n## Setup\n\n**Step 1 — generate a long-lived token for each Claude subscription:**\n\n```bash\nclaude auth login       # authenticate with your Claude account\nclaude setup-token      # prints a sk-ant-oat... token valid for 1 year\n```\n\n**Step 2 — register it:**\n\n```bash\ncc-creds add \u003ctoken\u003e --label \"account-name\"\n```\n\nThe token is verified against the API immediately. The first credential added\nbecomes active automatically.\n\n**Step 3 — install session tracking hooks:**\n\n```bash\ncc-creds install-hook\n```\n\nRegisters `Stop`, `StopFailure`, and `UserPromptSubmit` hooks in\n`~/.claude/settings.json`. Creates the file if it does not exist yet.\n\nThat's it. Use `claude` normally — all sessions are tracked automatically.\n\nThe active credential is stored on disk in `~/.cc-creds/`. `claude-auto` reads it\nat startup and passes the token explicitly to each run — no global environment\ninjection, so interactive `claude` sessions are never affected.\n\n## Commands\n\n### Credential management\n\n```\ncc-creds                              open the interactive TUI (Credentials, Stats, Usage tabs)\ncc-creds add \u003ctoken\u003e [--label NAME]   register and verify a new credential\ncc-creds list                         list all credentials with live API status\ncc-creds status                       show auth mode and active label (no API call)\ncc-creds status --verify              re-verify token against API, show full status\ncc-creds status --json                machine-readable JSON output for scripts/statusline\ncc-creds status --label               print just the active label — safe for hooks/scripts\ncc-creds set-active \u003clabel-or-id\u003e     switch active credential\ncc-creds remove \u003clabel-or-id\u003e         remove a credential (scrubs token from registry and settings.json if active)\ncc-creds deactivate                   clear active credential, return to full OAuth session\ncc-creds rotate                       advance to next available credential\ncc-creds install-hook                 register session tracking hooks in ~/.claude/settings.json\n```\n\n**TUI keybindings (Credentials tab):**\n\n```\na       add new credential (opens token + label form)\nd       delete selected credential\nenter   set selected as active\nr       rotate to next available credential\ni       install session tracking hooks\nv       verify selected credential against the API\nq       quit\n```\n\n### Autonomous runner\n\n```\nclaude-auto \"prompt\"                  run a prompt non-interactively\nclaude-auto -p \"prompt\"               same, -p flag for muscle memory\nclaude-auto -f prompt.txt             read prompt from file\nclaude-auto --cwd /path/to/project    set working directory (default: cwd)\nclaude-auto --resume \u003csession-id\u003e     resume a specific session\n```\n\nAutomatically picks the active credential, rotates on rate limit, and resumes\nthe same session with the new token.\n\n## How it works\n\n### Credential store — `~/.cc-creds/`\n\n```\ncredentials.json    registered tokens with labels and expiry\ncred-status.json    per-credential status: available / limited / admin_disabled\nactive.key          currently active credential ID (absent when deactivated)\nsessions.jsonl      session registry with cost and token data\nenv                 shell env file written on non-Windows (source from .bashrc/.zshrc)\n```\n\n### Auth modes\n\ncc-creds supports two modes which can be switched at any time without restarting\nyour session:\n\n**OAuth2-Full (default)** — `claude` uses your real OAuth session with full scope.\nRemote Control, billing, and all Claude Code features work normally. This is the\ndefault when no credential is active.\n\n**LLT-Limited** — a long-lived token is active. Claude Code uses that token for\nAPI calls, which means usage comes from the associated subscription quota. Some\nfeatures that require the full OAuth session (e.g. Remote Control) are unavailable.\n\nSwitch modes:\n```bash\ncc-creds set-active \u003clabel\u003e   # activate an LLT — persists to user env vars\ncc-creds deactivate           # return to OAuth2-Full — clears user env vars\n```\n\n`set-active` writes the token to the Windows user environment (`HKCU\\Environment`)\nso new terminals and Claude Code sessions inherit it. `deactivate` removes it.\nNeither touches `settings.json` — that would break interactive sessions.\n\n`claude-auto` always reads the active credential from disk and passes the token\nexplicitly per run, regardless of what is in the shell environment.\n\n### Session tracking\n\nHooks registered by `install-hook` fire on every session:\n- `UserPromptSubmit` — registers the session, records rolling cost/token data\n- `Stop` — finalises status to `success`, records final cost/tokens\n- `StopFailure` — detects rate limits, rotates to next credential automatically\n\nCost and token data comes from `$CCODE_HOME/states/sessions/` when the `CCODE_HOME`\nenvironment variable is set and points to your Claude Code data directory. Without\nit, the `Stop` hook falls back to parsing the Claude transcript JSONL directly —\nthis path is less accurate and does not report rolling cost during active sessions\n(`UserPromptSubmit`). Set `CCODE_HOME` for reliable tracking.\n\n### Rate limit rotation\n\nWhen a rate limit is hit mid-session, `claude-auto`:\n1. Catches the `RateLimitEvent` or `ProcessError` from the SDK\n2. Marks the current credential as limited with the reset time when available (parsed from session state or assistant text; may be absent if not reported)\n3. Rotates to the next available credential\n4. Resumes the same session with `ClaudeAgentOptions(resume=session_id)`\n\nInteractive `claude` sessions are handled by the `StopFailure` hook — Claude\nrotates the active credential and the next session starts with the fresh token.\n\n## Testing rotation\n\n```bash\n# Force-skip credential 1 (in-memory only, no store write):\nCC_CREDS_FORCE_LIMIT_1=1 claude-auto \"hello\"\n\n# Exhaust all credentials:\nCC_CREDS_FORCE_LIMIT_1=1 CC_CREDS_FORCE_LIMIT_2=1 claude-auto \"hello\"\n```\n\n## Debug logging\n\n```bash\nCC_CREDS_DEBUG=1 cc-creds status\nCC_CREDS_DEBUG=1 cc-creds list\nCC_CREDS_DEBUG=1 claude-auto \"hello\"\n```\n\nOutputs structured Rich logs to stderr: API calls with full response headers,\nSDK message stream, rotation decisions, session registration.\n\n## Statusline integration\n\nIf you use a Claude Code statusline script, `cc-creds status --json` returns:\n```json\n{\"mode\": \"LLT-Limited\", \"label\": \"account-name\"}\n{\"mode\": \"OAuth2-Full\", \"label\": null}\n```\nUse this to display the current auth mode in your statusline.\n\n## Troubleshooting\n\n**Hooks not firing or showing errors**\n\nCheck that `cc-creds install-hook` ran successfully and that `~/.claude/settings.json`\ncontains entries under `hooks.Stop`, `hooks.StopFailure`, and `hooks.UserPromptSubmit`.\nHook payloads are JSON objects sent via stdin — the `hook-event` handler expects\n`session_id`, `type`, and `cwd` fields. If Claude Code changes its hook payload\nschema, the handler will silently skip unrecognised payloads.\n\n**`cc-creds list` shows \"unknown\" status after a network error**\n\nStatus checks that fail due to network errors (timeout, DNS failure) are retried\nafter 5 minutes. A credential in \"unknown\" state is treated as available for\nrotation — it will be re-verified the next time rotation tries to use it.\n\n**Credential removed but old token still active in a new terminal**\n\n`cc-creds remove` scrubs the token from `HKCU\\Environment` and `settings.json`\nwhen the removed credential was active. Open a new terminal after removing an\nactive credential to pick up the cleared environment.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkydoimos97%2Fcc-credentials-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkydoimos97%2Fcc-credentials-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkydoimos97%2Fcc-credentials-manager/lists"}