agent-tank 0.9.3 → 0.9.5

package/README.md

@@ -2,286 +2,268 @@
 
 ![Agent Tank Web UI preview](https://raw.githubusercontent.com/integry/agent-tank/main/media/www-preview.png)
 
-Monitor and query usage limits for LLM CLI tools (Claude, Gemini, Codex) via a simple HTTP API.
+Agent Tank is a local dashboard and HTTP API for monitoring usage limits in AI coding agent CLIs.
 
-> **Note:** Agent Tank is designed for **AI coding agent subscriptions** such as Claude Code Pro/Max, Google Gemini CLI (with Advanced/Max plans), and ChatGPT Codex (with Plus/Pro plans). It tracks **active session and rate limit usage**—not API key consumption or pay-per-use billing. If you're using API keys with pay-as-you-go pricing, this tool won't help you track costs; check your provider's billing dashboard instead.
+It supports:
 
-## Features
+- Claude Code
+- Gemini CLI
+- OpenAI Codex
 
-- **Privacy-first** - Runs entirely locally with no external data transmission
-- **Auto-discovery** - Automatically detects installed LLM CLI tools
-- **HTTP API** - Query usage limits via REST endpoints
-- **Unified Web UI** - All-in-one dashboard showing Claude, Gemini, and Codex usage at a glance
-- **Instant Tab Tracking** - Pin the dashboard to your browser tab and see live usage updates via favicon and title changes
-- **Lightweight** - Single dependency (node-pty)
-- **Multi-agent** - Monitor Claude, Gemini, and Codex simultaneously
-- **Secure by design** - No browser cookies, web scraping, or credential access
+## How It Gets the Data
 
-## Usage
+This is the part that matters.
 
-### Basic Usage
+Agent Tank reads usage directly from the local CLI tools you already use. It launches the installed CLIs locally, runs their built-in usage commands, and parses the output into a unified web UI and JSON API.
 
-```bash
-# Auto-discover and monitor all available LLM agents
-agent-tank
+- Claude: runs `/usage`
+- Gemini: runs `/stats`
+- Codex: prefers JSON-RPC `account/rateLimits/read`, falls back to `/status`
 
-# Monitor specific agents only
-agent-tank --claude --gemini
+What it does not do:
 
-# Use a custom port (default: 3456)
-agent-tank --port 8080
+- It does not scrape provider websites
+- It does not read browser cookies
+- It does not depend on a logged-in browser session
+- It does not MITM or inspect your network traffic
+- It does not send your usage data to a remote service
 
-# Fetch usage once and exit (no HTTP server)
-agent-tank --once
+If you have seen other tools built around log-file heuristics or browser-session scraping, Agent Tank is deliberately not that.
 
-# Output pure JSON for scripting/piping
-agent-tank --once --json
-```
+## Who It Is For
 
-### Command Line Options
+Agent Tank is meant for subscription-based coding agent products where the CLI itself exposes session or limit information.
 
-```
-Options:
-  --claude              Enable Claude monitoring
-  --gemini              Enable Gemini monitoring
-  --codex               Enable Codex monitoring
-  --port <port>         HTTP server port (default: 3456)
-  --host <host>         Bind address (default: 127.0.0.1)
-  --auth-user <user>    HTTP Basic Auth username
-  --auth-pass <pass>    HTTP Basic Auth password
-  --auth-token <token>  API key for Bearer token auth
-  --fresh-process       Spawn a new process per refresh (default: false)
-  --claude-api          Use direct Anthropic API for Claude usage (faster, 60s refresh)
-  --config, -c          Path to config file (JSON)
-  --auto-discover       Auto-discover available agents (default: true)
-  --auto-refresh        Enable/disable background auto-refresh (default: true)
-  --auto-refresh-mode <mode>         Refresh mode: none, interval, activity (default: activity)
-  --auto-refresh-interval <seconds>  Auto-refresh interval in seconds (default: 60)
-  --activity-debounce <ms>           Activity debounce interval in milliseconds (default: 5000)
-  --keepalive           Enable/disable session keepalive (default: true)
-  --keepalive-interval <seconds>     Session keepalive interval in seconds (default: 300)
-  --history-retention-days <days>    Days to retain usage history (default: 14)
-  --once                Fetch usage once and exit (no HTTP server)
-  --json                Output pure JSON (suppress logging, use with --once)
-  --help, -h            Show this help message
-```
+Examples:
 
-### Environment Variables
+- Claude Code Pro / Max
+- Gemini CLI with supported subscription plans
+- ChatGPT Codex with supported plans
 
-Environment variables override CLI flags and config file settings:
+It is not for:
 
-| Variable | Description |
-|----------|-------------|
-| `AGENT_TANK_USER` | Basic auth username (overrides `--auth-user`) |
-| `AGENT_TANK_PASS` | Basic auth password (overrides `--auth-pass`) |
-| `AGENT_TANK_TOKEN` | API key (overrides `--auth-token`) |
-| `AGENT_TANK_HOST` | Bind address (overrides `--host`) |
-| `AGENT_TANK_FRESH_PROCESS` | Use fresh process per refresh (`1` or `true`) |
-| `AGENT_TANK_CLAUDE_API` | Use direct Anthropic API for Claude usage (`1` or `true`) |
-| `AGENT_TANK_AUTO_REFRESH` | Enable/disable background auto-refresh (`1`/`true` or `0`/`false`) |
-| `AGENT_TANK_AUTO_REFRESH_MODE` | Refresh mode: `none`, `interval`, or `activity` (default: `activity`) |
-| `AGENT_TANK_AUTO_REFRESH_INTERVAL` | Auto-refresh interval in seconds |
-| `AGENT_TANK_ACTIVITY_DEBOUNCE` | Activity debounce interval in milliseconds (default: 5000) |
-| `AGENT_TANK_KEEPALIVE` | Enable/disable session keepalive (`1`/`true` or `0`/`false`) |
-| `AGENT_TANK_KEEPALIVE_INTERVAL` | Session keepalive interval in seconds (default: 300) |
-| `AGENT_TANK_HISTORY_RETENTION_DAYS` | Days to retain usage history (default: 14) |
+- pay-as-you-go API key billing
+- cost tracking for API requests
+- provider billing dashboards
 
-### Configuration File
+If you need API spend tracking, use the provider’s billing tools instead.
 
-You can use a JSON configuration file:
+## Quick Start
 
-```json
-{
-  "claude": true,
-  "gemini": true,
-  "codex": false,
-  "port": 8080,
-  "history": {
-    "retentionDays": 7
-  }
-}
-```
+### Install
 
 ```bash
-agent-tank -c config.json
+npm install -g agent-tank
 ```
 
-## Claude API Mode
-
-By default, Claude usage data is fetched by spawning a PTY session and running the `/usage` command. With `--claude-api`, Agent Tank fetches usage directly from the Anthropic OAuth API instead, which is faster and allows a 60-second refresh interval (vs 10 minutes for PTY).
+Or run it directly:
 
 ```bash
-agent-tank --claude --claude-api
+npx agent-tank
 ```
 
-### How It Works
+### First Run
 
-- Uses the OAuth token from `~/.claude/.credentials.json` (the same credentials Claude Code uses)
-- Calls the `api.anthropic.com/api/oauth/usage` endpoint with the `anthropic-beta: oauth-2025-04-20` header
-- Automatically refreshes expired tokens using the OAuth refresh token flow
-- Falls back to PTY mode if the API call fails
+```bash
+# Auto-discover installed agents and start the web UI + API
+agent-tank
+```
 
-### Configuration
+By default it starts on:
 
-```json
-{
-  "claude": true,
-  "claudeApi": true
-}
+```text
+http://127.0.0.1:3456
 ```
 
-Or via environment variable:
+If Docker is available, Agent Tank asks Docker for the active bridge gateway addresses and binds them by default so containers on the same host can reach it without exposing it on the public interface. If Docker is unavailable, it falls back to local bridge interface detection.
+
+Use this if you want localhost only:
 
 ```bash
-AGENT_TANK_CLAUDE_API=1 agent-tank --claude
+agent-tank --no-docker
 ```
 
-## Activity-Based Polling
+### Most Common Commands
 
-Agent Tank supports intelligent activity-based polling that monitors local log directories for LLM CLI activity. Instead of polling on a fixed interval (which can waste resources during idle periods), activity mode only triggers usage refreshes when you're actively using the CLI tools.
+```bash
+# Monitor only specific agents
+agent-tank --claude --gemini
 
-### How It Works
+# Use a custom port
+agent-tank --port 8080
 
-1. **Log Directory Monitoring**: Agent Tank watches the following directories for file changes:
-   - Claude: `~/.config/claude/projects/`, `~/.claude/`
-   - Codex: `~/.codex/sessions/`, `~/.codex/`
-   - Gemini: `~/.config/gemini/`, `~/.gemini/`
+# Fetch once and print JSON
+agent-tank --once --json
 
-2. **Debounced Detection**: When activity is detected, a configurable debounce timer starts. This prevents excessive refreshes during bursts of activity.
+# Show the installed Agent Tank version
+agent-tank --version
 
-3. **On-Demand Refresh Cycles**: After the debounce period, a refresh cycle begins and continues at the configured interval while activity is ongoing.
+# Require at least 60 seconds between refreshes for the same agent
+agent-tank --refresh-cooldown 60
+```
 
-4. **Idle State**: When no more activity is detected, polling stops to conserve resources.
+## What You Get
 
-### Auto-Refresh Modes
+### Web UI
 
-Agent Tank supports three refresh modes:
+- Single-page dashboard for all supported agents
+- Live refresh
+- Reset countdowns
+- Pace indicators
+- Browser-tab tracking via title and favicon updates
 
-| Mode | Description |
-|------|-------------|
-| `activity` | (Default) Monitors log directories and refreshes when CLI activity is detected |
-| `interval` | Traditional interval-based polling at fixed intervals |
-| `none` | No automatic refresh; manual refresh only via `POST /refresh` |
+### HTTP API
 
-### Configuration
+- `GET /status`
+- `GET /status/:agent`
+- `POST /refresh`
+- `POST /refresh/:agent`
+- `GET /config`
+- `GET /history`
+- `GET /history/:agent`
 
-```bash
-# Use activity-based polling (default)
-agent-tank
+### Supported Metrics
 
-# Use activity mode with custom debounce (wait 10 seconds after activity)
-agent-tank --activity-debounce 10000
+| Agent | Method | Metrics |
+|---|---|---|
+| Claude | PTY `/usage` or Anthropic OAuth API | Current session, weekly all-models, weekly Sonnet-only |
+| Gemini | PTY `/stats` | Per-model usage and reset windows |
+| Codex | JSON-RPC preferred, PTY fallback | 5-hour limits, weekly limits, model/account info |
 
-# Use traditional interval-based polling
-agent-tank --auto-refresh-mode interval
+## Basic Usage
 
-# Disable all auto-refresh (manual only)
-agent-tank --auto-refresh-mode none
+### Auto-Discover Everything
 
-# Via environment variables
-AGENT_TANK_AUTO_REFRESH_MODE=activity agent-tank
-AGENT_TANK_ACTIVITY_DEBOUNCE=10000 agent-tank
+```bash
+agent-tank
 ```
 
-### Notes
-
-- Activity mode automatically falls back to interval mode if no log directories are found
-- The debounce interval is specified in milliseconds (default: 5000ms = 5 seconds)
-- During active usage, refreshes occur at the `--auto-refresh-interval` rate (default: 60 seconds)
-- Activity mode is disabled in one-shot mode (`--once`)
-
-## Session Keepalive
+### Monitor Specific Agents
 
-Agent Tank includes an automatic session keepalive feature that prevents LLM CLI sessions from expiring due to inactivity. This is especially useful for Claude and Codex, which have session timeouts that require periodic activity.
+```bash
+agent-tank --claude --codex
+```
 
-### How It Works
+### One-Shot Scripting Mode
 
-The keepalive manager runs in the background and periodically sends lightweight "ping" commands to each agent's PTY session. This maintains the connection without triggering API calls or affecting rate limits.
+```bash
+agent-tank --once --json
+```
 
-### Configuration
+### Bind to a Different Host or Port
 
 ```bash
-# Use default keepalive (every 5 minutes)
-agent-tank
-
-# Custom keepalive interval (every 10 minutes)
-agent-tank --keepalive-interval 600
+agent-tank --host 0.0.0.0 --port 8080
+```
 
-# Disable keepalive
-agent-tank --no-keepalive
+### Disable Docker Bridge Binding
 
-# Via environment variable
-AGENT_TANK_KEEPALIVE_INTERVAL=600 agent-tank
+```bash
+agent-tank --no-docker
 ```
 
-### Notes
+### Disable Background Refresh
 
-- Keepalive is automatically disabled in fresh process mode (`--fresh-process`) since there are no persistent sessions to maintain
-- Keepalive is also disabled in one-shot mode (`--once`)
-- The feature only affects PTY-based sessions; JSON-RPC mode (used by Codex when available) doesn't require keepalive
+```bash
+agent-tank --auto-refresh-mode none
+```
 
-## Usage History & Pace Evaluation
+### Slow Down Agent Refreshes
 
-Agent Tank automatically tracks usage history and evaluates whether you're burning through your rate limits faster than expected.
+By default, Agent Tank will not refresh the same agent more than once every 30 seconds, even if the refresh is triggered manually or by detected CLI activity. This reduces unnecessary polling and helps avoid CLI-side rate limiting.
 
-### Features
+```bash
+agent-tank --refresh-cooldown 60
+```
 
-- **Historical Snapshots**: Usage percentages are stored in `~/.agent-tank/history.json` with timestamps
-- **Automatic Pruning**: Records older than the retention period (default: 14 days) are automatically removed
-- **Pace Evaluation**: Each metric includes a `paceEval` object that calculates:
-  - `expectedPercent`: What your usage should be based on linear pace
-  - `isBurningFast`: Whether you're using faster than the 1.2x threshold
-  - `etaSeconds`: Estimated seconds until you hit 100% (if burning fast)
-  - `deltaPercent`: Difference between actual and expected usage
+Set it to `0` to disable the cooldown entirely.
 
-### Configuration
+## Command Line Options
 
-```bash
-# Keep 7 days of history instead of default 14
-agent-tank --history-retention-days 7
-
-# Via environment variable
-AGENT_TANK_HISTORY_RETENTION_DAYS=7 agent-tank
+```text
+Options:
+  --claude              Enable Claude monitoring
+  --gemini              Enable Gemini monitoring
+  --codex               Enable Codex monitoring
+  --port <port>         HTTP server port (default: 3456)
+  --host <host>         Bind address (default: 127.0.0.1 + Docker bridge when available)
+  --docker              Enable Docker bridge bind when --host is omitted (default: true)
+  --auth-user <user>    HTTP Basic Auth username
+  --auth-pass <pass>    HTTP Basic Auth password
+  --auth-token <token>  API key for Bearer token auth
+  --fresh-process       Spawn a new process per refresh (default: false)
+  --claude-api          Use direct Anthropic API for Claude usage (faster, 60s refresh)
+  --config, -c          Path to config file (JSON)
+  --version, -v         Show version
+  --auto-discover       Auto-discover available agents (default: true)
+  --auto-refresh        Enable/disable background auto-refresh (default: true)
+  --auto-refresh-mode <mode>         Refresh mode: none, interval, activity (default: activity)
+  --auto-refresh-interval <seconds>  Auto-refresh interval in seconds (default: 60)
+  --refresh-cooldown <seconds>       Minimum time between refreshes per agent (default: 30, 0 = disabled)
+  --activity-debounce <ms>           Activity debounce interval in milliseconds (default: 5000)
+  --keepalive           Enable/disable session keepalive (default: true)
+  --keepalive-interval <seconds>     Session keepalive interval in seconds (default: 300)
+  --history-retention-days <days>    Days to retain usage history (default: 14)
+  --once                Fetch usage once and exit (no HTTP server)
+  --json                Output pure JSON (suppress logging, use with --once)
+  --help, -h            Show this help message
 ```
 
-### API Endpoints
+## Configuration
 
-- `GET /history` - Get history statistics (total records, per-agent counts, date ranges)
-- `GET /history/:agent` - Get full history for a specific agent
+### Environment Variables
+
+Environment variables override CLI flags and config file values.
 
-### Example Pace Evaluation Data
+| Variable | Description |
+|---|---|
+| `AGENT_TANK_USER` | Basic auth username |
+| `AGENT_TANK_PASS` | Basic auth password |
+| `AGENT_TANK_TOKEN` | Bearer token auth |
+| `AGENT_TANK_HOST` | Bind address |
+| `AGENT_TANK_DOCKER` | Enable/disable Docker bridge bind when `--host` is omitted |
+| `AGENT_TANK_FRESH_PROCESS` | Use fresh process per refresh (`1`/`true`) |
+| `AGENT_TANK_CLAUDE_API` | Use Claude API mode (`1`/`true`) |
+| `AGENT_TANK_AUTO_REFRESH` | Enable/disable auto-refresh |
+| `AGENT_TANK_AUTO_REFRESH_MODE` | `none`, `interval`, or `activity` |
+| `AGENT_TANK_AUTO_REFRESH_INTERVAL` | Auto-refresh interval in seconds |
+| `AGENT_TANK_REFRESH_COOLDOWN` | Minimum time between refreshes per agent in seconds |
+| `AGENT_TANK_ACTIVITY_DEBOUNCE` | Activity debounce interval in milliseconds |
+| `AGENT_TANK_KEEPALIVE` | Enable/disable keepalive |
+| `AGENT_TANK_KEEPALIVE_INTERVAL` | Keepalive interval in seconds |
+| `AGENT_TANK_HISTORY_RETENTION_DAYS` | History retention window |
 
-When an agent is burning faster than expected, the `paceEval` object is attached to each metric:
+### Config File
 
 ```json
 {
-  "session": {
-    "percent": 60,
-    "resetsInSeconds": 9000,
-    "paceEval": {
-      "expectedPercent": 50,
-      "isBurningFast": true,
-      "etaSeconds": 6000,
-      "paceRatio": 1.2,
-      "elapsedPercent": 50,
-      "deltaPercent": 10
-    }
+  "claude": true,
+  "gemini": true,
+  "codex": false,
+  "port": 8080,
+  "dockerAccess": true,
+  "claudeApi": false,
+  "refreshCooldown": 30,
+  "autoRefresh": {
+    "mode": "activity",
+    "interval": 60,
+    "activityDebounce": 5000,
+    "refreshCooldown": 30
+  },
+  "keepalive": {
+    "enabled": true,
+    "interval": 300
+  },
+  "history": {
+    "retentionDays": 14
   }
 }
 ```
 
-This example shows: 50% of the 5-hour session has elapsed, but 60% of usage is consumed. At this pace (1.2x), you'll hit 100% in approximately 6000 seconds (1h 40m).
-
-## Installation
-
-```bash
-npm install -g agent-tank
-```
-
-Or run directly with npx:
+Run with:
 
 ```bash
-npx agent-tank
+agent-tank -c config.json
 ```
 
 ## HTTP API
@@ -289,19 +271,17 @@ npx agent-tank
 ### Endpoints
 
 | Method | Endpoint | Description |
-|--------|----------|-------------|
+|---|---|---|
 | GET | `/` | HTML status page |
 | GET | `/status` | JSON status for all agents |
-| GET | `/status/:agent` | JSON status for specific agent |
-| GET | `/config` | Auto-refresh and history configuration (JSON) |
-| GET | `/history` | Usage history statistics (JSON) |
-| GET | `/history/:agent` | Usage history for specific agent (JSON) |
+| GET | `/status/:agent` | JSON status for one agent |
+| GET | `/config` | Auto-refresh and history config |
+| GET | `/history` | History summary |
+| GET | `/history/:agent` | History for one agent |
 | POST | `/refresh` | Refresh all agents |
-| POST | `/refresh/:agent` | Refresh specific agent |
+| POST | `/refresh/:agent` | Refresh one agent |
 
-### Example Responses
-
-#### GET /status
+### Example `GET /status`
 
 ```json
 {
@@ -321,19 +301,9 @@ npx agent-tank
         "resetsAt": "Mar 13, 3am (Europe/London)",
         "resetsIn": "4d 5h",
         "resetsInSeconds": 364364
-      },
-      "weeklySonnet": {
-        "label": "Current week (Sonnet only)",
-        "percent": 5,
-        "resetsAt": "Mar 13, 10am (Europe/London)",
-        "resetsIn": "4d 12h",
-        "resetsInSeconds": 389564
       }
     },
     "metadata": {
-      "sessionId": "0b34aa59-...",
-      "cwd": "/tmp",
-      "organization": "Your Organization",
       "email": "user@example.com",
       "version": "2.1.71"
     },
@@ -341,94 +311,25 @@ npx agent-tank
     "error": null,
     "isRefreshing": false
   },
-  "gemini": {
-    "name": "gemini",
-    "usage": {
-      "models": [
-        {
-          "model": "gemini-2.5-flash",
-          "usageLeft": 100,
-          "resetsIn": "24h",
-          "percentUsed": 0,
-          "resetsInSeconds": 86400
-        },
-        {
-          "model": "gemini-2.5-pro",
-          "usageLeft": 99.5,
-          "resetsIn": "12h 16m",
-          "percentUsed": 0.5,
-          "resetsInSeconds": 44160
-        }
-      ]
-    },
-    "metadata": {
-      "version": "0.24.5",
-      "email": "user@example.com",
-      "authMethod": "OAuth",
-      "model": "auto-gemini-2.5",
-      "os": "linux",
-      "updateAvailable": {
-        "current": "0.24.5",
-        "latest": "0.32.1"
-      }
-    },
-    "lastUpdated": "2026-03-08T21:47:14.138Z",
-    "error": null,
-    "isRefreshing": false
-  },
   "codex": {
     "name": "codex",
     "usage": {
       "fiveHour": {
-        "percentLeft": 100,
-        "resetsAt": "02:44 on 9 Mar",
-        "label": "5h limit",
         "percentUsed": 0,
+        "resetsAt": "02:44 on 9 Mar",
         "resetsIn": "4h 56m",
         "resetsInSeconds": 17807
       },
       "weekly": {
-        "percentLeft": 100,
-        "resetsAt": "21:44 on 15 Mar",
-        "label": "Weekly limit",
         "percentUsed": 0,
+        "resetsAt": "21:44 on 15 Mar",
         "resetsIn": "6d 23h",
         "resetsInSeconds": 604607
-      },
-      "version": {
-        "current": "0.107.0",
-        "latest": "0.111.0"
-      },
-      "modelLimits": [
-        {
-          "name": "GPT-5.3-Codex-Spark",
-          "fiveHour": {
-            "percentLeft": 100,
-            "resetsAt": "02:46 on 9 Mar",
-            "label": "5h limit",
-            "percentUsed": 0,
-            "resetsIn": "4h 58m",
-            "resetsInSeconds": 17927
-          },
-          "weekly": {
-            "percentLeft": 100,
-            "resetsAt": "21:46 on 15 Mar",
-            "label": "Weekly limit",
-            "percentUsed": 0,
-            "resetsIn": "6d 23h",
-            "resetsInSeconds": 604727
-          }
-        }
-      ],
-      "model": "gpt-5.3-codex",
-      "account": "user@example.com"
+      }
     },
     "metadata": {
-      "directory": "/tmp",
-      "sessionId": "019ccf68-...",
-      "collaborationMode": "Default",
-      "model": "gpt-5.3-codex",
-      "email": "user@example.com"
+      "email": "user@example.com",
+      "model": "gpt-5.3-codex"
     },
     "lastUpdated": "2026-03-08T21:47:12.648Z",
     "error": null,
@@ -437,220 +338,206 @@ npx agent-tank
 }
 ```
 
-#### GET /status/claude
+## Claude API Mode
 
-```json
-{
-  "name": "claude",
-  "usage": {
-    "session": {
-      "label": "Current session",
-      "percent": 42,
-      "resetsAt": "10pm (Europe/London)",
-      "resetsIn": "12m",
-      "resetsInSeconds": 764
-    },
-    "weeklyAll": {
-      "label": "Current week (all models)",
-      "percent": 31,
-      "resetsAt": "Mar 13, 3am (Europe/London)",
-      "resetsIn": "4d 5h",
-      "resetsInSeconds": 364364
-    },
-    "weeklySonnet": {
-      "label": "Current week (Sonnet only)",
-      "percent": 5,
-      "resetsAt": "Mar 13, 10am (Europe/London)",
-      "resetsIn": "4d 12h",
-      "resetsInSeconds": 389564
-    }
-  },
-  "metadata": {
-    "sessionId": "0b34aa59-...",
-    "cwd": "/tmp",
-    "organization": "Your Organization",
-    "email": "user@example.com",
-    "version": "2.1.71"
-  },
-  "lastUpdated": "2026-03-08T21:47:15.090Z",
-  "error": null,
-  "isRefreshing": false
-}
-```
+By default, Claude usage is collected via PTY by running `/usage`.
 
-## Developer & Advanced Setup
+With `--claude-api`, Agent Tank uses the Anthropic OAuth usage API instead. This is usually faster and supports a shorter refresh interval.
 
-### Prerequisites
+```bash
+agent-tank --claude --claude-api
+```
 
-#### Build Requirements
+How it works:
 
-The `node-pty` dependency requires native compilation. You'll need:
+- reads the same Claude OAuth credentials the CLI already uses
+- calls `https://api.anthropic.com/api/oauth/usage`
+- refreshes expired OAuth tokens when needed
+- falls back to PTY mode if the API path fails
 
-- **Python 3.8+** (Python 3.11 recommended)
-- **C++ build tools** (gcc, g++, make)
-- **Node.js development headers**
+You can also enable it with:
 
-##### Linux (Ubuntu/Debian)
 ```bash
-sudo apt-get install python3.11 python3.11-dev build-essential nodejs-dev
+AGENT_TANK_CLAUDE_API=1 agent-tank --claude
 ```
 
-##### Linux (Fedora/RHEL/CentOS)
-```bash
-sudo dnf install python3.11 python3.11-devel gcc gcc-c++ make nodejs-devel
-```
+## Auto-Refresh Modes
 
-##### Linux (openSUSE)
-```bash
-sudo zypper install python311 python311-devel gcc gcc-c++ make nodejs20-devel
-```
+Agent Tank supports three refresh strategies:
+
+| Mode | Description |
+|---|---|
+| `activity` | Default. Watches known local agent directories and refreshes when activity is detected |
+| `interval` | Refreshes on a fixed timer |
+| `none` | No background refresh. Use manual refresh only |
+
+Examples:
 
-##### macOS
 ```bash
-# Install Xcode Command Line Tools if not already installed
-xcode-select --install
+# Default mode
+agent-tank
 
-# Install Python 3.11
-brew install python@3.11
+# Interval polling
+agent-tank --auto-refresh-mode interval
+
+# Manual-only mode
+agent-tank --auto-refresh-mode none
+
+# Longer activity debounce
+agent-tank --activity-debounce 10000
 ```
 
-##### Windows
-- Install [Python 3.11+](https://www.python.org/downloads/)
-- Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022)
+### Activity-Based Polling
 
-#### LLM CLI Tools
+In activity mode, Agent Tank watches common local directories:
 
-You need at least one of these CLI tools installed and authenticated:
+- Claude: `~/.config/claude/projects/`, `~/.claude/`
+- Codex: `~/.codex/sessions/`, `~/.codex/`
+- Gemini: `~/.config/gemini/`, `~/.gemini/`
 
-- [Claude Code](https://claude.ai/download) (`claude`) - **Version 2.0+ required** for `/usage` command support
-- [Gemini CLI](https://github.com/anthropics/gemini-cli) (`gemini`) - **Version 0.24.5+ required** for `/stats` command support
-- [OpenAI Codex](https://platform.openai.com/docs/codex) (`codex`)
+If no suitable directories are found, it falls back to interval mode.
+
+## Session Keepalive
 
-**Version Requirements:**
+Keepalive helps persistent PTY-backed sessions stay warm.
 
-**Claude Code:** Version 1.x does not support the `/usage` command.
 ```bash
-# Check version
-claude --version
+# Default keepalive
+agent-tank
+
+# Every 10 minutes
+agent-tank --keepalive-interval 600
 
-# Update to latest
-npm update -g @anthropic-ai/claude-code
+# Disable keepalive
+agent-tank --no-keepalive
 ```
 
-**Gemini CLI:** Version 0.24.4 and below do not support the `/stats` command properly.
-```bash
-# Check version
-gemini --version
+Notes:
+
+- disabled automatically in `--fresh-process`
+- disabled automatically in `--once`
+- not needed for Codex JSON-RPC mode
+
+## Usage History and Pace
+
+Agent Tank stores usage snapshots and calculates whether a metric is being consumed faster than the time window would suggest.
+
+You can configure retention:
 
-# Update to latest
-npm update -g gemini
+```bash
+agent-tank --history-retention-days 7
 ```
 
-### Programmatic Usage
+History endpoints:
 
-```javascript
-const { AgentTank } = require('agent-tank');
+- `GET /history`
+- `GET /history/:agent`
 
-const watcher = new AgentTank({
-  agents: ['claude', 'gemini'], // or null for auto-discover
-  port: 3456,
-  autoDiscover: true
-});
+## Installation Notes
 
-await watcher.start();
+### Build Requirements
 
-// Get status programmatically
-const status = watcher.getStatus();
-console.log(status.claude.usage);
+`node-pty` requires native compilation support.
 
-// Refresh a specific agent
-await watcher.refreshAgent('claude');
+You need:
 
-// Stop the server
-watcher.stop();
+- Python 3.8+
+- C/C++ build tools
+- Node.js development headers
+
+#### Ubuntu / Debian
+
+```bash
+sudo apt-get install python3.11 python3.11-dev build-essential nodejs-dev
 ```
 
-### How It Works: Privacy-First Local Execution
+#### Fedora / RHEL / CentOS
 
-Agent Tank is designed with privacy and security as core principles. Understanding how it collects usage data is essential for users evaluating the tool's security posture.
+```bash
+sudo dnf install python3.11 python3.11-devel gcc gcc-c++ make nodejs-devel
+```
 
-#### Local Execution Architecture
+#### openSUSE
 
-The tool operates entirely on your local machine using two different approaches depending on the CLI tool's capabilities:
+```bash
+sudo zypper install python311 python311-devel gcc gcc-c++ make nodejs20-devel
+```
 
-**JSON-RPC Mode (Codex)**
+#### macOS
 
-For the Codex CLI, Agent Tank uses a structured JSON-RPC protocol when available:
+```bash
+xcode-select --install
+brew install python@3.11
+```
 
-1. **Starts the app-server** - Launches `codex -s read-only -a untrusted app-server`
-2. **Sends JSON-RPC requests** - Calls `account/rateLimits/read` via stdin
-3. **Receives structured data** - Parses JSON responses with precise rate limit information
-4. **Falls back to PTY** - Automatically uses PTY mode if JSON-RPC is unavailable (older CLI versions)
+#### Windows
 
-This approach provides more reliable data parsing and is the preferred method for Codex.
+- Install [Python 3.11+](https://www.python.org/downloads/)
+- Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022)
 
-**PTY-Based Mode (Claude, Gemini, Codex fallback)**
+## CLI Requirements
 
-For other CLI tools (and as a fallback for Codex), Agent Tank spawns instances within a pseudo-terminal (PTY). This approach is functionally equivalent to you opening a terminal window and typing commands yourself:
+You need at least one supported CLI installed and authenticated.
 
-1. **Spawns a local PTY** - Creates a pseudo-terminal session on your machine
-2. **Launches the CLI tool** - Starts the authenticated CLI (e.g., `claude`, `gemini`, or `codex`)
-3. **Sends usage commands** - Types the appropriate command (`/usage`, `/stats`, or `/status`)
-4. **Parses the output** - Reads and structures the text response from the terminal
-5. **Exposes via local HTTP** - Makes the parsed data available through a localhost API
+- [Claude Code](https://claude.ai/download) as `claude`
+  - Version 2.0+ required for `/usage`
+- Gemini CLI as `gemini`
+  - Version 0.24.5+ required for `/stats`
+- OpenAI Codex as `codex`
 
-#### What Agent Tank Does NOT Do
+Useful checks:
 
-To be explicit about what this tool avoids:
+```bash
+claude --version
+gemini --version
+codex --version
+```
 
-- **No browser cookie access** - Agent Tank never reads, parses, or transmits browser cookies
-- **No web scraping** - The tool does not access web interfaces or scrape HTML pages
-- **No credential extraction** - Your API keys, tokens, or passwords are never accessed or stored
-- **No network interception** - There is no proxy, MITM, or traffic inspection involved
-- **No external data transmission** - Usage data stays on your machine; nothing is sent to external servers
+## Programmatic Usage
 
-#### Why This Approach?
+```javascript
+const { AgentTank } = require('agent-tank');
 
-LLM usage data is sensitive—it can reveal work patterns, subscription tiers, and usage intensity. By operating through local CLI tools that you've already authenticated, Agent Tank inherits the security model you've already established with each provider. The tool acts as a local automation layer, not a data collection service.
+const watcher = new AgentTank({
+  agents: ['claude', 'gemini'],
+  port: 3456,
+  autoDiscover: true
+});
 
-#### Supported Commands
+await watcher.start();
 
-| Agent | Method | Command/RPC | Output |
-|-------|--------|-------------|--------|
-| Claude | PTY | `/usage` | Session %, Weekly % |
-| Gemini | PTY | `/stats` | Model-specific usage % |
-| Codex | JSON-RPC | `account/rateLimits/read` | 5h limit %, Weekly % |
-| Codex | PTY (fallback) | `/status` | 5h limit %, Weekly % |
+const status = watcher.getStatus();
+console.log(status);
 
-## Troubleshooting
+await watcher.refreshAgent('claude');
 
-### Installation fails with "gyp ERR!"
+watcher.stop();
+```
 
-This indicates missing build dependencies. Make sure you have:
+## Troubleshooting
 
-1. **Python 3.8+**: Check with `python3 --version`. If you have multiple Python versions, set the PYTHON environment variable:
-   ```bash
-   PYTHON=/usr/bin/python3.11 npm install
-   ```
+### `gyp ERR!` during install
 
-2. **Build tools**: Install gcc, g++, and make for your platform (see Prerequisites above)
+This usually means your system is missing Python, compiler tools, or Node headers.
 
-3. **Node.js headers**: Install the nodejs-devel or nodejs-dev package for your distribution
+Try:
 
-If you still have issues, try rebuilding:
 ```bash
+PYTHON=/usr/bin/python3.11 npm install
 npm run rebuild
 ```
 
-### Agent shows "Timeout waiting for usage data"
+### `Timeout waiting for usage data`
 
-- Ensure the CLI tool is properly authenticated
-- Try running the CLI tool manually to verify it works
-- Check if there are any prompts requiring user input
+- make sure the CLI works on its own
+- make sure the CLI is authenticated
+- check for trust prompts, auth prompts, or update prompts
+- try `--fresh-process`
+- try disabling keepalive or background refresh while debugging
 
-### Codex fails with cursor position error
+### No agents found
 
-This is handled automatically. If you still see issues, ensure your terminal supports standard escape sequences.
+Make sure at least one supported CLI is installed and on your `PATH`.
 
 ### Port already in use
 
@@ -672,4 +559,4 @@ MIT
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Pull requests are welcome.