# codex-tool

**Repository Path**: Avilia/codex-to

## Basic Information

- **Project Name**: codex-tool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Codex Balance Widget

A small Windows PowerShell/WinForms tray widget that shows the remaining API
balance in the Windows notification area.

The widget reads:

- `CODEX_HOME\config.toml` for the OpenAI-compatible provider `base_url`
- `CODEX_HOME\auth.json` for `OPENAI_API_KEY`

It queries:

- `<base_url>/v1/usage`

Only the remaining balance number is displayed. Secrets are not copied into this
repository.

## Run

```powershell
wscript.exe D:\D\codex\balance-widget\launch-balance-widget-watcher.vbs
```

The watcher runs without a console window. It starts the tray widget only while
the local Codex desktop app is running, and both the watcher and tray widget are
single-instance guarded so repeated launches do not create duplicate icons.

The tray widget only refreshes the balance API while the local Codex desktop app
is running and its lifecycle event stream reports an active task, or when
Refresh now is clicked manually. It reads Codex's structured `task_started`,
`task_complete`, and `turn_aborted` events instead of guessing from child
processes. Current Codex package paths using either `OpenAI.Codex` or
`OpenAI\Codex` are recognized. Large session files are initialized from their
recent tail and then followed incrementally, so startup does not require reading
old multi-month logs from the beginning. When Codex is idle, the tray icon stays
black and keeps showing the most recent cached balance number. When Codex exits,
the tray widget exits after a short grace period; the watcher remains hidden and
waits for the next Codex launch.

The tray icon renders a compact integer balance number as a high-contrast
rounded rectangle with white text. It is black while idle and deep red while a
local Codex task is active. Activity is checked every 5 seconds; balance
refreshes are throttled to 60 seconds. Hover it to see the full two-decimal
balance. Right-click it for refresh/open/quit actions.

## Install At Startup

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File D:\D\codex\balance-widget\install-startup.ps1
```

The startup entry launches the hidden watcher, not the tray widget directly.
It uses `assets\codex-token-dashboard.ico` as the shortcut icon.

## Install Desktop Shortcut

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File D:\D\codex\balance-widget\install-desktop-shortcut.ps1
```

The desktop shortcut launches the same hidden watcher and uses the token
dashboard icon.

## Uninstall Startup Entry

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File D:\D\codex\balance-widget\uninstall-startup.ps1
```