Code Light AI

A system tray status light for AI coding agents.

中文文档

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.

Currently supports Claude Code and OpenAI Codex CLI.

Status Indicators

Active states blink every 500ms to catch your attention. The tray tooltip shows the current state, active session count, and last update time.

How It Works

Code Light uses a file-based polling mechanism:

1. Shell hooks are registered as lifecycle hooks for Claude Code (~/.claude/settings.json) and Codex (~/.codex/hooks.json)
2. Each hook writes a JSON state file to ~/.code-light/sessions/<session-id>.json
3. 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:

Usage

1. Launch Code Light — a gray dot appears in your system tray
2. Right-click the icon and select "Setup Claude Hooks" to register hooks for Claude Code, or "Setup Codex Hooks" for Codex CLI
3. 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 /hooks in the Codex CLI and press t to trust all hooks before they can take effect.

macOS: "App is damaged" or "cannot be opened" error

If you build from source or download an unsigned build, macOS may block the app. To fix this:

xattr -cr /path/to/Code\ Light.app

Then open it by right-clicking the app and selecting Open → Open again in the dialog. You only need to do this once.

Multi-session support

If you run multiple sessions (Claude Code and/or Codex) in different terminals, Code Light tracks all of them simultaneously. The icon reflects the highest-priority state across all active sessions (Error > Waiting > Working > Completed > Idle).

Automatic cleanup

• Sessions with no activity for 5 minutes are automatically removed
• Sessions stuck in "waiting" for 30+ seconds are promoted to "working"
• Sessions stuck in "working" for 60+ seconds are auto-completed
• Completed sessions are cleaned up after the 10-second display window

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm tauri dev

# Build for production
pnpm tauri build

# Lint Rust code
cd src-tauri && cargo clippy

Project Structure

code-light/
├── hooks/
│   ├── claude/                      # Claude Code hook scripts
│   │   ├── _helpers.sh              # Shared helpers (session ID from env, atomic write)
│   │   ├── pre-tool-use.sh          # → working
│   │   ├── post-tool-use.sh         # Placeholder
│   │   ├── post-tool-use-failure.sh # → error
│   │   ├── notification.sh          # → waiting (on permission prompts)
│   │   └── stop.sh                  # → completed
│   └── codex/                       # Codex CLI hook scripts
│       ├── _helpers.sh              # Shared helpers (session ID from stdin JSON)
│       ├── session_start.sh         # → working
│       ├── pre_tool_use.sh          # → working
│       ├── permission_request.sh    # → waiting
│       ├── post_tool_use.sh         # → working
│       ├── user_prompt_submit.sh    # → working
│       └── stop.sh                  # → completed
├── src-tauri/                       # Tauri v2 / Rust backend
│   ├── src/
│   │   ├── main.rs                  # Entry point
│   │   └── lib.rs                   # Tray icon, polling, blink, hook setup
│   ├── icons/status/                # Status indicator PNGs (gray, green, yellow, red, blue)
│   └── tauri.conf.json              # Tauri configuration
├── src/                             # Frontend (vestigial — no visible window)
├── package.json
└── vite.config.ts

Supported Agents & Events

Tech Stack

• Backend: Tauri v2 + Rust
• Frontend: Vite + TypeScript (minimal — the app has no visible window)
• Hooks: Bash scripts registered as lifecycle hooks

License

MIT