Notchi – a macOS “notch” companion for Claude Code & Codex

What it is – A small macOS application that lives in the screen notch of a MacBook Pro and shows animated mascots that react in real‑time to events coming from Anthropic’s Claude Code and OpenAI’s Codex. It also optionally analyses the sentiment of the prompts you send to those models and displays an emotional reaction.

---

Core functionality (as described in the README)

Feature	What you get
Live event reaction	The app registers shell‑script hooks with Claude Code or Codex. When the model emits events (thinking, tool use, permission requests, errors, completions, etc.) the hook sends a JSON payload over a Unix socket. Notchi parses the payload and animates a mascot accordingly.
Sentiment‑driven emotions	If you paste an Anthropic or OpenAI API key in Settings, Notchi calls the respective API to analyse the sentiment of each prompt and shows the mascot as happy, sad, elated, neutral or “sob”.
Usage tracking	A bar at the bottom shows daily token usage and estimated cost for the last 30 days, per provider or combined. Clicking it expands a dashboard with session time, quota bars and cost charts.
Multiple concurrent sessions	Each active Claude or Codex session gets its own sprite (chosen from the Claude/Codex sprite families) on a small “grass island” that appears when you click the notch.
Custom sound effects	Built‑in sounds for each event; you can import your own. Sounds are auto‑muted when a terminal window has focus.
Localization	UI follows the system language and is available in English, Japanese, Simplified/Traditional Chinese, Korean and Vietnamese.
Auto‑updates	Uses the Sparkle framework to deliver signed, notarized updates.
Cross‑platform community ports	Links to community‑maintained Windows ports (notchi‑for‑windows, pixel‑companion).

---

Installation steps (from the README)

1. Download the latest DMG from the releases page (e.g., Notchi‑1.2.7.dmg).
2. Open the DMG and drag Notchi into the Applications folder.
3. Launch the app – on first run it installs the Claude Code and/or Codex hooks automatically.
4. If macOS asks for Keychain access (used to store API usage stats), click Always Allow.
5. (Optional) Open Settings → paste your Anthropic or OpenAI API key to enable sentiment analysis.
6. Use Claude Code or Codex as usual; the mascot will start reacting.
7. Click the usage bar to view the cost/usage dashboard.

---

How it works internally (high‑level flow from the README)

Claude Code / Codex  →  Hook scripts (shell)  →  Unix socket  →
Event parser  →  State machine  →  Animated sprites

• The hook scripts are installed by Notchi and listen for JSON events emitted by the AI agents.
• Events travel over a local Unix socket to the Notchi process.
• The app parses the JSON, updates a finite‑state machine that maps events to animation states (idle, working, sleeping, compacting, waiting, etc.).
• If an API key is present, the prompt text is sent to Anthropic or OpenAI for sentiment analysis; the result influences the mascot’s facial expression.
• The UI draws the appropriate sprite on the notch area and updates the usage panel.

---

Requirements & compatibility

• macOS 15.0+ (Sequoia) – the app relies on the notch UI introduced in this version.
• MacBook with a physical notch – the mascot lives in that space.
• Claude Code and/or OpenAI Codex must be installed on the machine for the hooks to attach.

---

Contributing & support

• Contributions are welcomed via pull requests; see CONTRIBUTING.md for guidelines.
• The project is GPL‑3.0‑only.
• Development can be sponsored through GitHub Sponsors (covers the Apple Developer account needed for signed builds).

---

Quick take‑away

Notchi is a niche but fully functional macOS companion that visualises the inner workings of Claude Code and Codex in a playful way, while also giving developers a live view of token usage and optional sentiment feedback. It is a genuine software project focused on AI‑agent interaction, not just a tutorial or list.