Code Light AI
A system tray status light for Claude Code、Codex — monitor your AI coding agent without keeping the terminal visible.
Install
git clone https://github.com/cuihp/code-light-aiInstall command taken from the project's README or registry entry. Always review code before running it.
README excerpt
Read full README on GitHub →Code Light AI
A system tray status light for AI coding agents, with a desktop pet companion.
It shows a colored indicator in your system tray so you can tell at a glance what your AI agent is doing — without keeping the terminal visible. Plus, an adorable pixel cat pet that reacts to your agent's status!
Currently supports Claude Code and OpenAI Codex CLI.
Status Indicators
| Color | State | Description |
|---|---|---|
| Gray | Idle | No active sessions |
| Green (blinking) | Working | Agent is executing tool calls |
| Yellow (blinking) | Waiting | Agent is waiting for user confirmation |
| Red (blinking) | Error | An error has occurred |
| Blue | Completed | Task finished (displays for 10 seconds, then returns to idle) |
Active states blink every 500ms to catch your attention. The tray tooltip shows the current state, active session count, and last update time.
Desktop Pet 🐱
Code Light now includes a pixel art desktop pet that reacts to your AI agent's status! The cat companion sits on your desktop and animates based on what your agent is doing.
| State | Animation |
|---|---|
| Idle | Relaxed, sitting calmly |
| Working | Energetic, typing away |
| Waiting | Alert, looking around |
| Error | Startled, ears back |
| Completed | Happy, celebrating |
Toggle the pet: Right-click the tray icon and select "Show Pet" or "Hide Pet" to control visibility.
The pet window is always on top and draggable, so you can position it anywhere on your screen.
How It Works
Code Light uses a file-based polling mechanism:
- Shell hooks are registered as lifecycle hooks for Claude Code (
~/.claude/settings.json) and Codex (~/.codex/hooks.json) - Each hook writes a JSON state file to
~/.code-light/sessions/<session-id>.json - The tray app polls these files every second and updates the icon
Agent event → Hook script → ~/.code-light/sessions/*.json → Tray icon
Zero network ports, zero APIs, zero configuration — just files on disk.
Install
Prerequisites
- macOS 12+ / Linux / Windows 10+
- Claude Code CLI and/or Codex CLI installed
- Node.js 18+ and pnpm
- Rust toolchain
- Windows users need Git for Windows (provides bash)
Build from source
git clone https://github.com/cuihuapeng/code-light-ai.git
cd code-light-ai
pnpm install
pnpm tauri build
Built artifacts:
| Platform | Location |
|---|---|
| macOS | src-tauri/target/release/bundle/macos/Code Light.app |
| Linux | src-tauri/target/release/bundle/deb/code-light_*.deb |
| Windows | src-tauri/target/release/bundle/nsis/code-light_*.exe |
Usage
- Launch Code Light — a gray dot appears in your system tray
- Right-click the icon and select "Setup Claude Hooks" to register hooks for Claude Code, or "Setup Codex Hooks" for Codex CLI
- Start your AI agent in the terminal — the tray icon changes color as the agent works
That's it. On macOS the app runs as a pure menu bar accessory with no dock icon.
Note for Codex users: After setting up Codex hooks, run
/hooksin the Codex CLI and presstto trust all hooks before they can take effect.
macOS: "App is damaged" or "cannot be opened" error
Similar plugs
CLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies
Bash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1
Documented system prompts from Anthropic - Claude Fable 5.1, Opus 5.5, Claude Design, Claude Code. OpenAI - ChatGPT GPT-6-Astra, Codex. Google - Gemini 3.8 Flash, 3.1 Pro,…
Wrap Antigravity, ChatGPT Codex, Claude Code, Grok Build, Muse Code, Devin as an OpenAI/Gemini/Claude/Codex compatible API service, allowing you to enjoy the free Gemini…