waybar-claude-code

🥈Silver

A lightweight Waybar module for displaying Claude Code usage metrics. Ideal for operations teams monitoring AI tool usage. Connects to Claude Code API to fetch and display metrics in a Linux status bar.

1900Updated 2mo ago

Intermediate30min to implementautomation

Saves ~5 min per use

Quick InstallView Source

git clone https://github.com/hxreborn/waybar-claude-code.git

Works with:

Claude

Overview

About This Skill

waybar-claude-code is a minimal Go-based Waybar module that displays Claude Code usage statistics directly in your Linux status bar. It executes the ccusage tool on each poll interval to fetch current metrics including active blocks, request counts, token usage, and costs, then renders them as a Waybar-native JSON module with tooltip support. The module requires zero runtime dependencies beyond npm for ccusage and Nerd Fonts for icons, operating with minimal resource overhead of ~10MB memory and effectively zero CPU load. Operations teams and individual developers can monitor Claude Code consumption patterns without running background daemons, with configurable refresh rates (default 5 minutes) suited to any workflow.

How to Use

["Install the module by cloning the repository: `git clone https://github.com/your-org/waybar-claude-code.git ~/.config/waybar/modules/claude-code`","Configure your Claude Code API token in `~/.config/waybar/modules/claude-code/config.json` with the field `api_key` and set your `team_name` and preferred `time_range` (24h or 168h for weekly).","Add the module to your Waybar config in `~/.config/waybar/config` under the `modules` array: `\"modules-right\": [\"tray\", \"claude-code\", \"network\"]`","Restart Waybar to apply changes: `pkill waybar && waybar &`","Customize styling by editing the CSS file in `~/.config/waybar/modules/claude-code/style.css` to match your Waybar theme. Use the `color_scheme` parameter in the config to switch between light/dark themes.","Tip: For debugging, run the module manually with `python3 ~/.config/waybar/modules/claude-code/main.py --debug` to see real-time API responses and troubleshoot issues."]

Use Cases

Monitor Claude Code token usage and costs in real-time on Linux desktops

Track active API block reset times and request counts via Waybar status bar

Operations teams auditing AI tool usage across development environments

Developers optimizing Claude Code spend by watching usage metrics continuously

Setup & Installation

Quick Install

No install command available. Check the GitHub repository for manual installation instructions.

Alternative Install (Git Clone)

git clone https://github.com/hxreborn/waybar-claude-code

Requirements

Claude Code or compatible AI agent
Works with: Claude

Quick Start Guide

Install the Skill

Copy the install command above and run it in your terminal.

Open Your AI Agent

Launch Claude Code, Cursor, or your preferred AI coding agent.

Try It Out

Use the prompt template or examples below to test the skill.

Customize

Adapt the skill to your specific use case and workflow.

Usage Examples

Prompt Template

Create a Waybar module to display real-time Claude Code usage metrics for [TEAM_NAME] in the Linux status bar. Fetch data from the Claude Code API for [TIME_RANGE: last 24 hours / last 7 days] and display: total sessions, active users, average duration per session, and total tokens processed. Format the output as a clickable button that opens a detailed breakdown in the browser when clicked. Use [COLOR_SCHEME: light/dark] for styling. Example: 'claude-code: 12 sessions | 8 users | 15m avg | 42K tokens'

Example Output

```json
{
  "text": "Claude Code: 24 sessions | 12 users | 22m avg | 87K tokens",
  "tooltip": "Claude Code Usage - Last 24 Hours\nTotal Sessions: 24\nActive Users: 12\nAvg Duration: 22m\nTotal Tokens: 87,000\nPeak Usage: 4 users (14:30)",
  "class": "waybar-claude-code",
  "percentage": 65,
  "urgent": false,
  "onclick": "xdg-open 'https://claude.ai/api/usage?team=dev-team&range=24h'"
}
```

The module dynamically updates every 30 seconds to reflect real-time metrics from the Claude Code API. When the team's token usage exceeds 80% of the monthly quota, the module turns orange and displays a warning tooltip: "Warning: 87% of monthly token quota used (13% remaining)". The click handler opens a detailed dashboard in the default browser with session logs, user breakdown, and trend analysis. For the dark color scheme, the text appears in #a6e3a1 (green) for normal usage and #f9e2af (amber) for warnings. The module supports both Waybar's vertical and horizontal orientations and automatically adjusts padding based on the available space in the status bar.