agent-tank 0.9.3 → 0.9.4

package/README.md

@@ -2,286 +2,251 @@
 
 ![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
-```
-
-### How It Works
-
-- 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
-
-### Configuration
-
-```json
-{
-  "claude": true,
-  "claudeApi": true
-}
+npx agent-tank
 ```
 
-Or via environment variable:
+### First Run
 
 ```bash
-AGENT_TANK_CLAUDE_API=1 agent-tank --claude
+# Auto-discover installed agents and start the web UI + API
+agent-tank
 ```
 
-## Activity-Based Polling
-
-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.
-
-### How It Works
-
-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/`
+By default it starts on:
 
-2. **Debounced Detection**: When activity is detected, a configurable debounce timer starts. This prevents excessive refreshes during bursts of activity.
-
-3. **On-Demand Refresh Cycles**: After the debounce period, a refresh cycle begins and continues at the configured interval while activity is ongoing.
-
-4. **Idle State**: When no more activity is detected, polling stops to conserve resources.
+```text
+http://127.0.0.1:3456
+```
 
-### Auto-Refresh Modes
+If Docker is running with a detectable local bridge interface, Agent Tank also binds that bridge address by default so containers on the same host can reach it without exposing it on the public interface.
 
-Agent Tank supports three refresh modes:
+Use this if you want localhost only:
 
-| 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` |
+```bash
+agent-tank --no-docker
+```
 
-### Configuration
+### Most Common Commands
 
 ```bash
-# Use activity-based polling (default)
-agent-tank
-
-# Use activity mode with custom debounce (wait 10 seconds after activity)
-agent-tank --activity-debounce 10000
+# Monitor only specific agents
+agent-tank --claude --gemini
 
-# Use traditional interval-based polling
-agent-tank --auto-refresh-mode interval
+# Use a custom port
+agent-tank --port 8080
 
-# Disable all auto-refresh (manual only)
-agent-tank --auto-refresh-mode none
+# Fetch once and print JSON
+agent-tank --once --json
 
-# Via environment variables
-AGENT_TANK_AUTO_REFRESH_MODE=activity agent-tank
-AGENT_TANK_ACTIVITY_DEBOUNCE=10000 agent-tank
+# Show the installed Agent Tank version
+agent-tank --version
 ```
 
-### Notes
+## What You Get
 
-- 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`)
+### Web UI
 
-## Session Keepalive
+- Single-page dashboard for all supported agents
+- Live refresh
+- Reset countdowns
+- Pace indicators
+- Browser-tab tracking via title and favicon updates
+
+### HTTP API
 
-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.
+- `GET /status`
+- `GET /status/:agent`
+- `POST /refresh`
+- `POST /refresh/:agent`
+- `GET /config`
+- `GET /history`
+- `GET /history/:agent`
 
-### How It Works
+### Supported Metrics
 
-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.
+| 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 |
 
-### Configuration
+## Basic Usage
+
+### Auto-Discover Everything
 
 ```bash
-# Use default keepalive (every 5 minutes)
 agent-tank
+```
 
-# Custom keepalive interval (every 10 minutes)
-agent-tank --keepalive-interval 600
-
-# Disable keepalive
-agent-tank --no-keepalive
+### Monitor Specific Agents
 
-# Via environment variable
-AGENT_TANK_KEEPALIVE_INTERVAL=600 agent-tank
+```bash
+agent-tank --claude --codex
 ```
 
-### Notes
+### One-Shot Scripting Mode
 
-- 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 --once --json
+```
 
-## Usage History & Pace Evaluation
+### Bind to a Different Host or Port
 
-Agent Tank automatically tracks usage history and evaluates whether you're burning through your rate limits faster than expected.
+```bash
+agent-tank --host 0.0.0.0 --port 8080
+```
 
-### Features
+### Disable Docker Bridge Binding
 
-- **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
+```bash
+agent-tank --no-docker
+```
 
-### Configuration
+### Disable Background Refresh
 
 ```bash
-# Keep 7 days of history instead of default 14
-agent-tank --history-retention-days 7
+agent-tank --auto-refresh-mode none
+```
 
-# Via environment variable
-AGENT_TANK_HISTORY_RETENTION_DAYS=7 agent-tank
+## Command Line Options
+
+```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)
+  --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
 
-### Example Pace Evaluation Data
+Environment variables override CLI flags and config file values.
 
-When an agent is burning faster than expected, the `paceEval` object is attached to each metric:
+| 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_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 |
+
+### 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,
+  "autoRefresh": {
+    "mode": "activity",
+    "interval": 60,
+    "activityDebounce": 5000
+  },
+  "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 +254,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 |
-
-### Example Responses
+| POST | `/refresh/:agent` | Refresh one agent |
 
-#### GET /status
+### Example `GET /status`
 
 ```json
 {
@@ -321,19 +284,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 +294,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 +321,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
+
+In activity mode, Agent Tank watches common local directories:
 
-#### LLM CLI Tools
+- Claude: `~/.config/claude/projects/`, `~/.claude/`
+- Codex: `~/.codex/sessions/`, `~/.codex/`
+- Gemini: `~/.config/gemini/`, `~/.gemini/`
 
-You need at least one of these CLI tools installed and authenticated:
+If no suitable directories are found, it falls back to interval mode.
 
-- [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`)
+## 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.
 
-# Update to latest
-npm update -g gemini
+You can configure retention:
+
+```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 +542,4 @@ MIT
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Pull requests are welcome.

package/bin/agent-tank.js

@@ -13,6 +13,7 @@ const options = {
   'claude-api': { type: 'boolean', default: false },
   port: { type: 'string', default: '3456' },
   host: { type: 'string' },
+  docker: { type: 'boolean', default: true },
   'auth-user': { type: 'string' },
   'auth-pass': { type: 'string' },
   'auth-token': { type: 'string' },
@@ -53,7 +54,8 @@ Options:
   --codex               Enable Codex monitoring
   --claude-api          Use direct Anthropic API for Claude usage (faster, 60s refresh)
   --port <port>         HTTP server port (default: 3456)
-  --host <host>         Bind address (default: 127.0.0.1)
+  --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
@@ -83,6 +85,7 @@ Environment variables:
   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_DOCKER     Enable/disable Docker bridge bind ("1"/"true" or "0"/"false")
   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" or "true" / "0" or "false")
@@ -98,6 +101,7 @@ Examples:
   agent-tank --claude --gemini        # Monitor specific agents
   agent-tank --port 8080              # Use custom port
   agent-tank --host 0.0.0.0           # Expose on all interfaces
+  agent-tank --no-docker              # Bind localhost only when host is omitted
   agent-tank --auth-user admin --auth-pass secret  # Enable basic auth
   agent-tank --auth-token mykey       # Enable API key auth
   agent-tank -c ./config.json         # Use config file
@@ -161,6 +165,13 @@ async function main() {
   };
 
   const host = process.env.AGENT_TANK_HOST || values.host || config.host;
+  const dockerEnv = process.env.AGENT_TANK_DOCKER;
+  let dockerAccess = values.docker;
+  if (dockerEnv !== undefined) {
+    dockerAccess = dockerEnv === '1' || dockerEnv === 'true';
+  } else if (config.dockerAccess !== undefined) {
+    dockerAccess = config.dockerAccess;
+  }
 
   const freshProcessEnv = process.env.AGENT_TANK_FRESH_PROCESS;
   const freshProcess = values['fresh-process'] ||
@@ -251,6 +262,7 @@ async function main() {
     autoDiscover: values['auto-discover'] && agents.length === 0,
     port: parseInt(values.port || config.port || '3456', 10),
     host,
+    dockerAccess,
     auth,
     freshProcess,
     claudeApi,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-tank",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Monitor and query usage limits for LLM CLI tools (Claude, Gemini, Codex) via HTTP API",
   "main": "src/index.js",
   "bin": {

package/src/agents/claude.js

@@ -204,43 +204,25 @@ class ClaudeAgent extends BaseAgent {
     const clean = this.stripAnsi(output);
     // Detect error responses (rate limiting, session errors) — treat as complete
     if (/rate.?limited|rate_limit_error|Failed to load usage|session.?expired|session.?error|invalid.?session|authentication.?error|auth.?failed|Unable to (?:load|fetch)|Error loading|could not (?:load|fetch)|not authenticated|login required|sign.?in required/i.test(clean)) return true;
-    // Basic requirements - must have actual usage data, not just the loading screen
-    const hasSession = clean.includes('Current session');
-    const hasWeekly = clean.includes('Current week');
-    const hasPercentUsed = clean.includes('% used');
-    if (!hasSession || !hasWeekly || !hasPercentUsed) return false;
-
-    // If "all models" section exists, wait for "Sonnet only" section to render
-    const hasAllModels = /Current\s+week\s*\(?\s*all\s+models/i.test(clean);
-    if (hasAllModels) {
-      const hasSonnetOnly = /Current\s+week\s*\(?\s*Sonnet\s+only/i.test(clean);
-      if (!hasSonnetOnly) {
-        return false;
-      }
-      // Both sections exist, check we have at least one timezone per section
-      const allModelsIdx = clean.search(/Current\s+week\s*\(?\s*all\s+models/i);
-      const sonnetOnlyIdx = clean.search(/Current\s+week\s*\(?\s*Sonnet\s+only/i);
-      const allModelsSection = clean.substring(allModelsIdx, sonnetOnlyIdx);
-      const sonnetSection = clean.substring(sonnetOnlyIdx);
-
-      const allModelsHasTimezone = /\([A-Za-z]+\/[A-Za-z_]+\)/.test(allModelsSection);
-      const sonnetHasTimezone = /\([A-Za-z]+\/[A-Za-z_]+\)/.test(sonnetSection);
+    const parsed = parsePtyOutput(clean);
 
-      return allModelsHasTimezone && sonnetHasTimezone;
-    }
+    const hasSessionData = parsed.session && typeof parsed.session.percent === 'number';
+    const hasLegacyWeekly = parsed.weekly && typeof parsed.weekly.percent === 'number';
+    const hasAllModelsWeekly = parsed.weeklyAll && typeof parsed.weeklyAll.percent === 'number';
 
-    // Fallback for legacy format (single "Current week" without model qualifiers)
-    // Check for timezone pattern which indicates reset times are fully loaded
-    const hasTimezone = /\([A-Za-z]+\/[A-Za-z_]+\)/.test(clean);
-    return hasTimezone;
+    // Newer Claude builds often emit usable session/weekly data before the UI fully settles.
+    // If we can already parse session data plus either weekly format, treat the response as complete.
+    return hasSessionData && (hasLegacyWeekly || hasAllModelsWeekly);
   }
 
   sendCommands(shell, _output) {
     logger.agent(this.name, 'Sending /usage command...');
-    // Escape dismisses any previous output/UI, then type command + Enter
+    // Claude keeps slash-command suggestions open for /usage on newer builds.
+    // Confirm the command selection, then submit the actual command execution.
     setTimeout(() => shell.write('\x1b'), 50);
     setTimeout(() => shell.write('/usage'), 600);
     setTimeout(() => shell.write('\r'), 1000);
+    setTimeout(() => shell.write('\r'), 1400);
   }
 
   // After getting /usage output, dismiss dialog so next refresh starts with clean prompt

package/src/client-auto-refresh.js

@@ -87,8 +87,8 @@ ${metricExtractors}
       if (modelContainer) {
         const resetWrapper = modelContainer.querySelector('.reset-info-wrapper');
         if (resetWrapper) {
-          if (isZero || !resetsIn) {
-            // Hide "Resets in" when at 0%
+          if (!resetsIn) {
+            // Hide reset info only when the backend provides no reset time
             resetWrapper.style.display = 'none';
           } else {
             resetWrapper.style.display = '';

package/src/index.js

@@ -1,4 +1,5 @@
 const path = require('node:path');
+const os = require('node:os');
 const { ClaudeAgent } = require('./agents/claude.js');
 const { GeminiAgent } = require('./agents/gemini.js');
 const { CodexAgent } = require('./agents/codex.js');
@@ -22,6 +23,7 @@ const pkg = require(path.join(__dirname, '..', 'package.json'));
  * - 'activity': Activity-based polling (refreshes when log activity is detected)
  */
 const AUTO_REFRESH_MODES = ['none', 'interval', 'activity'];
+const DOCKER_INTERFACE_PATTERNS = [/^docker\d*$/i, /^br-/i, /^podman\d*$/i];
 
 function describeAgentShutdown(agent) {
   const parts = [];
@@ -41,10 +43,34 @@ function describeAgentShutdown(agent) {
   return parts.join(', ');
 }
 
+function isPrivateIpv4(address) {
+  return /^10\./.test(address) ||
+    /^192\.168\./.test(address) ||
+    /^172\.(1[6-9]|2\d|3[0-1])\./.test(address);
+}
+
+function detectDockerHost(networkInterfaces = os.networkInterfaces()) {
+  for (const [name, addresses] of Object.entries(networkInterfaces)) {
+    if (!DOCKER_INTERFACE_PATTERNS.some(pattern => pattern.test(name))) {
+      continue;
+    }
+
+    for (const info of addresses || []) {
+      if (info && info.family === 'IPv4' && !info.internal && isPrivateIpv4(info.address)) {
+        return info.address;
+      }
+    }
+  }
+
+  return null;
+}
+
 class AgentTank {
   constructor(options = {}) {
     this.port = options.port || 3456;
     this.host = options.host || '127.0.0.1';
+    this.explicitHost = !!options.host;
+    this.dockerAccess = options.dockerAccess !== false;
     this.autoDiscover = options.autoDiscover !== false;
     this.requestedAgents = options.agents || null;
     this.freshProcess = options.freshProcess || false;
@@ -52,6 +78,8 @@ class AgentTank {
     this.auth = options.auth || {};
     this.agents = new Map();
     this.server = null;
+    this.servers = [];
+    this.listenHosts = [];
     this.publicStatus = {}; // Public API status from upstream providers
     this.skipServer = options.skipServer || false; // Skip HTTP server in one-shot mode
     this.lastRefreshedAt = null;
@@ -183,7 +211,7 @@ class AgentTank {
 
     // Start HTTP server immediately so it's available during agent loading (unless skipped)
     if (!this.skipServer) {
-      this.startServer();
+      await this.startServer();
     }
 
     // Pre-spawn persistent processes in parallel before sending commands
@@ -377,12 +405,64 @@ class AgentTank {
   }
 
   startServer() {
-    this.server = createServer(this);
-    this.server.listen(this.port, this.host, () => {
+    const hosts = this._resolveListenHosts();
+
+    return Promise.all(hosts.map(async (host, index) => {
+      const server = createServer(this);
+      try {
+        await new Promise((resolve, reject) => {
+          const onError = (err) => {
+            server.off('listening', onListening);
+            reject(err);
+          };
+          const onListening = () => {
+            server.off('error', onError);
+            resolve();
+          };
+          server.once('error', onError);
+          server.once('listening', onListening);
+          server.listen(this.port, host);
+        });
+        this.servers.push(server);
+        this.listenHosts.push(host);
+      } catch (err) {
+        try {
+          server.close();
+        } catch (_closeErr) {
+          // Ignore cleanup errors for failed listeners
+        }
+
+        if (index === 0) {
+          throw err;
+        }
+
+        logger.warn(`Could not bind optional host ${host}:${this.port} (${err.message})`);
+      }
+    })).then(() => {
+      this.server = this.servers[0] || null;
+      if (this.listenHosts.length > 0) {
+        this.host = this.listenHosts[0];
+      }
       displayServerBanner(this);
     });
   }
 
+  _resolveListenHosts(detectHost = detectDockerHost) {
+    if (this.explicitHost) {
+      return [this.host];
+    }
+
+    const hosts = ['127.0.0.1'];
+    if (this.dockerAccess) {
+      const dockerHost = detectHost();
+      if (dockerHost && dockerHost !== '127.0.0.1') {
+        hosts.push(dockerHost);
+      }
+    }
+
+    return hosts;
+  }
+
   stop() {
     this.stopping = true;
     console.log('[Shutdown] Stopping Agent Tank...');
@@ -395,10 +475,15 @@ class AgentTank {
       }
       agent.killProcess();
     }
-    if (this.server) {
+    if (this.servers.length > 0) {
       console.log('[Shutdown] Closing HTTP server');
-      this.server.close();
+      for (const server of this.servers) {
+        server.close();
+      }
     }
+    this.server = null;
+    this.servers = [];
+    this.listenHosts = [];
   }
 
   /** Get keepalive status. @returns {Object|null} Keepalive manager status or null if not initialized */
@@ -419,4 +504,4 @@ class AgentTank {
   }
 }
 
-module.exports = { AgentTank, AUTO_REFRESH_MODES };
+module.exports = { AgentTank, AUTO_REFRESH_MODES, detectDockerHost };

package/src/server.js

@@ -135,9 +135,12 @@ function displayServerBanner(tank) {
   if (tank.auth.token) {
     logger.info('🔑 Authentication: API key');
   }
-  logger.server(`Listening on: ${tank.host}:${tank.port}`);
-  logger.server(`📄 Status page: http://${tank.host}:${tank.port}/`);
-  logger.server(`📡 JSON API:    http://${tank.host}:${tank.port}/status`);
+  const listenHosts = tank.listenHosts && tank.listenHosts.length > 0 ? tank.listenHosts : [tank.host];
+  logger.server(`Listening on: ${listenHosts.map(host => `${host}:${tank.port}`).join(', ')}`);
+  for (const host of listenHosts) {
+    logger.server(`📄 Status page: http://${host}:${tank.port}`);
+    logger.server(`📡 JSON API:    http://${host}:${tank.port}/status`);
+  }
   console.log('');
 }
 

package/src/usage-formatters.js

@@ -49,10 +49,10 @@ function getStatusDotClass(value) {
 }
 
 function resetInfoItem(resetsIn, originalValue, cycleType, options = {}) {
-  const { isZero = false, paceData = null } = options;
+  const { paceData = null } = options;
   // Always render the wrapper so XHR updates can show/hide it dynamically.
-  // Hidden when at 0% (no useful info when at full capacity).
-  const hidden = isZero ? ' style="display:none"' : '';
+  // Hidden only when there is no reset information to show.
+  const hidden = resetsIn ? '' : ' style="display:none"';
   const tooltip = originalValue ? ` title="${originalValue}"` : '';
 
   // Calculate elapsed time progress bar