Usage Statistics

Why Track Usage?

• Cost Awareness - See which AI providers consume most of your budget
• Pattern Recognition - Identify your most-used tools and workflows
• Optimization - Find opportunities to use cheaper models for simple tasks
• Debugging - Understand what happened during complex multi-model sessions

Quick Start

View Statistics

1usage_stats({ action: "view" })

Returns a rich terminal visualization with:

• BigText ASCII Header - "TACHIBOT" in block font with cristal gradient (cyan→green)
• Pie Chart - Tool usage distribution with colored segments
• Braille Progress Bars - High-resolution usage bars using Unicode braille (⣿⣧⡇⡀)
• Donut Chart - Cost distribution with total in center
• Summary Table - Total calls, tokens, cost, and date range

Reset Statistics

1usage_stats({ action: "reset" })

Clears all statistics for the current repository. Useful when starting a new project phase.

Parameters

Scope: Per-Repo vs Global

Statistics are tracked per repository by default. This helps you understand usage patterns for specific projects.

Current Repository

1// Default - stats for current repo only
2usage_stats({ action: "view", scope: "current" })

All Repositories

1// Aggregate stats across all repos
2usage_stats({ action: "view", scope: "all" })

Output Formats

Table Format (Default)

Human-readable ASCII table with bar charts. Best for quick overview in Claude/Cursor.

JSON Format

1usage_stats({ action: "view", format: "json" })

Machine-readable JSON for integration with other tools or dashboards:

1{
2  "repo": "/path/to/project",
3  "period": "2025-12-28",
4  "tools": {
5    "grok_reason": { "calls": 12, "tokens": 24500, "cost": 0.49 },
6    "gemini_brainstorm": { "calls": 8, "tokens": 18200, "cost": 0.36 },
7    "perplexity_ask": { "calls": 6, "tokens": 12100, "cost": 0.24 }
8  },
9  "totals": { "calls": 63, "tokens": 67500, "cost": 1.09 }
10}

Visual Features

Usage stats now includes rich terminal visualizations:

• BigText ASCII Headers - Gradient-colored ASCII art titles using block font
• Pie Charts - Visual distribution of tool usage with percentage breakdown
• Braille Progress Bars - High-resolution Unicode braille bars (⣿⣀) for usage visualization
• Donut Charts - Cost distribution visualization with center total
• Gradient Dividers - Colored separators using gradient presets (cristal, rainbow, mind)

What Gets Tracked

• Tool Calls - Number of times each tool was invoked
• Tokens - Approximate token usage per tool
• Cost - Estimated cost based on provider pricing
• Workflows - Tool usage from workflow executions
• Models - Which AI models were used per tool

Configuration

Control usage tracking behavior with environment variables:

1# Enable/disable usage tracking (default: true)
2TACHIBOT_USAGE_TRACKING=true
3 
4# Show model tags in output (default: true)
5TACHIBOT_SHOW_MODEL_TAGS=true
6 
7# Show receipt after tool calls (default: false)
8TACHIBOT_SHOW_RECEIPT=true
9 
10# Enable/disable BigText ASCII headers (default: true)
11TACHIBOT_BIG_HEADERS=false

Best Practices

• Check weekly - Review stats to understand your usage patterns
• Reset per sprint - Clear stats at the start of each project phase
• Compare repos - Use scope: "all" to see which projects consume most
• Export JSON - Save stats for billing reconciliation or team reviews

Related