clauchy

README

clauchy

A zero-config Go binary that turns your Claude Code usage data into a live Waybar icon and a full TUI dashboard.

---

Requirements: Omarchy or another Waybar/Hyprland environment, Claude Code logged in, and a Nerd Font patched terminal. Building from source additionally requires Go 1.26.4 or newer.

---

What it is

clauchy reads two sources of truth and brings them together in one place:

• The Anthropic usage API — the same server-side 5-hour session bar Claude Code itself uses. No approximation, no local reconstruction.
• Your local JSONL transcripts — per-day token counts, per-model breakdown, cost estimates, and your current streak, computed directly from ~/.claude/projects/.

The binary has three modes:

Mode	Command	What it does
Dashboard — monochrome (default)	clauchy	Bubbletea TUI, white/gray tones matching the reference design
Dashboard — colorful	clauchy --colorful	Same TUI with Sky-accented colors and severity-mapped bars
Waybar module	clauchy waybar	One JSON line on stdout; designed for return-type: json
Installer	clauchy install	Idempotently patches config.jsonc, style.css, writes icon SVGs, and appends Hyprland window rules
Installer — colorful	clauchy install --colorful	Same as above but the on-click launches the dashboard in colorful mode (clauchy --colorful); re-running with or without the flag repairs the on-click either direction

---

Install

go install github.com/jesusrobot0/clauchy@latest
clauchy install

Starting with the next release, static Linux binaries for amd64 and arm64 are attached to GitHub releases. Verify downloads with checksums.txt.

clauchy install makes the following changes (all idempotent — safe to run again after an upgrade):

1. Adds a custom/clauchy module block to ~/.config/waybar/config.jsonc with the correct exec, return-type: json, interval, and a floating-terminal on-click.
2. Registers "custom/clauchy" in your modules-right (or whichever modules-* array you use).
3. Appends a marked CSS block to ~/.config/waybar/style.css that paints the Claude SVG logo via background-image in each severity color. The Waybar module box emits a single space " " so the box exists without a glyph.
4. Writes one theme-adaptive claude-symbolic.svg to ~/.local/share/clauchy/. Severity colors are applied by CSS.
5. On Hyprland: appends a marked block of windowrule entries to ~/.config/hypr/hyprland.conf so the dashboard panel opens floating, centered, and sized correctly. If hyprland.conf does not exist the step is skipped with a warning (non-Hyprland setups work fine without it).

All modified files are backed up to timestamped .bak.<epoch> names before any write. Waybar is reloaded via SIGUSR2 and Hyprland via hyprctl reload automatically.

---

Why clauchy is different

Correct 1-hour cache-write pricing per Anthropic's published rates. Claude transcripts distinguish two cache-write buckets: 5-minute writes (1.25× base input rate) and 1-hour writes (2× base input rate). clauchy applies both multipliers to the correct token bucket, matching Anthropic's published pricing page. An optional ~/.config/clauchy/pricing.json override file lets you update rates for new models without rebuilding.

Authoritative server-side 5-hour bar. The 5-hour utilization value comes directly from Anthropic's OAuth usage API — the same number Claude Code's own rate-limit indicator uses. There is no local estimation or approximation.

Single static binary. clauchy compiles to one binary with no runtime dependencies. Install it, run clauchy install, and it works. No Node.js, no Python, no daemon.

---

Zero-config philosophy

clauchy discovers everything from your existing Claude Code setup:

• Credentials: ~/.claude/.credentials.json (or CLAUDE_CONFIG_DIR if set)
• Transcripts: ~/.claude/projects/ (or CLAUDE_CONFIG_DIR)
• Waybar config: ~/.config/waybar/config.jsonc and style.css

No configuration file is required. The only optional file is the pricing override. When an access token expires or is rejected, clauchy uses Claude Code's refresh token and atomically updates the shared credentials file. It never writes credentials to its cache or logs. Clauchy detects concurrent credential changes and adopts the newer token, but no third-party tool can make cross-process coordination absolute unless Claude Code participates in the same lock; a rejected concurrent refresh degrades to cached data or reauthentication.

---

Pricing override

To update or add model rates without rebuilding, create ~/.config/clauchy/pricing.json:

{
  "claude-new-model": { "input": 5.00, "output": 15.00 }
}

Rates are USD per million tokens. The file merges with the built-in table; any model you list overrides its built-in rate. Models not listed use the built-in rates.

---

Uninstall

Remove the generated blocks and local data, then delete the binary:

rm -rf ~/.cache/clauchy ~/.local/share/clauchy
rm "$(which clauchy)"

Also remove:

• The custom/clauchy object and array entry from Waybar config.jsonc.
• The /* clauchy start */ through /* clauchy end */ block from style.css.
• The # clauchy start through # clauchy end block from hyprland.conf.
• Any .bak.<epoch> backups after confirming the active configuration works.

clauchy writes to: ~/.cache/clauchy/ (ephemeral usage cache), the Waybar config files it patches during install, ~/.local/share/clauchy/ (SVG icons), and (on Hyprland) ~/.config/hypr/hyprland.conf. No files outside these locations are written.

---

Building from source

git clone https://github.com/jesusrobot0/clauchy
cd clauchy
CGO_ENABLED=0 go build -trimpath \
  -ldflags "-s -w -X main.version=$(git describe --tags --always)" \
  -o clauchy .

Documentation

Overview

clauchy — zero-config Claude Code usage monitor.

Usage:

clauchy              # open the TUI dashboard (monochrome, default)
clauchy --colorful   # open the TUI dashboard with Sky-accented colors
clauchy waybar       # emit one JSON line for a Waybar custom module
clauchy install      # add/repair the Waybar module config idempotently
clauchy --version    # print the build version and exit

The --colorful flag may appear anywhere before or after the mode word. Dashboard mode is the default when no mode word is provided.

The binary is intentionally thin: every domain concern lives in an internal package. main's only job is composition — wiring injected values (HTTP clients, paths, token func, clock) into the domain packages and dispatching to the correct entry point.

Clock seam re-sampling invariant (CRITICAL — §1): the TokenFunc closure and the FetchStats closure both re-sample time.Now() on EVERY call. A captured fixed time would freeze "today" on a long-running dashboard. This is a wiring invariant enforced here by code review, not a unit test.