A zero-dependency, local Python CLI tool to monitor token usage and statistics for popular AI coding agents like Hermes, Claude Code, CodeX, and OpenClaw.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install ai-agent-usage-stats
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install ai-agent-usage-stats using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is AI Agent Usage Stats?
AI Agent Usage Stats is a local command-line utility that aggregates and displays token usage statistics across multiple prominent AI development assistants. By serving as an accessible dashboard for your local environment, it stands out as an incredibly lightweight utility in the catalog of Openclaw Skills to help developers manage LLM API costs.
The tool operates on three fundamental principles. First, it is fully interactive, prompting you with an on-run menu to select which agent's data you wish to inspect. Second, it respects your absolute privacy by running fully offline and reading only local database files. Third, it is written entirely using the Python standard library, providing a zero-dependency setup that integrates smoothly with standard developer toolchains.
AI Agent Usage Stats Use Cases
- Cost and Token Monitoring: Track cumulative input and output token consumption across different local AI agents like Hermes, Claude Code, CodeX, and OpenClaw.
- Offline Usage Analysis: Analyze developer expenses and agent performance metrics without sending any database logs over the internet.
- Real-Time Development Watching: Run active live-monitoring tasks during coding sessions to spot sudden spikes in token consumption.
- Automation & Reporting Hooks: Chain the CLI with other Openclaw Skills to output consumption stats automatically upon completing tasks.
How AI Agent Usage Stats Works
- Execution: The user runs the
agent-usage-statscommand, either directly in the terminal, through an interactive watch loop, or nested within another agent's run script. - Selection: If no specific backend argument is provided, the tool outputs an interactive CLI selection menu displaying available local agent backends.
- Extraction: The underlying Python engine detects and directly parses the local filesystem databases (SQLite, JSONL files, or session directories) associated with your selected AI agent.
- Formatting: The tool processes the raw database logs, computes the exact token metrics, and outputs clean, readable stats directly to your terminal.
AI Agent Usage Stats Setup
Prerequisites
- Python 3.11+
- Local usage history for at least one supported agent (Hermes, Claude Code, CodeX, or OpenClaw)
Installation
To install and configure the utility, execute the following commands:
# Install the skill from clawhub
clawhub install ai-agent-usage-stats
# Run the setup script to initialize paths
python3 ~/skills/ai-agent-usage-stats/agent-usage-stats.py setup
Usage Reference
# Open the default interactive menu
agent-usage-stats
# Directly view a specific agent's stats (skips menu)
agent-usage-stats -a hermes
agent-usage-stats -a claude-code
agent-usage-stats -a codex
# Monitor token usage in real-time
agent-usage-stats --watch
agent-usage-stats -a hermes --watch
# List all supported backends detected on your system
agent-usage-stats --list-backends
# Check the installed version
agent-usage-stats --version
Automating with Hermes
You can integrate the tool as a post-task hook in your Hermes setup by adding this to your SKILL.md configurations:
run: agent-usage-stats -a hermes
AI Agent Usage Stats Data Schema & Taxonomy
The utility dynamically inspects and extracts metrics from local application directories. Below is the mapping of how the skill retrieves token consumption data:
| Agent Backend | Local Data Source Path | Extraction Details |
|---|---|---|
| Hermes | ~/.hermes/state.db |
Queries the sessions table within the SQLite database. |
| Claude Code | ~/.claude/projects/**/*.jsonl |
Iteratively parses project history JSON Lines files. |
| CodeX | ~/.codex/state_*.sqlite |
Queries the threads table inside the user's localized state. |
| OpenClaw | ~/.openclaw/agents/main/sessions/ |
Inspects directory session structures and local files. |
AI Agent Usage Stats Advanced Features
- Interactive vs. Direct Modes: Choose between an interactive CLI menu or skip it using direct command arguments (e.g.,
-a hermes) for script automations. - Continuous Monitor (Watch Mode): Keep a live feed open with the
--watchparameter to observe session-by-session token growth as you work with your AI agents. - Zero-Dependency Core: Zero external Python packages required, ensuring minimal footprint, zero security vulnerabilities, and lightning-fast execution.
- Extensible Integration: Designed to be integrated easily into custom toolchains and other Openclaw Skills to trigger reports at key milestones of your development workflow.
SKILL.md
Loading
Related Openclaw Skills
OPC Playbook (One-Person Company)
The OPC Playbook is a dual-mode strategic framework designed to help solo founders rigorously evaluate startup viability and systematically execute an AI-native business model.
AI Code Review
An AI-powered multi-dimensional code review tool that scans code changes and provides structured feedback, risk assessments, and code fixes.
audio2srt-localgen
A fully offline project generator and deployer that builds a local MLX Whisper audio transcription and translation Web GUI tailored for Apple Silicon.
Brief Master
An elite execution brief generator designed to eliminate wasted tokens and ensure precise downstream agent execution.
Autoresearch Loop
A highly structured, metric-driven modify-verify-decide optimization loop with strict safety gates and approval contracts for AI coding agents.
Video Metadata Analyzer
An automated multi-stage video analysis pipeline that processes parallel visual frames and audio transcriptions to synthesize optimized, publish-ready metadata for Bilibili.
Featured*
