🎨 Community Formatters

[S1M0N38]

🎨 Community Formatters

Hello ccusage.nvim community! 👋

We'd love to see the community contribute new formatter options to make ccusage display even more customizable and useful. Currently, we have two built-in formatters:

• default.lua: Compact "time 75% | tok 45%" format with color coding
• verbose.lua: Detailed statistics for the :CCUsage command

🎯 What We're Looking For

New formatter files in lua/ccusage/formatters/ that follow our formatter specification. Each formatter should:

📋 Requirements

1. Function Signature: Return a function that takes a CCUsage.FormatterContext parameter
2. Return Value: String for display or nil to hide the component
3. Error Handling: Gracefully handle missing or invalid data
4. Documentation: Include clear annotations and comments

📊 Available Data

Your formatter receives a context object with:

context = {
  data = {
    blocks = {
      -- Array of usage blocks with:
      -- id, startTime, endTime, isActive, tokenCounts, costUSD, models, etc.
    }
  },
  stats = {
    max_tokens = 200000,      -- Token limit for session
    tokens = 89500,           -- Current token usage
    usage_ratio = 0.45,       -- Usage as ratio (0.0-1.0+)
    time_ratio = 0.75,        -- Time progress ratio (0.0-1.0)
    start_time = 1706123400,  -- Session start (unix timestamp)
    end_time = 1706141400,    -- Session end (unix timestamp)
    cost = 0.1250            -- Cost in USD
  }
}

💡 Formatter Ideas

Here are some ideas to get you started:

• Minimal: Just token percentage "45%"
• Cost-focused: Emphasize spending "$0.12 (45%)"
• Time-aware: Show time remaining "2h15m left | 45%"
• Status-bar: Different symbols/colors for usage levels
• Compact: Single emoji + percentage "🔥 85%"
• Multi-line: Detailed breakdown for wider statuslines
• Threshold-based: Only show when approaching limits
• Model-aware: Show which models are being used

🏗️ Formatter Template

---@param context CCUsage.FormatterContext formatter context with data and stats
---@return string? formatted display string or nil to hide component
return function(context)
  -- Always check for valid data
  if not context or not context.stats then
    return nil
  end
  
  local stats = context.stats
  
  -- Your custom formatting logic here
  -- Example: return string.format("Custom: %.0f%%", stats.usage_ratio * 100)
  
  -- Optional: Add color coding
  -- if stats.usage_ratio > 1.0 then
  --   return string.format("%%#DiagnosticError#%s%%*", display_text)
  -- elseif stats.usage_ratio >= 0.8 then
  --   return string.format("%%#DiagnosticWarn#%s%%*", display_text)
  -- else
  --   return display_text
  -- end
end

🔍 Study the Examples

Check out our existing formatters for inspiration:

• lua/ccusage/formatters/default.lua
• lua/ccusage/formatters/verbose.lua

🚀 How to Contribute

1. Fork this repository
2. Create a new file in lua/ccusage/formatters/[your-formatter-name].lua
3. Follow the formatter specification above
4. Test your formatter (see testing instructions in CLAUDE.md)
5. Submit a pull request with a clear description

🧪 Testing Your Formatter

# Test with busted
busted spec/

# Test in Neovim
nvim -u repro/repro.lua

# In Neovim, test your formatter:
:lua require("ccusage").setup({ formatter = require("ccusage.formatters.your-formatter") })

📚 Resources

• Plugin Documentation: :help ccusage
• Type Definitions: lua/ccusage/types.lua
• Testing Guide: CLAUDE.md
• ccusage CLI: ryoppippi/ccusage

🎉 Recognition

Contributors will be:

• Credited in the changelog and documentation
• Featured in the README as community formatters
• Mentioned in release notes

Let's make ccusage.nvim more versatile together! Looking forward to seeing your creative formatter contributions. 🚀