Canary

Canary is being rewritten as a workspace with three coordinated products:

• canary: the local monitor and wrapped-agent launcher that serves the browser UI, watches repo changes, and starts attributed Codex or Claude sessions
• canaryctl: the local review CLI that writes typed review threads and file briefs directly into SQLite
• skills: agent instructions that teach Codex and Claude how to use canaryctl

Workspace

packages/
  canary/            monitor + wrapped agent launcher + React/Vite UI
  canaryctl/         review CLI
  canary-core/       schema, migrations, repositories, shared types
  canary-observers/  agent adapter definitions
skills/              canonical agent skill bundle

Stack

• pnpm workspaces
• TypeScript on Node.js 20+
• better-sqlite3 for per-user SQLite persistence
• React + Vite for the review UI
• commander for the CLIs

Project state lives under ~/.canary/projects/<project-hash>/canary.db.

Install

npm install -g @canaryctl/canary

To set up the agent skill:

canaryctl skill setup --codex
# or
canaryctl skill setup --claude-code

Development (from source)

corepack enable
pnpm install
pnpm build

To symlink local builds into your PATH:

pnpm install:local

This links canary and canaryctl into ~/.local/bin and installs the Canary skill into $CODEX_HOME/skills/canary.

Releasing a new version

Push a tag and the GitHub Actions workflow handles the rest:

git tag v0.x.0
git push origin v0.x.0

This automatically creates a GitHub release and publishes all packages to npm.