Skip to content

[codex] Add quota spend forecasting #145

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
xodapi wants to merge 5 commits into
base: main
Choose a base branch
from
Draft

[codex] Add quota spend forecasting #145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0024e5b
Add quota spend forecasting
xodapi Jun 21, 2026
637dcb1
feat: collect Factory Droid sessions, models, missions, and token usage
xodapi Aug 8, 2026
06edf8e
docs: restructure README for Factory Droid fork
xodapi Aug 8, 2026
dfaefec
feat: add Factory Droid context % from lastCallTokenUsage + fix READM…
xodapi Aug 8, 2026
e15d42c
perf: speed up Factory and opencode collectors on Windows
xodapi Aug 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
179 changes: 63 additions & 116 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,143 +1,102 @@
# abtop
# abtop — Factory Droid edition

**Like [btop](https://github.com/aristocratos/btop), but for your AI coding agents.**

See every Claude Code, Codex CLI, and OpenCode session at a glance — token usage, context window %, rate limits, child processes, open ports, and more.
Claude Code, Codex CLI, and OpenCode sessions are discovered from local process/file state, so multiple active profiles are supported across macOS, Linux, and Windows.
Monitor Claude Code, Codex CLI, OpenCode, and **Factory Droid** sessions at a glance — token usage, context window %, rate limits, child processes, open ports, and more. All read-only, from local files and processes. No API keys, no auth.

![demo](https://raw.githubusercontent.com/graykode/abtop/main/assets/demo.gif)
> **Fork notice.** This is a fork of [graykode/abtop](https://github.com/graykode/abtop). Everything upstream is preserved; the additions live under [What's different](#whats-different).

## Why
![demo](https://raw.githubusercontent.com/graykode/abtop/main/assets/demo.gif)

- Running 3+ agents across projects? See them all in one screen.
- Hitting rate limits? Watch your quota in real-time.
- Agent spawned a server and forgot to kill it? Orphan port detection.
- Context window filling up? Per-session % bars with warnings.
## Features

All read-only. No API keys. No auth.
- Single-screen monitoring for **Claude Code**, **Codex CLI**, **OpenCode**, and **Factory Droid**.
- **Factory Droid**: live sessions + worker subagents, custom-model catalog, missions, and config validation — read from `~/.factory`.
- **Accurate token tracking for Factory Droid**: usage is parsed from `sessions/**/<sessionId>.settings.json` → `tokenUsage`; worker tokens are attributed via the parent's `childInclusiveTokenUsageBySessionId`.
- Real-time rate limits, context window %, per-session token rate, orphan port detection.
- 12 built-in themes (4 colorblind-friendly), EN/ZH UI, runtime config overlay.

## Install
## What's different

### macOS / Linux
Main change: a **Factory Droid collector** (`src/collector/factory.rs`) plus two new panels.

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/graykode/abtop/releases/latest/download/abtop-installer.sh | sh
```
| Area | Upstream | This fork |
|---|---|---|
| Factory Droid | — | ✅ sessions, models, missions, config validation |
| Token usage (Factory Droid) | — | ✅ from `*.settings.json` → `tokenUsage` |
| Worker subagent tokens | — | ✅ from `childInclusiveTokenUsageBySessionId` |
| Models / missions panels | — | ✅ toggle with `8` / `9` |
| JSON snapshot | — | `factory` block (models, missions, issues) |

### Cargo
**Token fix** (commit `637dcb1`): Factory Droid does not write token usage into session `.jsonl` logs — it lives in `sessions/**/<sessionId>.settings.json`. The collector now scans and parses those files, which populates the Tokens column, the tokens panel, footer totals, and the token rate.

```bash
cargo install abtop
```
## Install / Build

### Windows
The fork ships as source. Build it yourself:

Native support — no WSL required. Uses `sysinfo` for process info and `netstat -ano` for listening ports.
```bash
# Build from source (Windows / macOS / Linux — native, no WSL required)
cargo build --release

```powershell
powershell -c "irm https://github.com/graykode/abtop/releases/latest/download/abtop-installer.ps1 | iex"
# Install from the local checkout
cargo install --path .
```

Or `cargo install abtop` from any terminal with Git in PATH. Claude Code config is resolved automatically from `%USERPROFILE%\.claude`.

### Other

Pre-built binaries for all platforms are available on the [GitHub Releases](https://github.com/graykode/abtop/releases) page.
Pre-built binaries: upstream [releases](https://github.com/graykode/abtop/releases).

## Usage

```bash
abtop # Launch TUI
abtop --once # Print snapshot and exit
abtop --json # Print one JSON snapshot and exit (for scripts/tools)
abtop --json # One JSON snapshot and exit (for scripts/tools)
abtop --status-json # Compact status JSON without local paths/prompts
abtop --setup # Install rate limit collection hook
abtop --theme dracula # Launch with a specific theme
```

Recommended terminal size: **120x40** or larger. Minimum 80x24 — panels hide gracefully when small.

### tmux
Recommended terminal size: **120x40**. Minimum 80x24 — panels degrade gracefully.

abtop works standalone, but running inside tmux unlocks session jumping — press `Enter` to switch directly to the pane running that agent.
Factory Droid models/missions panels are off by default. Toggle at runtime with `8` / `9`, or enable in `~/.config/abtop/config.toml`:

```bash
tmux new -s work
# pane 0: abtop
# pane 1: claude (project A)
# pane 2: claude (project B)
# → Enter on a session in abtop jumps to its pane
```toml
show_models = true
show_missions = true
```

## Supported Agents

| Feature | Claude Code | Codex CLI | OpenCode |
| ----------------- | :---------: | :-------: | :------: |
| Session Discovery | ✅ | ✅ | ✅ |
| Token Tracking | ✅ | ✅ | ✅ |
| Context Window % | ✅ | ✅ | ❌ |
| Status Detection | ✅ | ✅ | ✅ |
| Current Task | ✅ | ✅ | ❌ |
| Rate Limit | ✅ | ✅ | ❌ |
| Git Status | ✅ | ✅ | ✅ |
| Children / Ports | ✅ | ✅ | ✅ |
| Subagents | ✅ | ❌ | ❌ |
| Memory Status | ✅ | ❌ | ❌ |

OpenCode support reads the local SQLite database at `~/.local/share/opencode/opencode.db` and requires `sqlite3` in `PATH`.
`hidden_agents = ["factory"]` disables the Factory Droid collector entirely.

## Themes

12 built-in themes, including 4 colorblind-friendly options (`high-contrast`, `protanopia`, `deuteranopia`, `tritanopia`). Press `t` to cycle at runtime, or launch with `--theme <name>`. Your choice is saved to `~/.config/abtop/config.toml`.

| btop (default) | dracula | catppuccin |
|:-:|:-:|:-:|
| ![btop](https://raw.githubusercontent.com/graykode/abtop/main/assets/themes/btop.png) | ![dracula](https://raw.githubusercontent.com/graykode/abtop/main/assets/themes/dracula.png) | ![catppuccin](https://raw.githubusercontent.com/graykode/abtop/main/assets/themes/catppuccin.png) |

| tokyo-night | gruvbox | nord |
|:-:|:-:|:-:|
| ![tokyo-night](https://raw.githubusercontent.com/graykode/abtop/main/assets/themes/tokyo-night.png) | ![gruvbox](https://raw.githubusercontent.com/graykode/abtop/main/assets/themes/gruvbox.png) | ![nord](https://raw.githubusercontent.com/graykode/abtop/main/assets/themes/nord.png) |

Colorblind-friendly themes:

| high-contrast | protanopia |
|:-:|:-:|
| ![high-contrast](https://raw.githubusercontent.com/graykode/abtop/main/assets/themes/high-contrast.png) | ![protanopia](https://raw.githubusercontent.com/graykode/abtop/main/assets/themes/protanopia.png) |

| deuteranopia | tritanopia |
|:-:|:-:|
| ![deuteranopia](https://raw.githubusercontent.com/graykode/abtop/main/assets/themes/deuteranopia.png) | ![tritanopia](https://raw.githubusercontent.com/graykode/abtop/main/assets/themes/tritanopia.png) |

Light themes (`light` — Solarized cream, `white` — GitHub-style pure white) for bright terminals:
## Supported Agents

| light | white |
|:-:|:-:|
| ![light](https://raw.githubusercontent.com/graykode/abtop/main/assets/themes/light.png) | ![white](https://raw.githubusercontent.com/graykode/abtop/main/assets/themes/white.png) |
| Feature | Claude Code | Codex CLI | OpenCode | Factory Droid |
| ----------------- | :---------: | :-------: | :------: | :-----------: |
| Session Discovery | ✅ | ✅ | ✅ | ✅ |
| Token Tracking | ✅ | ✅ | ✅ | ✅ |
| Context Window % | ✅ | ✅ | ❌ | ❌ |
| Status Detection | ✅ | ✅ | ✅ | ✅ |
| Current Task | ✅ | ✅ | ❌ | ✅ |
| Rate Limit | ✅ | ✅ | ❌ | ❌ |
| Git Status | ✅ | ✅ | ✅ | ❌ |
| Children / Ports | ✅ | ✅ | ✅ | ❌ |
| Subagents | ✅ | ❌ | ❌ | ✅ |
| Memory Status | ✅ | ❌ | ❌ | ❌ |

Factory Droid support reads `~/.factory`: live sessions from `sessions-index.json` (orchestrator plus worker subagents), token usage from `sessions/**/<sessionId>.settings.json`, the custom-model catalog from `settings.json` / `factory-settings.json`, missions from `missions/<id>/`, and a config validator that flags duplicate ids, dangling default model references, and stale state files. API keys are never read.

## Configuration

`~/.config/abtop/config.toml` supports:
`~/.config/abtop/config.toml`:

```toml
theme = "btop"
# Hide specific agent CLIs from the TUI (case-insensitive).
# Useful if you only use one agent and want a cleaner view.
hidden_agents = ["codex"]
# Additional Claude Code profile roots to scan.
# abtop also auto-discovers ~/.claude and ~/.claude-* roots that contain
# both sessions/ and projects/.
show_models = true
show_missions = true
claude_config_dirs = ["~/.claude-personal", "~/.claude-work-team"]
# UI language. Omit or leave empty to auto-detect from LANG.
language = "zh"
```

### Supported Languages

| Code | Language |
| ---- | ------------------- |
| `en` | English (default) |
| `zh` | Simplified Chinese |

When `language` is unset, abtop auto-detects from `LANG` — any value starting with `zh` switches to Simplified Chinese, otherwise English.
UI language: `en` (default) or `zh`; auto-detected from `LANG` when unset.

## Key Bindings

Expand All @@ -148,25 +107,23 @@ When `language` is unset, abtop auto-detects from `LANG` — any value starting
| `x` | Kill selected session |
| `X` | Kill all orphan ports |
| `t` | Cycle theme |
| `1`–`5` | Toggle panel visibility |
| `1`–`9` | Toggle panel visibility |
| `Esc` | Open/close config page |
| `q` | Quit |
| `r` | Force refresh |

## Library / JSON snapshot

abtop is also a library crate, so local tools can reuse its data-collection
layer in-process — no re-scanning, no subprocesses — and serialize the same
state the TUI renders.
abtop is also a library crate, so local tools can reuse its data-collection layer in-process and serialize the same state the TUI renders:

```bash
abtop --json # one-shot JSON snapshot for scripts
abtop --json # one-shot JSON snapshot for scripts
abtop --status-json # compact status summary; omits local paths, prompts, session ids
```

For long-running consumers, build an `App`, refresh it with
`App::tick_no_summaries()` (which never spawns `claude --print`, so it doesn't
touch your Claude quota), and call `App::to_snapshot(interval_ms)` to get a
JSON-serializable [`Snapshot`]:
The **JSON snapshot includes** `chat_messages`, `summary`, working directories, tool-call previews, token counts, and a `factory` block — matching the TUI view.

For long-running consumers, build an `App`, refresh with `App::tick_no_summaries()` (never spawns `claude --print`), and call `App::to_snapshot(interval_ms)`:

```rust,no_run
use abtop::app::App;
Expand All @@ -180,19 +137,9 @@ app.tick_no_summaries();
let json = serde_json::to_string(&app.to_snapshot(2_000)).unwrap();
```

`App` is not `Send` (it owns the collectors), so keep it on one thread and pass
the serialized JSON elsewhere. [abtop-web-ui](https://github.com/XKHoshizora/abtop-web-ui)
is a reference consumer: a local-first web dashboard built on exactly this API.

## Privacy

abtop reads local files and local process/open-file metadata only. No API keys, no auth. In the TUI and `--once` output, tool names and file paths are shown, but file contents and prompt text are never displayed. Session summaries are generated via `claude --print`, which makes its own API call — this is the only indirect network usage.

The JSON snapshot includes richer local dashboard data, including `summary`, `chat_messages`, working directories, config roots, tool-call previews, child process commands, token counts, and port metadata. Chat text is bounded and redacted by the collectors, but it is still derived from local transcripts and may contain sensitive project context. Treat JSON snapshots as local/private data and avoid writing them to shared logs or exposing them on a network without your own access controls.

## Acknowledgements

Huge thanks to [@tbouquet](https://github.com/tbouquet) for driving much of abtop's recent shape — themes, config overlay and panel toggles, session filtering, subagent tree view, the context window gauge with compaction detection, plus a steady stream of fixes and security hardening along the way.
abtop reads local files and local process/open-file metadata only. No API keys, no auth. Tool names and file paths are shown, but file contents and prompt text are never displayed. The full `--json` snapshot includes local dashboard data (`chat_messages`, `summary`, working directories, tool-call previews, token counts) plus a `factory` block — treat it as private and don't expose it without your own access controls. `--status-json` emits only aggregate health/quota fields and **omits local paths**.

## License

Expand Down
Loading