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.

✅ 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

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.

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

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

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

Access usage data programmatically:

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

# 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

# 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(', ')}"

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

• 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

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

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.

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.

We welcome contributions! Here's how you can help:

Found a bug? Please create an issue using our Bug Report template.

Before reporting:

• Check existing issues
• Review TROUBLESHOOTING.md for common solutions
• Run rake claude_usage:show_project to verify your setup

Have an idea? Submit a feature request using our Feature Request template.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run tests: bundle exec rspec
5. Run linter: bundle exec rubocop
6. Commit your changes
7. Push to your fork and submit a Pull Request

See CONTRIBUTING.md for detailed guidelines.

This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

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

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

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

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