A macOS notch companion that reacts to Claude Code activity in real-time.

• Reacts to Claude Code events in real-time (thinking, working, errors, completions)
• Analyzes conversation sentiment to show emotions (happy, sad, neutral, sob)
• Click to expand and see session time and usage quota
• Supports multiple concurrent Claude Code sessions with individual sprites
• Sound effects for events (optional, auto-muted when terminal is focused)
• Auto-updates via Sparkle

• macOS 15.0+ (Sequoia)
• MacBook with notch
• Claude Code installed

1. Download Notchi-x.x.x.dmg from the latest GitHub Release

2. Open the DMG and drag Notchi to Applications

3. Launch Notchi — it auto-installs Claude Code hooks on first launch

4. A macOS keychain popup will appear asking to access Claude Code's cached OAuth token (used for API usage stats). Click Always Allow so it won't prompt again on future launches

   

5. (Optional) Click the notch to expand → open Settings → paste your Anthropic API key. This enables sentiment analysis of your prompts so the mascot reacts emotionally

   

6. Start using Claude Code and watch Notchi react

Claude Code --> Hooks (shell scripts) --> Unix Socket --> Event Parser --> State Machine --> Animated Sprites

Notchi registers shell script hooks with Claude Code on launch. When Claude Code emits events (tool use, thinking, prompts, session start/end), the hook script sends JSON payloads to a Unix socket. The app parses these events, runs them through a state machine that maps to sprite animations (idle, working, sleeping, compacting, waiting), and uses the Anthropic API to analyze user prompt sentiment for emotional reactions.

Each Claude Code session gets its own sprite on the grass island. Clicking expands the notch panel to show a live activity feed, session info, and API usage stats.

If you have any bugs, ideas, or would like to contribute through pull requests, please check out Contributing to Notchi.

• Claude Island — design inspiration for the app
• Readout — design inspiration for notchi.app
• Aseprite — sprite design

MIT