cc-focus: Instructions file for Claude Code

cc-focus

macOS menu bar status indicator for Claude Code sessions. Single-file Swift/AppKit app.

Architecture

Claude Code hooks (JSON on stdin)
  → cc-focus-hook.sh <event_type>     # injects event_type, sends to socket
    → nc -U /tmp/cc-focus-$(id -u).sock
      → cc-focus.swift                # NSStatusItem menu bar app

All logic is in cc-focus.swift (~350 lines). No external dependencies, no packages.

Files

• cc-focus.swift - The entire app: socket listener, state machine, menu bar UI
• cc-focus-hook.sh - Shell hook that reads Claude Code JSON from stdin, injects event_type via python3, sends to Unix socket
• cc-focus-cli - CLI wrapper: cc-focus-cli setup / cc-focus-cli teardown for hook management
• Info.plist - App bundle config (LSUIElement=true for no dock icon)
• build.sh - Compiles Swift and creates .app bundle
• install.sh - Builds, cleans up legacy installs, sets up hooks
• install-hooks.sh - Merges hook entries into ~/.claude/settings.json (preserves existing hooks)
• uninstall-hooks.sh - Removes cc-focus hooks from ~/.claude/settings.json
• uninstall.sh - Stops service, cleans up legacy installs, removes socket/hooks

Build & Test

bash build.sh                    # compile
bash install.sh                  # build + hooks (cleans up legacy installs)
bash uninstall.sh                # full removal
brew services restart cc-focus   # start/restart via Homebrew
brew services stop cc-focus      # stop

Manual test events:

echo '{"event_type":"session_start","session_id":"test1","cwd":"/tmp"}' | nc -U /tmp/cc-focus-$(id -u).sock
echo '{"event_type":"stop","session_id":"test1","cwd":"/tmp"}' | nc -U /tmp/cc-focus-$(id -u).sock
echo '{"event_type":"session_end","session_id":"test1"}' | nc -U /tmp/cc-focus-$(id -u).sock

Key Design Decisions

• Stop hook for idle: The Stop hook (fires when Claude finishes its turn) maps to the idle (gray) state. The PermissionRequest hook and idle_prompt/permission_prompt Notification hooks map to needsInput (red). PermissionRequest fires promptly when the permission dialog appears; the Notification/permission_prompt hook fires with a delay and serves as a backup.
• Notification events lack session_id: Notification hook events (permission_prompt, idle_prompt) don't include session_id. The app falls back to extracting it from transcript_path.
• Resume creates orphan sessions: When continuing a session, Claude fires two session_start events: a "startup" wrapper and a "resume". Only the resumed session gets a session_end. The app cleans up the orphaned wrapper when it sees a resume event.
• isTemplate = false: The status item image must not be a template, otherwise macOS recolors the circle to match the menu bar theme.
• Compile with -swift-version 5: Avoids Swift 6 strict concurrency requirements.
• Debug logging: cc-focus-hook.sh writes to /tmp/cc-focus-debug.log. Remove once stable.