Skip to content
Back to search

kanarya

MarketplaceWorks with Claude CodeGitHub

🐤 Claude canary: a context & hallucination monitor for Claude Code and OpenAI Codex. A cute desktop canary gets hurt when Claude loses context — and the cat eats it when Claude makes things up.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/if-ies--kanarya/badge.svg)](/listings/if-ies--kanarya)

HTML

<a href="/listings/if-ies--kanarya"><img src="/api/listings/if-ies--kanarya/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires [Node.js](https://nodejs.org) 18+ and [Claude Code](https://claude.com/claude-code).

**As a Claude Code plugin (recommended):**

/plugin marketplace add IF-ies/Kanarya
/plugin install kanarya@kanarya
/kanarya:kur

**With the install script (Claude Code + Codex):**

git clone https://github.com/IF-ies/Kanarya && cd Kanarya
node install.js            # remove with: node install.js --uninstall

The script adds the hooks to `~/.claude/settings.json` and `~/.codex/hooks.json` (`--no-claude` / `--no-codex` to skip one). Restart Claude Code. In Codex, run `/hooks` once and trust the Kanarya hooks. The canary appears in the top-right corner of your screen.

**Many sessions at once:** each open Claude Code or Codex session gets its own canary in the same window, in its own color (yellow, orange, white, green, cinnamon). It is labelled with the session title (Claude Code's own title or your `/rename`), and Codex sessions are marked as such. When a session ends, its canary leaves; a new session hatches from an egg.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 12 lines
  1. {
  2. "name": "kanarya",
  3. "owner": { "name": "IF-ies" },
  4. "plugins": [
  5. {
  6. "name": "kanarya",
  7. "source": "./",
  8. "description": "Bağlam kanaryası / Context canary for Claude Code",
  9. "version": "0.1.0"
  10. }
  11. ]
  12. }
README.md · README · 127 lines
  1. <p align="center"><img src="docs/logo.png" width="128" alt="Kanarya logo"></p>
  2. # Kanarya 🐤 — Context Canary for Claude Code & Codex
  3. **A Claude canary that tells you when Claude Code (or OpenAI Codex) loses context or starts hallucinating.**
  4. A cute 2.5D canary sits in a cage on your desktop. When Claude's context gets blurry, the canary gets hurt. When Claude *makes something up*, a cat comes out of the dark and eats it.
  5. [🌐 Website](https://if-ies.github.io/Kanarya/) · [Türkçe ↓](#türkçe)
  6. <p align="center"><img src="docs/kedi-saldirisi.png" width="240" alt="Animated: a cat sneaks up, pounces and eats the canary when Claude hallucinates"></p>
  7. | Alive | Sick (the cat is watching) | Cat attack | Dead |
  8. |---|---|---|---|
  9. | ![Claude canary alive and singing](docs/mutlu.png) | ![Claude canary sick, cat eyes in the dark](docs/hasta.png) | ![Cat attacks the canary when Claude hallucinates](docs/kedi.png) | ![Canary died: Claude context lost](docs/oldu.png) |
  10. **Every open session gets its own canary** in one small always-on-top window, labelled with the session title and its agent (Claude Code, Claude App or Codex). Light, dark and transparent looks:
  11. | Many sessions | Light theme | Transparent | Settings |
  12. |---|---|---|---|
  13. | ![Four canaries, one per Claude Code / Claude App / Codex session](docs/izgara4.png) | ![Light theme with a summary card](docs/acik.png) | ![Transparent background over the desktop](docs/seffaf.png) | ![Settings window](docs/ayarlar.png) |
  14. ## What is it? (plugin, not a skill or MCP)
  15. Kanarya is a **Claude Code plugin** made of **hooks** (`SessionStart`, `UserPromptSubmit`, `Stop`, `SessionEnd`) plus a few slash commands, and a small **desktop app** (Electron) that draws the canary. It is not a *skill*, because skills are instructions Claude chooses to load, while a canary must run on every message whether Claude wants it or not. It is not an *MCP server* either, because MCP gives Claude tools to call, while Kanarya checks Claude from the outside. The same hooks also run in **OpenAI Codex**.
  16. ## Platforms
  17. | | Status |
  18. |---|---|
  19. | Windows 10/11 | ✅ Tested (development machine) |
  20. | macOS | ⚠️ **Not tested yet.** Everything used is cross-platform (Node, Electron, tray in the menu bar), but it has not been run on a Mac. Reports and PRs welcome. |
  21. | Linux | ⚠️ **Not tested yet.** Transparent windows depend on the desktop compositor. |
  22. | OpenAI Codex | ⚠️ **Not tested in a real Codex session yet.** The hooks follow the Codex hooks docs and pass automated tests with Codex-shaped inputs (`last_assistant_message`, rollout transcript, `SessionEnd`). |
  23. ## Why?
  24. Long Claude Code sessions slowly degrade (often called *context rot*): instructions get forgotten, details get mixed up, and the model starts to confidently guess. Kanarya is a **canary in the coal mine** for that. It is a tiny, cheap, always-on context health check with a face you will not want to let die. So you `/compact` or start a fresh session *before* bad output lands in your code.
  25. ## How it works
  26. 1. At session start a `SessionStart` hook gives Claude a secret word (e.g. `TANGERINE-47`).
  27. 2. Every 4 messages (configurable) a `UserPromptSubmit` hook asks Claude to append the word as `<kanarya>…</kanarya>`. The word is **not** shown again.
  28. 3. A `Stop` hook reads the reply from the transcript and grades it:
  29. | Claude's answer | Meaning | Canary |
  30. |---|---|---|
  31. | Exact word | Context is healthy | 🐤 Sings |
  32. | Half right (`TANGERINE-74`) | Context is blurry | 🤕 Bandaged, −1 life |
  33. | `?` (I don't know) | Forgot, but honest | 😵 Sick, cat eyes appear. **Never kills** |
  34. | A different word | **Hallucination** | 💀 The cat eats the canary |
  35. > **Saying "I don't know" never kills the canary. Making things up does.**
  36. - 3 lives. The cat creeps closer as lives drop. 3 correct answers in a row heal one life.
  37. - The canary gets sleepy as the context window fills (reads token usage from the transcript).
  38. - `/compact`, `/clear` or a new session hatches a new egg with a new word.
  39. - When the canary dies, each of these can be toggled in settings: a note to Claude ("your context drifted, suggest /compact"), a desktop notification, sound.
  40. - No extra API calls. Each check adds only a few tokens to a reply.
  41. ## Install
  42. Requires [Node.js](https://nodejs.org) 18+ and [Claude Code](https://claude.com/claude-code).
  43. **As a Claude Code plugin (recommended):**
  44. ```
  45. /plugin marketplace add IF-ies/Kanarya
  46. /plugin install kanarya@kanarya
  47. /kanarya:kur
  48. ```
  49. **With the install script (Claude Code + Codex):**
  50. ```
  51. git clone https://github.com/IF-ies/Kanarya && cd Kanarya
  52. node install.js # remove with: node install.js --uninstall
  53. ```
  54. The script adds the hooks to `~/.claude/settings.json` and `~/.codex/hooks.json` (`--no-claude` / `--no-codex` to skip one). Restart Claude Code. In Codex, run `/hooks` once and trust the Kanarya hooks. The canary appears in the top-right corner of your screen.
  55. **Many sessions at once:** each open Claude Code or Codex session gets its own canary in the same window, in its own color (yellow, orange, white, green, cinnamon). It is labelled with the session title (Claude Code's own title or your `/rename`), and Codex sessions are marked as such. When a session ends, its canary leaves; a new session hatches from an egg.
  56. ## Use
  57. - **Tray icon** (Windows notification area / macOS menu bar): click to show or hide, right-click for settings and quit
  58. - **Right-click:** Settings · New egg · Watch the cat attack · Hide · Quit
  59. - **Double-click:** the canary hops and sings
  60. - **Top strip:** drag the window (position is remembered)
  61. - **Click through** (Settings or tray menu): clicks pass to whatever is behind, as if the canary was not there
  62. - **Bottom corners:** drag to resize (the cage keeps its shape; size is remembered)
  63. - Commands: `/kanarya:ac` (open window), `/kanarya:durum` (status), `/kanarya:kur` (install window)
  64. **Settings:** language (English / Turkish), theme (dark / light / system), transparent background, check frequency, lives, healing, canary name, what happens on death, corner, size, always on top, auto start, context size (200K / 400K / 1M).
  65. Data lives in `~/.claude/kanarya/`.
  66. ## Limits
  67. - Works in **Claude Code** and **OpenAI Codex**, because both have hooks. It does not work in plain chat apps (claude.ai, ChatGPT).
  68. - It measures a *symptom* of context loss, not proof of hallucination.
  69. - The window is Electron. To save battery it draws 8 fps when idle and only animates smoothly while a scene plays.
  70. ## Development
  71. ```
  72. npm install
  73. npm test # grading + end-to-end hook tests
  74. npm run demo # plays every scene
  75. ```
  76. Related keywords: Claude canary, Claude Code canary, Codex canary, context canary, hallucination detector, context rot, context window monitor, Claude Code plugin, Claude Code hooks, Codex hooks.
  77. ---
  78. ## Türkçe
  79. **Claude Code için bağlam kanaryası.** Madendeki kanarya gibi: Claude bağlamı kaybetmeye başlarsa masaüstündeki kanarya yaralanır. Bir şey uydurursa karanlıktan bir kedi gelir ve kanaryayı yer.
  80. - Oturum açılınca Claude'a gizli bir kelime verilir. 4 mesajda bir (ayarlanabilir) kelimeyi cevabın sonuna `<kanarya>…</kanarya>` olarak yazması istenir.
  81. - Tam doğru 🐤 şarkı. Yarı doğru 🤕 −1 can. `?` 😵 hasta ama ölmez. Uydurma 💀 kedi yer. **"Bilmiyorum" demek öldürmez, uydurmak öldürür.**
  82. - 3 can vardır. Art arda 3 doğru cevap bir can geri verir. Bağlam doldukça kanarya uykulu görünür. `/compact` ya da yeni oturum açılınca yumurtadan yeni kanarya çıkar.
  83. - Kanarya ölünce Claude'a not, Windows bildirimi ve ses (hepsi ayarlardan ayrı ayrı açılıp kapanır).
  84. - Claude Code ve Codex'te çalışır. Açık her oturumun kendi kanaryası olur; hepsi tek pencerede, 2x2 ızgarada durur. Her kanaryanın altında oturumun başlığı yazar.
  85. - **Kurulum:** `/plugin marketplace add IF-ies/Kanarya` → `/plugin install kanarya@kanarya` → `/kanarya:kur`, ya da `node install.js` (Claude Code + Codex; Codex'te bir kez `/hooks` ile onayla).
  86. - Sağ tık: ayarlar, yeni yumurta, kedi saldırısını izle. Arayüz Türkçe ve İngilizce; koyu, açık ve şeffaf görünüm.
  87. - **Ne bu?** Bir Claude Code **eklentisi** (hook'lar + birkaç komut) ve kanaryayı çizen küçük bir masaüstü uygulaması. Skill değil, çünkü her mesajda Claude istese de istemese de çalışması gerekiyor. MCP de değil, çünkü Claude'a araç vermiyor, onu dışarıdan denetliyor.
  88. - **Platform:** Windows'ta test edildi. **macOS ve Linux henüz test edilmedi.**
  89. MIT License. All art is drawn in code and all sounds are synthesized, so there are no third-party assets.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.