# Kannu

> Shows a traffic light in the notch while AI agents run in your editor: green while the agent
> is working, yellow when it needs your input, and red when it has stopped. Free and open source.

Watch Your Agents. Kannu tracks Claude Code, Cursor, Codex, VS Code (Copilot) and Google
Antigravity. Green means Active — the agent is thinking, planning, executing tools, or otherwise
working. Yellow means Awaiting Input — the agent needs your approval or a response. Red means
Stopped — the agent has finished or was aborted.

The notch shows exactly one light, aggregated across every running session; the panel underneath
lists each session with its own state. The light appears on change: when an agent changes state
the island pulls itself into view, holds for about seven seconds, and collapses — heartbeats
deliberately don't re-open it. Hovering holds it open. Unlike menu bar agent monitors, Kannu
lives in the notch — space already in your eyeline — and opens into full panels there.

## How it detects agent state

Kannu registers hooks in each tool that exposes them rather than polling. The events are
`PermissionRequest`, `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop` and `UserPromptSubmit`,
installed into `~/.claude/settings.json`, `~/.codex/hooks.json`, `~/.cursor/hooks.json` and
Copilot's hooks folder. Each hook runs a small script that writes a status file Kannu watches.
It never reads your code. Concurrent hook writes cannot silently overwrite a yellow "needs you"
with a green "running" — 11 of 200 parallel rounds lost the urgent state before the fix, 0 of
200 after.

It also carries the everyday notch utilities, and these work whether or not you use an AI coding
agent — agent status is one panel among several, not a prerequisite:

- Agent stats: for Claude, labelled rate-limit bars in two groups — Session with its own reset
  countdown, and Weekly with a shared countdown over an All models bar plus each individually
  reported model. Bar colour is the severity the server itself reports; a refresh button fetches
  the latest figures on demand. Codex and Cursor have their own usage cards. Google Antigravity
  has no public token or cost API, so its card shows session activity only.
- Smart caffeinate: the Mac stays awake automatically while any agent runs and sleeps normally
  once they stop, or use the manual switch. One native macOS power assertion, never a
  `caffeinate` subprocess. Only system sleep is prevented — the display may still sleep, and
  closing the lid always sleeps the Mac.
- Light customization: Classic (all three lights, inactive dimmed) or Minimal (only the lit one)
  styles, per-state colours from a curated ten-hue palette — two states can never share a
  colour, keeping the lights readable with red-green colour blindness — and the indicator is
  announced to VoiceOver with a spoken state. A toggle controls whether red shows when idle.
- Recent agent chats: every session across all supported tools in one list with its live state;
  click a row and the app that owns it comes to the front.
- A Pomodoro focus timer in the notch — Focus 25, Break 5, Deep Work 45 — with a colour-draining ring.
- Music controls for the current track without leaving the window you are in.
- A file shelf for moving files between apps, spaces and screens, sharing via AirDrop, LocalSend
  and Quick Share.
- Weather: temperature, feels-like and humidity for your location.
- Custom accent colour applied throughout, a tint for the notch itself, and user-supplied notch skins.

## Facts

- Platform: macOS 14.0 or later, optimised for macOS 15+. A notch is not required — it also runs
  as a floating Dynamic Island-style panel on any Mac and on external displays.
- Universal build: Apple Silicon and Intel.
- Price: free. Licensed under the GPL-3.0. No paywall, no license key, no in-app purchases.
- Distribution: a DMG from GitHub Releases. Not on Homebrew or the Mac App Store.
- Privacy: credentials are read-only — Kannu never refreshes your rotating token — Keychain
  access sits behind an explicit one-time approval, and it backs off when rate-limited. Beyond
  fetching your own usage figures from your own providers, and outbound notifications only if
  you enable them, everything stays on the Mac: no telemetry, no analytics, no backend.
- Signed and notarized by Apple; it opens normally on first launch.
- The name is Malayalam: കണ്ണ്, meaning "eye."
- Forked from Atoll and Boring Notch, then substantially rewritten around agent status.

## Links

- Homepage: https://kannu.app/
- How it detects agent state: https://kannu.app/how-it-works/
- Vs menu bar agent monitors: https://kannu.app/vs-menu-bar-apps/
- Changelog: https://kannu.app/changelog/
- Source: https://github.com/libinmv/kannu
- Download: https://github.com/libinmv/kannu/releases/latest
- Privacy policy: https://kannu.app/legal/privacy-policy/
- Full content: https://kannu.app/llms-full.txt