Fleet Auditor Skill
Relevant source files
The following files were used as context for generating this wiki page:
The Fleet Auditor is a cross-platform auditing system designed to detect token waste across various AI agent environments, including Claude Code, Codex, OpenClaw, Hermes, and OpenCode. It serves as a high-level diagnostic tool that identifies idle heartbeats, model misrouting, and configuration bloat, providing users with actionable fixes and estimated dollar savings.
While the primary Token Optimizer focuses on deep-diving into specific configuration files like CLAUDE.md and MEMORY.md, the Fleet Auditor provides a broader view of the entire "fleet" of agent systems installed on a user's machine. It quantifies usage patterns over time (typically 30 days) and flags critical security or cost risks, such as the "ClawJacked" vulnerability in older OpenClaw versions.
Sources: skills/fleet-auditor/SKILL.md:1-12, skills/token-optimizer/SKILL.md:1-10
Architecture and Workflow
The Fleet Auditor operates through a five-phase lifecycle: Initialization, Scanning, Auditing, Presentation, and Optional Deep Dives. It relies on a core Python script, fleet.py, which is dynamically resolved at runtime to ensure the most recent version is used across different installation paths.
Execution Flow
The following diagram illustrates the standard operational flow of the Fleet Auditor from system detection to the presentation of findings.
The flow begins with runtime resolution and moves through data collection and analysis before offering the user specific remediation paths.
Sources: skills/fleet-auditor/SKILL.md:14-118
System Detection and Initialization
The initialization phase (Phase 0) is critical for resolving the correct execution environment and finding the fleet.py script. The system checks for specific environment variables and directory structures to determine the active runtime (e.g., claude, codex, or opencode).
Runtime Resolution Logic
The system prioritizes environment variables such as TOKEN_OPTIMIZER_RUNTIME, CLAUDE_PLUGIN_ROOT, and CODEX_HOME. If no environment variables are present, it falls back to checking for specific configuration directories like ~/.codex or ~/.config/opencode.
Sources: skills/fleet-auditor/SKILL.md:16-36
Script Location Resolution
To avoid issues where stale copies in plugin caches shadow fresh installs, the system performs a version-aware search for fleet.py. It inspects the plugin.json in the root of each candidate directory and selects the one with the highest version number.
Sources: skills/fleet-auditor/SKILL.md:38-58
Data Collection and Analysis
Once initialized, the Auditor performs a scan of session data and executes waste pattern detection logic.
Scanning and Auditing Process
| Phase | Command | Description |
|---|---|---|
| Scan | fleet.py scan --days 30 | Collects token usage data from all detected systems over the last 30 days. |
| Audit | fleet.py audit --json | Runs pattern detection algorithms to identify high-severity waste. |
Sources: skills/fleet-auditor/SKILL.md:65-79
Waste Patterns and Security Checks
The audit phase includes specific logic for different platforms:
- Codex: Detects model misrouting and usage patterns. If pricing data is unavailable locally, it reports token waste without inventing dollar costs.
- OpenClaw: Includes a security-specific check (as of March 2026) for CVEs such as ClawJacked (v < 2026.3.12) and ClawHavoc (malicious skills).
- General: Identifies idle "heartbeat" burns where agents consume tokens while inactive.
Sources: skills/fleet-auditor/SKILL.md:81-94
Findings and Remediation
Findings are presented to the user ordered by severity and potential monthly savings. The Auditor categorizes results by system and provides specific "Fix" recommendations.
Reporting Format
A typical Fleet Auditor result includes:
- Systems Detected: Count of runs and total cost per system.
- Waste Patterns: Descriptions of issues with severity levels.
- Potential Savings: Quantified monthly recurring savings in dollars and tokens.
Sources: skills/fleet-auditor/SKILL.md:96-114
Remediation Actions
Users can choose to view detailed fix snippets, generate an HTML-based visual dashboard, or transition into a Deep Dive using the /token-optimizer skill for Claude Code-specific optimizations.
Sources: skills/fleet-auditor/SKILL.md:116-137
Implementation Guidelines and Rules
The Fleet Auditor follows strict operational rules to ensure data privacy and technical accuracy.
- Privacy First: The system never reads or exposes message content; it only analyzes token counts and metadata.
- Confidence Thresholds: Findings with a confidence level below 0.4 are suppressed to avoid false positives.
- Quantification: All findings must be quantified in both tokens and dollars where possible.
- Safety: The system recommends archiving files (moving them outside the skills directory) rather than deleting them.
Sources: skills/fleet-auditor/SKILL.md:148-158, skills/token-optimizer/SKILL.md:273-282
Conclusion
The Fleet Auditor Skill serves as the entry point for cross-platform token management. By identifying system-wide waste and security vulnerabilities across multiple agent runtimes, it enables users to regain control over their context windows and AI operational costs before proceeding to the granular optimizations provided by the core Token Optimizer.