ClaudeUsage

A Rails engine for tracking Claude Code token usage and costs in your Rails applications. Get real-time insights into your Claude Code usage with automatic cost calculation using LiteLLM pricing data.

Features

✅ Automatic Usage Tracking - Reads Claude Code JSONL logs automatically
✅ Auto-Detection - Automatically detects project name from Rails.root
✅ LiteLLM Pricing Integration - Fetches up-to-date pricing from LiteLLM API
✅ Tiered Pricing Support - Handles 200k+ token tiered pricing
✅ Cache Token Tracking - Tracks cache creation and read tokens
✅ Beautiful Web UI - Modern, responsive interface for viewing usage
✅ JSON API - Programmatic access to usage data
✅ Rake Tasks - CLI commands for quick reports
✅ Zero Configuration - Works out of the box with sensible defaults

Installation

Add this line to your application's Gemfile in the development group:

group :development do
  gem 'claude_usage'
end

And then execute:

bundle install

Note: This gem is designed for development environments to track your Claude Code usage while building your application. It's recommended to keep it in the development group unless you need production usage tracking.

Quick Start

After installing the gem, run the generator:

rails generate claude_usage:install

IMPORTANT: Verify your setup immediately:

rake claude_usage:show_project

This command will:

• Show which project is being tracked
• List all available Claude Code projects
• Indicate if data files exist
• Provide solutions if no data is found

If the project name doesn't match, update config/initializers/claude_usage.rb:

ClaudeUsage.configure do |config|
  config.project_name = "actual-project-name"  # From show_project output
end

Start your Rails server and visit:

http://localhost:3000/claude-usage

Usage

Web Interface

Visit http://localhost:3000/claude-usage to see:

• Total usage statistics
• Daily breakdown of token usage
• Cost calculations
• Model usage information

JSON API

Access usage data programmatically:

curl http://localhost:3000/claude-usage/json

Rake Tasks

# Show daily usage report
rake claude_usage:daily

# Show total usage
rake claude_usage:total

# Clear pricing cache
rake claude_usage:clear_cache

# Show which project is being tracked and list all available projects
rake claude_usage:show_project

# Debug pricing issues (helps diagnose $0 cost problems)
rake claude_usage:debug_pricing

Programmatic Access

# In your Rails app
aggregator = ClaudeUsage::UsageAggregator.new
totals = aggregator.total_usage
daily = aggregator.daily_usage

# Access specific data
puts "Total cost: $#{totals[:total_cost]}"
puts "Total tokens: #{totals[:total_tokens]}"
puts "Models used: #{totals[:models_used].join(', ')}"

Configuration

You can customize the behavior in config/initializers/claude_usage.rb:

ClaudeUsage.configure do |config|
  # Project name - defaults to Rails.root.basename
  config.project_name = "my-rails-app"

  # Custom Claude paths (optional)
  config.claude_paths = [
    File.expand_path("~/.config/claude/projects"),
    File.expand_path("~/.claude/projects")
  ]

  # Pricing cache expiry (default: 1 hour)
  config.cache_expiry = 1.hour

  # Offline mode (use cached pricing only)
  config.offline_mode = false
end

Configuration Options

• project_name - The Claude Code project name to track (defaults to Rails app name)
• claude_paths - Array of paths to search for Claude Code logs
• cache_expiry - How long to cache LiteLLM pricing data (default: 1 hour)
• offline_mode - Use only cached pricing data without fetching from API

How It Works

1. Reads JSONL Files - Scans ~/.config/claude/projects/{project_name}/ for usage logs
2. Fetches Pricing - Gets current pricing from LiteLLM
3. Calculates Costs - Applies tiered pricing (200k+ tokens) and cache pricing
4. Displays Results - Shows usage in web UI, JSON API, or CLI

Data Location

Claude Code stores usage data at:

~/.config/claude/projects/{your-project-name}/{sessionId}.jsonl

The gem automatically detects your Rails app name and looks for matching Claude Code projects.

Troubleshooting: If no data is found, see TROUBLESHOOTING.md for detailed solutions.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Shoebtamboli/claude_usage. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the ClaudeUsage project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Acknowledgments

• Pricing data from LiteLLM
• Inspired by the need to track AI development costs

Support

If you find this gem useful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting new features
• 🤝 Contributing code

---

Made with ❤️ for Rails developers using Claude Code