cctop-tui 0.1.0__tar.gz

cctop_tui-0.1.0/.claude/skills/cctop-setup/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: cctop-setup
+description: Install and configure cctop, the multi-account Claude Code usage monitor, for the user. Use when the user wants to set up / install cctop, get it running, or add a Claude account (subscription) for it to track. STRICTLY ADDITIVE: this skill only installs and adds; it must never delete, remove, rewrite, or reconfigure any existing files, credentials, sessions, aliases, or shell config.
+---
+
+# cctop setup
+
+Set up cctop (a live TUI that monitors multiple Claude Code sessions and
+subscription usage) for the user. Everything here is additive and safe.
+
+## Absolute safety rules (do not violate)
+
+1. **Never delete or remove anything** — no `rm`, no removing files, dirs,
+   sessions, accounts, aliases, or credentials. cctop itself has no delete
+   operation; do not add one or work around its absence.
+2. **Never modify existing configuration in place** — do not edit, rewrite, or
+   reorder existing lines in `~/.zshrc`, `~/.bashrc`, `settings.json`,
+   `.claude.json`, `config.toml`, or any other config the user already has. The
+   only permitted change to a shell rc file is the **append** performed by
+   `cctop add-account --alias NAME` (which backs the file up first and is
+   idempotent); without `--alias`, add-account never touches a shell rc file.
+3. **Never log out, revoke, or touch credentials** — do not run `claude logout`,
+   `codex logout`, delete `.credentials.json`, or read/print any token.
+4. **Confirm before any change outside the repo** — installing into the repo's
+   own `.venv` is fine without asking. Adding an account (which appends a shell
+   alias and creates a new `~/.claude-N` dir) requires explicit user
+   confirmation first; show the dry-run plan and wait for a yes.
+5. If the user asks to **remove/delete/reset** an account or setup, decline and
+   explain that cctop is intentionally additive-only to avoid ever breaking a
+   working setup. Offer to point them at the manual steps instead, but do not do
+   it for them.
+
+## Step 1 — Install
+
+Work in the cloned repo directory. Prefer `uv`; fall back to `python -m venv`.
+
+```bash
+# from the repo root
+uv venv --python 3.12 && uv pip install -e .
+# fallback if uv is unavailable:
+# python3 -m venv .venv && .venv/bin/pip install -e .
+```
+
+Verify it imports and runs (read-only):
+
+```bash
+.venv/bin/cctop --once        # one-shot snapshot; should print the table
+.venv/bin/cctop accounts      # lists discovered accounts (read-only)
+```
+
+If `cctop --once` works, installation is done. Tell the user how to launch the
+live TUI: `.venv/bin/cctop` (keys: `s` stats, `r` refresh limits, `R` refresh
+token, `a` add account, `q` quit), and suggest they add a shell alias like
+`alias cctop='<repo>/.venv/bin/cctop'` — but only append it, and only if they
+want it.
+
+## Step 2 — Accounts (only if the user wants to add one)
+
+cctop auto-discovers every `~/.claude` (cc-0) and `~/.claude-<N>` (cc-<N>)
+account, so existing accounts need no setup — just confirm they show up in
+`cctop accounts`. No shell alias is required for cctop to see an account.
+
+To add a **new** subscription/account, use the built-in additive command. Always
+show the dry-run first, get confirmation, then apply:
+
+```bash
+.venv/bin/cctop add-account                      # dry-run: prints the plan, changes nothing
+.venv/bin/cctop add-account --login              # ONLY after the user confirms: create dir + sign in
+.venv/bin/cctop add-account --from cc-0 --login  # ...also clone cc-0's user config into the new account
+.venv/bin/cctop add-account --alias cc-2 --login # ...and set an explicit cc-2 shell alias
+```
+
+What each flag does, all additive:
+
+- **No flag** creates only the next `~/.claude-N` dir (or reuses an existing
+  logged-out one). It does **not** write a shell alias.
+- **`--alias NAME`** (opt-in only) backs up the rc file and appends one alias
+  line. Never automatic.
+- **`--from ACCOUNT`** copies an allowlist of user config only (`CLAUDE.md`,
+  `settings.json`, `commands/ agents/ skills/ hooks/ output-styles/`); it never
+  copies `.claude.json`, credentials, or session state, never overwrites an
+  existing file, and never modifies the source.
+- **`--login`** runs `claude auth login` scoped to the new dir so the user signs
+  in themselves (browser flow); it is isolated to the new account and cannot
+  touch another. This is a sign-**in**, never a logout.
+
+After applying, if an alias was set tell the user to `source ~/.zshrc` (or open a
+new shell) to use it. cctop picks the account up automatically either way.
+
+## Step 3 — Confirm
+
+Run `cctop accounts` once more and show the user the result: each account with
+its tier, whether a token is present, and its live session count. Point out that
+usage limits and stats are read for free (no tokens consumed), and that nothing
+was deleted or modified.
+
+## What NOT to do (recap)
+
+- No `rm`, no `logout`, no editing existing config lines, no deleting sessions
+  or accounts, no reading/printing tokens.
+- The only writes you may perform: create the repo `.venv`, and (with
+  confirmation) run `cctop add-account --apply`, which is additive and backed up.

cctop_tui-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    name: ${{ matrix.os }} / py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install project (with dev extras) into a venv
+        run: |
+          uv venv
+          uv pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: uv run ruff check src tests
+
+      - name: Ruff format
+        run: uv run ruff format --check src tests
+
+      - name: Mypy
+        run: uv run mypy
+
+      - name: Tests
+        run: uv run pytest -q

cctop_tui-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.DS_Store
+references/

cctop_tui-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

cctop_tui-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to
+follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- The USAGE panel now wraps account blocks onto multiple rows and sizes bars to
+  the terminal width, reflowing live on resize instead of overflowing when many
+  accounts or a narrow window are in play.
+- Live TUI monitoring Claude Code and OpenAI Codex sessions side by side, with
+  real usage-limit gauges from the free `/api/oauth/usage` and Codex usage GETs.
+- GitHub-style activity heatmaps and lifetime stats, per provider.
+- Delegated token refresh (`R`): renews an account's OAuth token via the owning
+  binary, without cctop ever writing a credential.
+- One-step account provisioning (`add-account --login` / the `a` key): create,
+  optionally clone user config from another account (`--from`, allowlisted), set
+  an explicit alias (`--alias`, never automatic), and sign in.
+- `cctop doctor`: a read-only self-check (platform, claude/codex binaries, and
+  each account's credential, token expiry, tier, and live-session count).
+- A never-started usage window (0% with no reset) now renders "no usage yet"
+  instead of a misleading empty 0% bar, and a `percent` value carrying a reset
+  epoch (a known upstream bug) is guarded instead of shown as a full bar.
+- Rate-limit resilience: per-account backoff (Retry-After aware) that keeps the
+  last good usage numbers instead of blanking on a transient 429/5xx/network
+  failure, and a refresh that will not "refresh into another 429".
+- Test suite, `ruff`/`mypy` gates, and CI across Python 3.11-3.13 on macOS
+  (macOS-only for the first release; Linux support is future work).
+- `LICENSE` (MIT), `SECURITY.md`, and packaging metadata (distribution
+  `cctop-tui`; the command stays `cctop`).
+
+[Unreleased]: https://github.com/ryanirl/cctop/commits/main

cctop_tui-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cctop_tui-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: cctop-tui
+Version: 0.1.0
+Summary: A live terminal monitor for multiple Claude Code and OpenAI Codex accounts, in the spirit of nvtop/htop.
+Project-URL: Homepage, https://github.com/ryanirl/cctop
+Project-URL: Repository, https://github.com/ryanirl/cctop
+Project-URL: Issues, https://github.com/ryanirl/cctop/issues
+Author: Ryan 'RyanIRL' Peters
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anthropic,claude,claude-code,cli,codex,monitoring,nvtop,openai,tui,usage
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: rich>=13.0
+Requires-Dist: textual>=0.60
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cctop
+
+[![CI](https://github.com/ryanirl/cctop/actions/workflows/ci.yml/badge.svg)](https://github.com/ryanirl/cctop/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-teal.svg)](LICENSE)
+![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)
+![macOS](https://img.shields.io/badge/macOS-only-lightgrey.svg)
+
+A live terminal monitor for your **Claude Code** and **OpenAI Codex** usage, in
+the spirit of `nvtop`/`htop`. It **auto-detects your accounts** (your Claude
+account and your Codex account both work out of the box, no setup), shows real
+usage-limit gauges and every running session, and gives a GitHub-style view of
+your activity over time. Running more than one Claude subscription? It picks
+those up too.
+
+Everything is read from files the tools already write plus a couple of free,
+read-only usage reads; nothing here ever spends message quota. cctop touches
+your credentials only to make those reads, never logs or transmits a token, and
+is read-only except for two explicit, additive account actions. See
+[SECURITY.md](SECURITY.md) for the full trust statement.
+
+![cctop](https://raw.githubusercontent.com/ryanirl/cctop/main/docs/hero.png)
+
+## What it shows
+
+- **Usage limits** (top panel), per account, side by side: the 5-hour, weekly
+  (all models), and weekly (Fable) windows with utilization, reset countdown,
+  and the currently-binding window marked. These are the real numbers from
+  Anthropic's `GET /api/oauth/usage` endpoint (the same one `/usage` uses) — a
+  free read, no tokens consumed.
+- **Sessions** (table): every live Claude Code process, tagged by account, with
+  status, model, cwd, context %, cumulative tokens, cost, and age. Selecting a
+  row opens a detail panel (full cwd, pid, version, token/cost/context
+  breakdown).
+- **Statistics** (press `s`): a GitHub-style daily-activity heatmap, lifetime
+  totals (messages, sessions, tool calls, active days, longest streak, busiest
+  day), a top-models-by-tokens chart, and a per-account breakdown, all merged
+  from each account's `stats-cache.json`.
+
+## Install
+
+Requires **macOS** and **Python 3.11+** (Linux support is planned).
+
+Once published to PyPI (distribution name `cctop-tui`), the one-liners are:
+
+```bash
+uv tool install cctop-tui     # or: pipx install cctop-tui
+uvx cctop-tui                 # run without installing (starts the `cctop` TUI)
+```
+
+From a clone (current default while pre-release):
+
+```bash
+cd cctop
+uv venv --python 3.12
+uv pip install -e .           # add ".[dev]" for the test/lint tooling
+cctop
+```
+
+## Usage
+
+```bash
+cctop                 # launch the live TUI (default)
+cctop --once          # print a one-shot snapshot and exit
+cctop --json          # emit the snapshot as JSON (for scripting)
+cctop --no-limits     # skip the usage fetch (no network, session table only)
+
+cctop accounts        # list discovered accounts (read-only)
+cctop doctor          # read-only self-check (platform, binaries, token/expiry)
+cctop add-account     # provision a new account (dry-run; see Accounts below)
+```
+
+TUI keys: `s` stats · `r` refresh limits · `R` refresh token · `a` add account ·
+`q` quit.
+
+### Token refresh (`R`)
+
+A Claude Code OAuth access token lives only ~12-15h, and the CLI refreshes it
+lazily when you *use* an account, so an account you are merely monitoring drifts
+past expiry and the usage read starts failing (`token expired`). Press `R` and
+cctop asks the tool that owns the credential to renew it: it runs
+`claude mcp list` under each account's config dir (a quota-free command whose
+startup renews and rewrites the Keychain record). **cctop never writes a
+credential itself** — it only triggers the owner binary and reads the result —
+and it is a no-op on tokens that are still valid. An account whose refresh token
+is itself dead reports "needs re-login" (only a fresh `/login` can fix that).
+
+### Accounts
+
+cctop **auto-detects your accounts** with zero setup: your Claude Code account
+(`~/.claude`) and your Codex account (`~/.codex`) are picked up automatically.
+For most people that is the whole story: install, run `cctop`, done. Run
+`cctop accounts` to see what it found.
+
+**Multiple Claude accounts (optional).** If you run more than one Claude
+subscription in separate config dirs (via `CLAUDE_CONFIG_DIR`), cctop shows them
+all side by side. To add one without leaving cctop, press `a` (or run
+`cctop add-account --login`): it creates the config dir, optionally clones your
+existing config, and signs you in. It is **strictly additive** — it never
+deletes, overwrites, or modifies existing config, credentials, or sessions, and
+only writes a shell alias if you explicitly ask for one.
+
+## How it works
+
+| Data | Claude source | Codex source | Cost |
+|---|---|---|---|
+| Live sessions | `~/.claude*/sessions/<pid>.json` | `ps` + `~/.codex/sessions/` rollouts | free (file/ps) |
+| Tokens / context | transcript JSONL, tailed | rollout `token_count` events | free (file) |
+| Usage limits | `GET /api/oauth/usage` (Keychain token) | `GET chatgpt.com/backend-api/codex/usage` (`~/.codex/auth.json` token) | free (GET) |
+| Statistics | `~/.claude*/stats-cache.json` | aggregated from rollout files | free (file) |
+
+## Providers
+
+cctop tracks both **Claude Code** and **OpenAI Codex** side by side. Claude
+accounts are `cc-0`/`cc-1`/…; a Codex account (`cx-0`, from `~/.codex`) is added
+automatically when present. Usage windows and stats are read per provider (they
+differ in shape: Codex exposes primary/secondary windows plus per-model limits,
+and its stats come from rollout files rather than a stats cache). Codex sessions
+show token/context but no dollar cost, since Codex is subscription-based.
+
+The credential for the usage read is resolved per account from the macOS
+Keychain service `Claude Code-credentials-<sha256(config_dir)[:8]>`, used only to
+authenticate to Anthropic's own API, never logged or persisted. The usage
+response's org is verified against the account so one account can never show
+another's numbers.
+
+Undocumented, version-internal formats (the sessions registry, transcript
+schema, usage JSON) are all read defensively and isolated to the collector core
+(`registry`, `transcript`, `usage`, `stats`, `monitor`, `pricing`, `status`,
+`codex*` for the Codex provider, `authctl` for delegated token refresh, and
+`manage` for additive account provisioning), with a thin Textual presentation
+layer on top.
+
+## Notes
+
+- Pricing (`pricing.py`) is a small editable table; update it as rates change.
+- The palette is the house teal (`#20B2AA`) on monochrome terminal. Usage bars
+  stay teal even when maxed (fullness is the signal); red is reserved for a
+  blocked or dead session.
+
+## Author
+
+Ryan 'RyanIRL' Peters

cctop_tui-0.1.0/README.md

@@ -0,0 +1,142 @@
+# cctop
+
+[![CI](https://github.com/ryanirl/cctop/actions/workflows/ci.yml/badge.svg)](https://github.com/ryanirl/cctop/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-teal.svg)](LICENSE)
+![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)
+![macOS](https://img.shields.io/badge/macOS-only-lightgrey.svg)
+
+A live terminal monitor for your **Claude Code** and **OpenAI Codex** usage, in
+the spirit of `nvtop`/`htop`. It **auto-detects your accounts** (your Claude
+account and your Codex account both work out of the box, no setup), shows real
+usage-limit gauges and every running session, and gives a GitHub-style view of
+your activity over time. Running more than one Claude subscription? It picks
+those up too.
+
+Everything is read from files the tools already write plus a couple of free,
+read-only usage reads; nothing here ever spends message quota. cctop touches
+your credentials only to make those reads, never logs or transmits a token, and
+is read-only except for two explicit, additive account actions. See
+[SECURITY.md](SECURITY.md) for the full trust statement.
+
+![cctop](https://raw.githubusercontent.com/ryanirl/cctop/main/docs/hero.png)
+
+## What it shows
+
+- **Usage limits** (top panel), per account, side by side: the 5-hour, weekly
+  (all models), and weekly (Fable) windows with utilization, reset countdown,
+  and the currently-binding window marked. These are the real numbers from
+  Anthropic's `GET /api/oauth/usage` endpoint (the same one `/usage` uses) — a
+  free read, no tokens consumed.
+- **Sessions** (table): every live Claude Code process, tagged by account, with
+  status, model, cwd, context %, cumulative tokens, cost, and age. Selecting a
+  row opens a detail panel (full cwd, pid, version, token/cost/context
+  breakdown).
+- **Statistics** (press `s`): a GitHub-style daily-activity heatmap, lifetime
+  totals (messages, sessions, tool calls, active days, longest streak, busiest
+  day), a top-models-by-tokens chart, and a per-account breakdown, all merged
+  from each account's `stats-cache.json`.
+
+## Install
+
+Requires **macOS** and **Python 3.11+** (Linux support is planned).
+
+Once published to PyPI (distribution name `cctop-tui`), the one-liners are:
+
+```bash
+uv tool install cctop-tui     # or: pipx install cctop-tui
+uvx cctop-tui                 # run without installing (starts the `cctop` TUI)
+```
+
+From a clone (current default while pre-release):
+
+```bash
+cd cctop
+uv venv --python 3.12
+uv pip install -e .           # add ".[dev]" for the test/lint tooling
+cctop
+```
+
+## Usage
+
+```bash
+cctop                 # launch the live TUI (default)
+cctop --once          # print a one-shot snapshot and exit
+cctop --json          # emit the snapshot as JSON (for scripting)
+cctop --no-limits     # skip the usage fetch (no network, session table only)
+
+cctop accounts        # list discovered accounts (read-only)
+cctop doctor          # read-only self-check (platform, binaries, token/expiry)
+cctop add-account     # provision a new account (dry-run; see Accounts below)
+```
+
+TUI keys: `s` stats · `r` refresh limits · `R` refresh token · `a` add account ·
+`q` quit.
+
+### Token refresh (`R`)
+
+A Claude Code OAuth access token lives only ~12-15h, and the CLI refreshes it
+lazily when you *use* an account, so an account you are merely monitoring drifts
+past expiry and the usage read starts failing (`token expired`). Press `R` and
+cctop asks the tool that owns the credential to renew it: it runs
+`claude mcp list` under each account's config dir (a quota-free command whose
+startup renews and rewrites the Keychain record). **cctop never writes a
+credential itself** — it only triggers the owner binary and reads the result —
+and it is a no-op on tokens that are still valid. An account whose refresh token
+is itself dead reports "needs re-login" (only a fresh `/login` can fix that).
+
+### Accounts
+
+cctop **auto-detects your accounts** with zero setup: your Claude Code account
+(`~/.claude`) and your Codex account (`~/.codex`) are picked up automatically.
+For most people that is the whole story: install, run `cctop`, done. Run
+`cctop accounts` to see what it found.
+
+**Multiple Claude accounts (optional).** If you run more than one Claude
+subscription in separate config dirs (via `CLAUDE_CONFIG_DIR`), cctop shows them
+all side by side. To add one without leaving cctop, press `a` (or run
+`cctop add-account --login`): it creates the config dir, optionally clones your
+existing config, and signs you in. It is **strictly additive** — it never
+deletes, overwrites, or modifies existing config, credentials, or sessions, and
+only writes a shell alias if you explicitly ask for one.
+
+## How it works
+
+| Data | Claude source | Codex source | Cost |
+|---|---|---|---|
+| Live sessions | `~/.claude*/sessions/<pid>.json` | `ps` + `~/.codex/sessions/` rollouts | free (file/ps) |
+| Tokens / context | transcript JSONL, tailed | rollout `token_count` events | free (file) |
+| Usage limits | `GET /api/oauth/usage` (Keychain token) | `GET chatgpt.com/backend-api/codex/usage` (`~/.codex/auth.json` token) | free (GET) |
+| Statistics | `~/.claude*/stats-cache.json` | aggregated from rollout files | free (file) |
+
+## Providers
+
+cctop tracks both **Claude Code** and **OpenAI Codex** side by side. Claude
+accounts are `cc-0`/`cc-1`/…; a Codex account (`cx-0`, from `~/.codex`) is added
+automatically when present. Usage windows and stats are read per provider (they
+differ in shape: Codex exposes primary/secondary windows plus per-model limits,
+and its stats come from rollout files rather than a stats cache). Codex sessions
+show token/context but no dollar cost, since Codex is subscription-based.
+
+The credential for the usage read is resolved per account from the macOS
+Keychain service `Claude Code-credentials-<sha256(config_dir)[:8]>`, used only to
+authenticate to Anthropic's own API, never logged or persisted. The usage
+response's org is verified against the account so one account can never show
+another's numbers.
+
+Undocumented, version-internal formats (the sessions registry, transcript
+schema, usage JSON) are all read defensively and isolated to the collector core
+(`registry`, `transcript`, `usage`, `stats`, `monitor`, `pricing`, `status`,
+`codex*` for the Codex provider, `authctl` for delegated token refresh, and
+`manage` for additive account provisioning), with a thin Textual presentation
+layer on top.
+
+## Notes
+
+- Pricing (`pricing.py`) is a small editable table; update it as rates change.
+- The palette is the house teal (`#20B2AA`) on monochrome terminal. Usage bars
+  stay teal even when maxed (fullness is the signal); red is reserved for a
+  blocked or dead session.
+
+## Author
+
+Ryan 'RyanIRL' Peters

cctop_tui-0.1.0/SECURITY.md

@@ -0,0 +1,56 @@
+# Security & trust
+
+cctop reads local files that Claude Code and Codex already write, plus a small
+number of free, read-only API calls. It touches OAuth tokens only to the extent
+required to make those reads. This document states exactly what it does and does
+not do, because a tool that sits next to your credentials should be auditable.
+
+## What cctop reads
+
+| Source | Purpose |
+|---|---|
+| `~/.claude*/sessions/<pid>.json`, transcripts, `stats-cache.json` | live sessions, tokens, cost, activity |
+| `~/.codex/sessions/**` rollout files, `ps` | live Codex sessions and stats |
+| `GET https://api.anthropic.com/api/oauth/usage` | real Claude usage limits (the endpoint `/usage` uses) |
+| `GET https://chatgpt.com/backend-api/codex/usage` | real Codex usage limits |
+| macOS Keychain item `Claude Code-credentials-<hash>`, or `~/.claude*/.credentials.json` | the OAuth token used to authenticate the two GETs above |
+| `~/.codex/auth.json` | the token used to authenticate the Codex usage GET |
+
+All of it is read-only. The two usage GETs are plain reads that consume no
+message quota.
+
+## What cctop does with your token
+
+- It reads the token for an account **only from that account's own store** (its
+  per-config-dir Keychain service or its own credentials file), never from a
+  shared default, so one account can never be authenticated with another's
+  token. The usage response's organization is additionally verified against the
+  account.
+- The token is placed in the `Authorization` header of the usage GET and used
+  nowhere else.
+- The token is **never** logged, printed, written to disk by cctop, included in
+  `--json` output, or transmitted anywhere except the provider's own API
+  (`api.anthropic.com` / `chatgpt.com`) that issued it.
+
+## The only things cctop ever writes
+
+cctop is read-only except for two explicit, additive actions you invoke:
+
+1. **Account provisioning** (`add-account`, the `a` key): creates a new
+   `~/.claude-N` directory; with `--alias` appends one shell-rc line (after
+   backing the file up); with `--from` copies an allowlist of *user config*
+   (`CLAUDE.md`, `settings.json`, `commands/agents/skills/hooks/output-styles`)
+   — never credentials, identity (`.claude.json`), or session state. It never
+   deletes, overwrites, or edits existing lines.
+2. **Token refresh** (the `R` key): runs `claude mcp list` for an account so the
+   **Claude Code binary itself** renews its own token at startup (a quota-free,
+   non-interactive command). cctop does not write the credential; it delegates
+   to the tool that owns it.
+
+There is deliberately **no** delete, logout, or credential-writing path in
+cctop's own code.
+
+## Reporting
+
+This is a personal project; open an issue for anything that looks wrong. If you
+find a genuine credential-handling flaw, please report it privately first.

cctop_tui-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "cctop-tui"
+version = "0.1.0"
+description = "A live terminal monitor for multiple Claude Code and OpenAI Codex accounts, in the spirit of nvtop/htop."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ryan 'RyanIRL' Peters" }]
+keywords = [
+    "claude",
+    "claude-code",
+    "codex",
+    "anthropic",
+    "openai",
+    "tui",
+    "monitoring",
+    "usage",
+    "nvtop",
+    "cli",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+    "Topic :: System :: Monitoring",
+]
+dependencies = ["rich>=13.0", "textual>=0.60"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.6", "mypy>=1.11", "pre-commit>=3.7"]
+
+[project.urls]
+Homepage = "https://github.com/ryanirl/cctop"
+Repository = "https://github.com/ryanirl/cctop"
+Issues = "https://github.com/ryanirl/cctop/issues"
+
+[project.scripts]
+cctop = "cctop.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cctop"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W", "C4"]
+# B008: several call sites legitimately use defaults from calls.
+# UP017: the code consistently uses timezone.utc; rewriting to datetime.UTC is
+# churn without benefit.
+ignore = ["B008", "UP017"]
+
+[tool.mypy]
+python_version = "3.11"
+files = ["src/cctop"]
+ignore_missing_imports = true
+check_untyped_defs = true
+warn_redundant_casts = true
+no_implicit_optional = true