Codo

Codo

macOS menubar daemon + CLI for displaying system toast notifications. Designed as a notification bridge for Claude Code hooks and other AI agent workflows.

# Simple notification
codo "Build Done" "All 42 tests passed"

# With template (sets subtitle + sound automatically)
codo "Build Done" "42 tests passed" --template success
codo "Build Failed" "3 errors" --template error
codo "Deploying..." --template progress

# Group related notifications
codo "Step 1/3" --template progress --thread deploy-v1.2
codo "Step 2/3" --template progress --thread deploy-v1.2
codo "Deploy Done" --template success --thread deploy-v1.2

# Via stdin JSON
echo '{"title":"Build Done","body":"All tests passed","subtitle":"✅ Success"}' | codo

# List available templates
codo --template list

Architecture

Two layers: **Swift menubar app** (daemon, listens on Unix Domain Socket, shows toast) + **TypeScript CLI** (Bun script, sends messages to daemon).

Claude Code hook → codo CLI (Bun) → UDS → Codo.app (Swift) → macOS notification

Development

Prerequisites

• macOS 14+ (Sonoma)
• Swift 5.10+ (swift --version)
• Bun (bun --version) — CLI runtime and TS test runner
• SwiftLint (brew install swiftlint)

Setup

# Install dependencies and git hooks
bun install

This runs `husky` via the `prepare` script, which sets up `.husky/` as the git hooks directory.

Git Hooks

Hook	Stage	What runs
pre-commit	L1+L2	swift test + bun test + SwiftLint strict + Biome lint
pre-push	L1+L2+L3	Unit tests + lint + integration tests

Hooks **cannot be skipped** — this is by design. Every commit must pass unit tests and lint.

Running Tests Manually

# L1: Swift unit tests (46 tests)
swift test

# L1: TypeScript unit tests (60 tests)
cd cli && bun test

# L2: Swift lint
swiftlint lint --strict --quiet

# L2: TypeScript lint
cd cli && bunx biome check .

# L3: Integ