claude-code-stats: Instructions file for Claude Code

CLAUDE.md

Project Overview

ClaudeCodeStats is a native macOS menu bar app (SwiftUI) that shows Claude Code usage limits, Claude service health status, and CLI version update notifications.

Build

cd ClaudeCodeStats
xcodebuild -scheme ClaudeCodeStats -configuration Release build

The built .app is in ~/Library/Developer/Xcode/DerivedData/ClaudeCodeStats-<hash>/Build/Products/Release/.

Resolve that path explicitly — never with a ClaudeCodeStats-* glob. Xcode keeps a separate DerivedData directory per project location, and stale ones are not cleaned up. When more than one exists the glob expands to all of them, so cp -R src1 src2 /Applications/ copies the fresh build and then overwrites it with the stale one, exit 0 and no warning — you end up debugging a binary that is weeks old. ls -dt does not save you either: it sorts by directory mtime, which a previous cp will have touched. The last line xcodebuild prints (lsregister -f -R -trusted <path>) names the directory it actually built into.

To install locally:

# Take the path from xcodebuild's own output, or pick by the *binary's* mtime:
APP=$(ls -dt ~/Library/Developer/Xcode/DerivedData/ClaudeCodeStats-*/Build/Products/Release/ClaudeCodeStats.app/Contents/MacOS/ClaudeCodeStats \
      | head -1 | sed 's#/Contents/MacOS/ClaudeCodeStats##')
echo "installing from: $APP"   # sanity-check this before continuing

# Kill running instance, copy to /Applications, relaunch
pkill -x ClaudeCodeStats; sleep 0.5
rm -rf /Applications/ClaudeCodeStats.app
cp -R "$APP" /Applications/ClaudeCodeStats.app
open /Applications/ClaudeCodeStats.app

If a change you just made doesn't show up, check this first: a rendered colour or string that exists nowhere in the source tree means you are not running the tree.

There are no tests or linters configured, so verifying a change means running the app and looking at it. Three non-obvious traps when doing that from a shell:

• Launch with open, never &. A .app started as "$BINARY" & from a Bash tool dies when that shell returns, often mid-work — open /Applications/ClaudeCodeStats.app hands it to LaunchServices so it survives. To time a scan or wait on a side effect, poll the artifact (until [ -f "$cost_cache" ]; do sleep 2; done), don't hold the process open.
• Instrument to a file, not stderr. A menu bar app has no attached terminal, and one you'll pkill loses buffered stdout/stderr — write debug lines to a file (/tmp/…) and cat it after.
• AppleScript can't open the MenuBarExtra popover (click menu bar item … does nothing). To inspect a view in a specific state or appearance without the running app, compile the real views into a standalone ImageRenderer harness and render at a chosen \.colorScheme + sample data (swiftc main.swift Theme.swift Models.swift Views/*.swift — top-level code needs the file named main.swift). It renders everything except ScrollView content, which comes back blank.