agent-tank 0.9.6 → 0.9.8

package/README.md

@@ -7,7 +7,7 @@ Agent Tank is a local dashboard and HTTP API for monitoring usage limits in AI c
 It supports:
 
 - Claude Code
-- Gemini CLI
+- Antigravity CLI
 - OpenAI Codex
 
 ## How It Gets the Data
@@ -17,7 +17,7 @@ This is the part that matters.
 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.
 
 - Claude: runs `/usage`
-- Gemini: runs `/stats`
+- Antigravity: runs `/usage`
 - Codex: prefers JSON-RPC `account/rateLimits/read`, falls back to `/status`
 
 What it does not do:
@@ -37,7 +37,7 @@ Agent Tank is meant for subscription-based coding agent products where the CLI i
 Examples:
 
 - Claude Code Pro / Max
-- Gemini CLI with supported subscription plans
+- Antigravity CLI with supported subscription plans
 - ChatGPT Codex with supported plans
 
 It is not for:
@@ -62,6 +62,47 @@ Or run it directly:
 npx agent-tank
 ```
 
+### Run from Source
+
+If you want to run the latest code from a checkout instead of the published package:
+
+```bash
+# 1. Clone the repo
+git clone https://github.com/integry/agent-tank.git
+cd agent-tank
+
+# 2. Install dependencies (compiles node-pty natively)
+npm install
+
+# 3. Run it
+npm start          # = node bin/agent-tank.js
+```
+
+By default it auto-discovers installed CLIs and serves the dashboard + API at `http://127.0.0.1:3456`.
+
+To pass flags, call the entry point directly (`npm start` does not forward arguments cleanly):
+
+```bash
+node bin/agent-tank.js --claude --codex --port 8080
+node bin/agent-tank.js --once --json          # one-shot, prints JSON, no server
+node bin/agent-tank.js --no-docker            # localhost only
+node bin/agent-tank.js --help                 # full option list
+```
+
+Prerequisites:
+
+- **Node.js 18+**
+- `node-pty` is a native module, so `npm install` needs **Python 3.8+** and **C/C++ build tools**. See [Installation Notes](#installation-notes) if the build fails.
+- At least one supported CLI installed and authenticated on your `PATH` (`claude`, `agy`, or `codex`).
+
+Other useful scripts:
+
+```bash
+npm test           # run all tests
+npm run lint       # check code style
+npm run rebuild    # rebuild node-pty against a detected Python
+```
+
 ### First Run
 
 ```bash
@@ -87,14 +128,14 @@ agent-tank --no-docker
 
 ```bash
 # Monitor only specific agents
-agent-tank --claude --gemini
-
-# Prefer direct Gemini quota fetching
-agent-tank --gemini --gemini-mode direct
+agent-tank --claude --agy
 
 # Use a custom port
 agent-tank --port 8080
 
+# Keep Agent Tank running after closing this terminal
+agent-tank --background
+
 # Fetch once and print JSON
 agent-tank --once --json
 
@@ -130,7 +171,7 @@ agent-tank --refresh-cooldown 60
 | 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 |
+| Antigravity | PTY `/usage` | Per-model quota availability and reset windows when reported |
 | Codex | JSON-RPC preferred, PTY fallback | 5-hour limits, weekly limits, model/account info |
 
 ## Basic Usage
@@ -153,6 +194,14 @@ agent-tank --claude --codex
 agent-tank --once --json
 ```
 
+### Background Server Mode
+
+```bash
+agent-tank --background
+```
+
+This starts Agent Tank as a detached process, prints the background PID, and exits the parent command.
+
 ### Bind to a Different Host or Port
 
 ```bash
@@ -186,9 +235,8 @@ Set it to `0` to disable the cooldown entirely.
 ```text
 Options:
   --claude              Enable Claude monitoring
-  --gemini              Enable Gemini monitoring
+  --agy                 Enable Antigravity monitoring
   --codex               Enable Codex monitoring
-  --gemini-mode <mode>  Gemini strategy: fallback, direct, pty (default: fallback)
   --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)
@@ -202,14 +250,15 @@ Options:
   --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)
+  --auto-refresh-interval <seconds>  Auto-refresh interval in seconds (default: 60, 0 = disabled)
   --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)
+  --keepalive-interval <seconds>     Session keepalive interval in seconds (default: 300, 0 = disabled)
   --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)
+  --background          Start Agent Tank as a detached background process
   --help, -h            Show this help message
 ```
 
@@ -217,7 +266,9 @@ Options:
 
 ### Environment Variables
 
-Environment variables override CLI flags and config file values.
+Environment variables override CLI flags and config file values. Background mode has
+three exceptions: `--no-background`, `--once`, and `--json` suppress
+`AGENT_TANK_BACKGROUND=1` for that run.
 
 | Variable | Description |
 |---|---|
@@ -228,7 +279,6 @@ Environment variables override CLI flags and config file values.
 | `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_GEMINI_MODE` | Gemini strategy: `fallback`, `direct`, or `pty` |
 | `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 |
@@ -237,18 +287,20 @@ Environment variables override CLI flags and config file values.
 | `AGENT_TANK_KEEPALIVE` | Enable/disable keepalive |
 | `AGENT_TANK_KEEPALIVE_INTERVAL` | Keepalive interval in seconds |
 | `AGENT_TANK_HISTORY_RETENTION_DAYS` | History retention window |
+| `AGENT_TANK_BACKGROUND` | Start as a detached background process (`1`/`true`) |
+| `AGENT_TANK_BACKGROUND_LOG` | Background child stdout/stderr log path (defaults to a temp file) |
+| `AGENT_TANK_BACKGROUND_GRACE_MS` | Parent startup grace period before reporting background success; success means the child survived this period |
 
 ### Config File
 
 ```json
 {
   "claude": true,
-  "gemini": true,
+  "agy": true,
   "codex": false,
   "port": 8080,
   "dockerAccess": true,
   "claudeApi": false,
-  "geminiMode": "fallback",
   "refreshCooldown": 30,
   "autoRefresh": {
     "mode": "activity",
@@ -272,26 +324,17 @@ Run with:
 agent-tank -c config.json
 ```
 
-## Gemini Modes
-
-By default, Gemini runs in `fallback` mode:
-
-- try a direct quota fetch using the local Gemini OAuth session
-- fall back to PTY `/stats` if the direct path fails
-
-Available modes:
+## Antigravity
 
-- `fallback`: direct first, PTY fallback
-- `direct`: use the direct quota API only
-- `pty`: use interactive Gemini CLI `/stats` only
+Antigravity support uses the `agy` CLI and reads the interactive `/usage` output.
 
 In `--once` mode, Agent Tank prints the result and exits immediately after the output is flushed.
 
 Examples:
 
 ```bash
-agent-tank --gemini --gemini-mode direct
-agent-tank --gemini --gemini-mode pty
+agent-tank --agy
+agent-tank --agy --once --json
 ```
 
 ## HTTP API
@@ -421,7 +464,7 @@ In activity mode, Agent Tank watches common local directories:
 
 - Claude: `~/.config/claude/projects/`, `~/.claude/`
 - Codex: `~/.codex/sessions/`, `~/.codex/`
-- Gemini: `~/.config/gemini/`, `~/.gemini/`
+- Antigravity: `~/.gemini/antigravity-cli/`
 
 If no suitable directories are found, it falls back to interval mode.
 
@@ -509,15 +552,15 @@ You need at least one supported CLI installed and authenticated.
 
 - [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`
+- Antigravity CLI as `agy`
+  - `/usage` command support required
 - OpenAI Codex as `codex`
 
 Useful checks:
 
 ```bash
 claude --version
-gemini --version
+agy --version
 codex --version
 ```
 
@@ -527,7 +570,7 @@ codex --version
 const { AgentTank } = require('agent-tank');
 
 const watcher = new AgentTank({
-  agents: ['claude', 'gemini'],
+  agents: ['claude', 'agy'],
   port: 3456,
   autoDiscover: true
 });

package/bin/agent-tank.js

@@ -1,17 +1,22 @@
 #!/usr/bin/env node
-/* eslint-disable complexity */
+/* eslint-disable complexity -- CLI option merging is centralized here to preserve precedence behavior. */
+/* eslint-disable max-lines -- Tracked in issue #90; CLI help text and option precedence stay together for now. */
 
 const { parseArgs } = require('node:util');
-const { AgentTank } = require('../src/index.js');
-const { installShutdownHandlers } = require('../src/shutdown-handler.js');
+const {
+  isTruthyEnv,
+} = require('../src/process-utils.js');
+const {
+  spawnBackgroundProcess,
+  warnAboutRunningProcesses,
+} = require('../src/cli-background.js');
 const pkg = require('../package.json');
 
 const options = {
   claude: { type: 'boolean', default: false },
-  gemini: { type: 'boolean', default: false },
+  agy: { type: 'boolean', default: false },
   codex: { type: 'boolean', default: false },
   'claude-api': { type: 'boolean', default: false },
-  'gemini-mode': { type: 'string' },
   port: { type: 'string', default: '3456' },
   host: { type: 'string' },
   docker: { type: 'boolean', default: true },
@@ -33,9 +38,15 @@ const options = {
   'keepalive-interval': { type: 'string', default: '300' },
   once: { type: 'boolean', default: false },
   json: { type: 'boolean', default: false },
+  background: { type: 'boolean', default: false },
 };
 
-const { values } = parseArgs({ options, allowPositionals: false, allowNegative: true });
+const { values, tokens } = parseArgs({
+  options,
+  allowPositionals: false,
+  allowNegative: true,
+  tokens: true,
+});
 
 function exitWithCode(code, message, stream = process.stderr) {
   if (message) {
@@ -63,10 +74,9 @@ Usage: agent-tank [options]
 
 Options:
   --claude              Enable Claude monitoring
-  --gemini              Enable Gemini monitoring
+  --agy                 Enable Antigravity monitoring
   --codex               Enable Codex monitoring
   --claude-api          Use direct Anthropic API for Claude usage (faster, 60s refresh)
-  --gemini-mode <mode>  Gemini strategy: fallback, direct, pty (default: fallback)
   --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)
@@ -87,6 +97,7 @@ Options:
   --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)
+  --background          Start Agent Tank as a detached background process
   --help, -h            Show this help message
 
 Auto-Refresh Modes:
@@ -103,7 +114,6 @@ Environment variables:
   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_GEMINI_MODE  Gemini strategy: fallback, direct, pty
   AGENT_TANK_AUTO_REFRESH   Enable/disable background auto-refresh ("1" or "true" / "0" or "false")
   AGENT_TANK_AUTO_REFRESH_MODE      Refresh mode: none, interval, activity
   AGENT_TANK_AUTO_REFRESH_INTERVAL  Auto-refresh interval in seconds
@@ -112,14 +122,18 @@ Environment variables:
   AGENT_TANK_KEEPALIVE      Enable/disable session keepalive ("1" or "true" / "0" or "false")
   AGENT_TANK_KEEPALIVE_INTERVAL  Session keepalive interval in seconds
   AGENT_TANK_HISTORY_RETENTION_DAYS  Days to retain usage history
+  AGENT_TANK_BACKGROUND  Start as a detached background process ("1" or "true")
+  AGENT_TANK_BACKGROUND_LOG  Log file for background child stdout/stderr
+  AGENT_TANK_BACKGROUND_GRACE_MS  Parent startup grace period before reporting background success
+                                  (success means the child survived this period)
 
 Examples:
   agent-tank                          # Auto-discover and monitor all available
-  agent-tank --claude --gemini        # Monitor specific agents
+  agent-tank --background             # Start in the background and print the PID
+  agent-tank --claude --agy           # 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 --gemini-mode direct     # Prefer direct Gemini quota API calls
   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
@@ -160,6 +174,37 @@ async function main() {
     return;
   }
 
+  const explicitNoBackground = tokens.some(token =>
+    token.kind === 'option' &&
+    token.name === 'background' &&
+    token.rawName === '--no-background');
+  const explicitBackground = tokens.some(token =>
+    token.kind === 'option' &&
+    token.name === 'background' &&
+    token.rawName === '--background');
+  const envBackgroundRequested = isTruthyEnv(process.env.AGENT_TANK_BACKGROUND) &&
+    !explicitNoBackground &&
+    !values.once &&
+    !values.json;
+  const backgroundRequested = explicitBackground || envBackgroundRequested;
+  const backgroundChild = isTruthyEnv(process.env.AGENT_TANK_BACKGROUND_CHILD);
+
+  if (backgroundRequested && !backgroundChild) {
+    for (const incompatibleFlag of ['once', 'json']) {
+      if (values[incompatibleFlag]) {
+        exitWithCode(1, `Error: --background cannot be combined with --${incompatibleFlag}`);
+        return;
+      }
+    }
+
+    const started = await spawnBackgroundProcess();
+    process.exitCode = started ? 0 : 1;
+    return;
+  }
+
+  const { AgentTank } = require('../src/index.js');
+  const { installShutdownHandlers } = require('../src/shutdown-handler.js');
+
   // Load config file if specified
   let config = {};
   if (values.config) {
@@ -174,7 +219,7 @@ async function main() {
   // Merge CLI options with config (env vars > CLI flags > config file)
   const agents = [];
   if (values.claude || config.claude) agents.push('claude');
-  if (values.gemini || config.gemini) agents.push('gemini');
+  if (values.agy || config.agy) agents.push('agy');
   if (values.codex || config.codex) agents.push('codex');
 
   const auth = {
@@ -203,9 +248,6 @@ async function main() {
     config.claudeApi ||
     claudeApiEnv === '1' || claudeApiEnv === 'true';
 
-  const geminiModeEnv = process.env.AGENT_TANK_GEMINI_MODE;
-  const geminiMode = geminiModeEnv || values['gemini-mode'] || config.geminiMode || 'fallback';
-
   // Auto-refresh configuration (env > CLI > config file)
   const autoRefreshEnv = process.env.AGENT_TANK_AUTO_REFRESH;
   let autoRefreshEnabled = values['auto-refresh'];
@@ -298,7 +340,6 @@ async function main() {
     auth,
     freshProcess,
     claudeApi,
-    geminiMode,
     autoRefreshEnabled: onceMode ? false : autoRefreshEnabled, // Disable auto-refresh in one-shot mode
     autoRefreshInterval,
     autoRefreshMode: onceMode ? 'none' : autoRefreshMode, // Disable auto-refresh in one-shot mode
@@ -354,7 +395,11 @@ async function main() {
       }
     }
 
+    const runningProcessWarning = (!jsonMode && !backgroundChild) ?
+      warnAboutRunningProcesses() :
+      Promise.resolve();
     await watcher.start();
+    await runningProcessWarning;
   } catch (err) {
     cleanupShutdownHandlers();
     if (jsonMode) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-tank",
-  "version": "0.9.6",
-  "description": "Monitor and query usage limits for LLM CLI tools (Claude, Gemini, Codex) via HTTP API",
+  "version": "0.9.8",
+  "description": "Monitor and query usage limits for LLM CLI tools (Claude, Antigravity, Codex) via HTTP API",
   "main": "src/index.js",
   "bin": {
     "agent-tank": "bin/agent-tank.js"
@@ -19,7 +19,8 @@
   "keywords": [
     "llm",
     "claude",
-    "gemini",
+    "antigravity",
+    "agy",
     "codex",
     "openai",
     "anthropic",
@@ -42,6 +43,7 @@
   },
   "homepage": "https://agenttank.io",
   "dependencies": {
+    "chokidar": "^3.6.0",
     "node-pty": "^1.0.0",
     "source-map-support": "^0.5.21"
   },

package/src/activity-monitor.js

@@ -1,7 +1,7 @@
 /**
  * ActivityMonitor - Monitors local log directories for LLM CLI activity
  *
- * Watches known log directories for Claude, Codex, and Gemini using fs.watch.
+ * Watches known log directories for Claude, Codex, and Antigravity using chokidar with polling.
  * When activity is detected (new log entries), it triggers usage refresh callbacks
  * with configurable debouncing to prevent excessive polling.
  */
@@ -9,6 +9,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
+const chokidar = require('chokidar');
 
 /**
  * Default log directories for each agent.
@@ -23,9 +24,8 @@ const DEFAULT_LOG_DIRECTORIES = {
     path.join(os.homedir(), '.codex', 'sessions'),
     path.join(os.homedir(), '.codex'),
   ],
-  gemini: [
-    path.join(os.homedir(), '.config', 'gemini'),
-    path.join(os.homedir(), '.gemini'),
+  agy: [
+    path.join(os.homedir(), '.gemini', 'antigravity-cli'),
   ],
 };
 
@@ -72,7 +72,7 @@ class ActivityMonitor {
 
   /**
    * Start monitoring log directories for activity.
-   * Sets up fs.watch on each agent's log directories.
+   * Sets up chokidar polling watchers on each agent's log directories.
    *
    * @returns {Object} Status object with monitoring details
    */
@@ -92,7 +92,18 @@ class ActivityMonitor {
       for (const dir of dirs) {
         if (fs.existsSync(dir)) {
           try {
-            const watcher = fs.watch(dir, { recursive: true }, (eventType, filename) => {
+            // Use chokidar with polling to avoid EMFILE errors from too many native watchers
+            const watcher = chokidar.watch(dir, {
+              persistent: true,
+              ignoreInitial: true,
+              usePolling: true,
+              interval: 1000,
+              depth: 99,
+              ignored: ['**/.git/**', '**/*.lock'],
+            });
+
+            watcher.on('all', (eventType, filepath) => {
+              const filename = path.relative(dir, filepath);
               this._handleFileChange(agent, eventType, filename);
             });
 
@@ -158,7 +169,7 @@ class ActivityMonitor {
   }
 
   /**
-   * Handle a file change event from fs.watch.
+   * Handle a file change event from chokidar.
    * Debounces activity detection per agent.
    *
    * @param {string} agent - Agent name