fleet-auditor

Fleet Auditor: Cross-Platform Agent Token Waste Auditor

Detects installed agent systems, collects token usage data, identifies waste patterns, and recommends fixes with dollar savings estimates. Everyone tracks. Nobody coaches. Until now.

Use when: Running multiple agent systems, spending $2-5/day on agents, suspecting idle heartbeats are burning tokens, or want a cross-system cost audit.

---

Phase 0: Initialize

1. Resolve runtime and fleet.py path (works for both skill and plugin installs):

RUNTIME="${TOKEN_OPTIMIZER_RUNTIME:-}"
if [ -z "$RUNTIME" ]; then
  if [ -n "$CLAUDE_PLUGIN_ROOT" ] || [ -n "$CLAUDE_PLUGIN_DATA" ]; then
    RUNTIME="claude"
  elif [ -n "$OPENCODE" ] || [ -n "$OPENCODE_BIN" ] || [ -n "$OPENCODE_CONFIG_DIR" ] || [ -n "$OPENCODE_CONFIG" ]; then
    RUNTIME="opencode"
  elif [ -n "$CODEX_HOME" ]; then
    RUNTIME="codex"
  elif [ -d "$HOME/.config/opencode" ] && [ ! -d "$HOME/.codex" ]; then
    RUNTIME="opencode"
  elif [ -d "$HOME/.codex" ]; then
    RUNTIME="codex"
  else
    RUNTIME="claude"
  fi
fi

# Resolve fleet.py to the NEWEST installed copy across channels so a stale
# plugin-cache copy never shadows a fresh install (issue #57). find -L follows the
# install.sh symlink under ~/.claude/skills; cd -P resolves it before reading each
# copy's plugin.json for its version. find (not bare globs) never errors under zsh.
FLEET_PY=""; _best_ver=""
while IFS= read -r _cand; do
  [ -f "$_cand" ] || continue
  _root="$(cd -P -- "$(dirname -- "$_cand")/../../.." 2>/dev/null && pwd)"
  _ver="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$_root/.claude-plugin/plugin.json" 2>/dev/null | head -1)"
  [ -n "$_ver" ] || _ver="0.0.0"
  if [ -z "$_best_ver" ] || [ "$(printf '%s\n%s\n' "$_ver" "$_best_ver" | sort -t. -k1,1n -k2,2n -k3,3n -k4,4n | tail -n1)" = "$_ver" ]; then
    _best_ver="$_ver"; FLEET_PY="$_cand"
  fi
done <<EOF
$(find -L "$HOME/.claude/skills" "$HOME/.claude/plugins/cache" "$HOME/.claude/token-optimizer" "$HOME/.codex/skills" "$HOME/.codex/plugins/cache" "$HOME/.config/opencode/plugins/cache" "$HOME/.config/opencode/plugins" -type f -name fleet.py -path '*fleet-auditor*/scripts/fleet.py' 2>/dev/null)
EOF
if [ -z "$FLEET_PY" ]; then echo "[Error] fleet.py not found. Is Fleet Auditor installed?"; exit 1; fi
echo "Using: $FLEET_PY"
export TOKEN_OPTIMIZER_RUNTIME="$RUNTIME"

Use $FLEET_PY for all subsequent fleet.py calls.

2. Detect systems:

python3 "$FLEET_PY" detect --json

Parse the JSON output. Report what was found.

If nothing detected, explain: "No agent systems found. Fleet Auditor supports: Claude Code, Codex, OpenClaw, NanoClaw, Hermes, OpenCode, IronClaw."

---

Phase 1: Scan

Collect token usage data from detected systems:

python3 "$FLEET_PY" scan --days 30

Report how many runs were collected per system. If this is the first scan, it may take a moment to parse all session files.

---

Phase 2: Audit

Run waste pattern detection:

python3 "$FLEET_PY" audit --json

Parse the JSON output. Present findings ordered by severity and monthly savings.

If no waste found: "Your fleet looks clean. No significant waste patterns detected."

For Codex findings, be careful with dollars: if a model's pricing is not in the local pricing table, present token waste confidently and say dollar impact depends on current model pricing instead of inventing a cost.

OpenClaw Security + Cost Check (March 2026):

• If OpenClaw is detected and version < 2026.3.12: flag as HIGH severity. 31 CVEs including ClawJacked (full agent takeover). Compromised instances run rogue agents that burn tokens undetected. Recommend immediate upgrade.
• Check for ClawHub skills matching ClawHavoc campaign patterns (1,184+ malicious skills). These skills exfiltrate data via extra API calls, inflating token spend.
• Flag if gateway rate limiting is disabled (CVE-2026-25253). Without it, brute-force attacks can spawn unlimited agent sessions. Recommend: openclaw config set security.rateLimit.enabled true

---

Phase 3: Present Findings

[Fleet Auditor Results]

SYSTEMS DETECTED
- Claude Code: X runs ($Y.YY)
- Codex: X runs ($Y.YY)
- OpenClaw: X runs ($Y.YY)

WASTE PATTERNS FOUND
1. [SEVERITY] Description
   Est. savings: $X.XX/month
   Fix: recommendation

2. [SEVERITY] Description
   ...

TOTAL POTENTIAL SAVINGS: $X.XX/month

Ready to act? I can:
1. Show detailed fix snippets for each finding
2. Generate the fleet dashboard for visual analysis
3. Run /token-optimizer for deeper Claude Code optimization

---

Phase 4: Dashboard (optional)

If user wants visual analysis:

python3 "$FLEET_PY" dashboard

This generates ~/.claude/_backups/token-optimizer/fleet-dashboard.html in Claude Code, or ~/.codex/_backups/token-optimizer/fleet-dashboard.html when TOKEN_OPTIMIZER_RUNTIME=codex.

---

Phase 5: Deep Dive (optional)

For Claude Code specifically, offer /token-optimizer for full audit (CLAUDE.md, skills, MCP, hooks, etc.).

For Codex specifically, offer token-optimizer for full audit (AGENTS.md, Codex memories, plugin skills, MCP, balanced hooks, compact prompt, status line).

For other systems, show the fix snippets from the audit and guide the user through implementing them.

---

Reference Files

Phase	Read
Adapter development	references/fleet-systems.md
Detector development	references/waste-patterns.md

---

Error Handling

• No systems detected: Report cleanly, list supported systems
• Empty scan results: System detected but no session data in window. Suggest increasing --days
• Permission errors: Report which files couldn't be read, continue with available data
• Corrupted data: Skip bad files, report count of skipped files
• fleet.py not found: Check both skill and plugin install paths

---

Core Rules

• Quantify everything in dollars AND tokens
• Never read or expose message content (privacy-first)
• Report confidence levels alongside findings
• Suppress findings below 0.4 confidence threshold
• Always show fix snippets with recommendations
• Frame savings as monthly recurring, not one-time