Willow — AI skill for Claude Code

Willow

**Willow is a companion narrator for blind builders working with AI coding agents.**

While an AI agent edits your project, Willow watches the folder and tells you — **out loud and in text** — what the agent actually did: which files changed, what changed in them, whether builds and tests really passed or failed, and whether the agent quietly undid its own work.

Every update is a **fact you could check yourself**. Willow never guesses. If it cannot verify something, it says so, or says nothing — it never fills the gap.

---

Setting up (about a minute)

You need **Python 3.8 or newer**. Nothing else: Willow uses only what comes with Python and your computer's built-in voice.

pip install willow-narrator

Then, in your project folder:

willow init

That one command does everything that used to be manual: it writes the rule that tells your AI agent to run tests through Willow (with the correct path already filled in), adds `.willow/` to your `.gitignore`, and installs Claude Code hooks.

The hooks are worth having. They come from the harness rather than from the model, so they work even when the agent forgets the rule — and they let Willow tell you **when Claude is waiting for your permission**, and **exactly how many times a file was written** rather than only how often polling happened to notice.

If you'd rather not install anything, download `willow.py` and use `python willow.py` everywhere this page says `willow`. Everything works the same.

Any time something seems wrong:

willow doctor

`doctor` checks Python, your voice, your model setup, whether a Willow is actually watching, and whether your project is set up — and **says the answer out loud**. Every failure in a tool like this looks like silence, so being able to ask "are you working?" and hear a real answer matters.

---

Using it (two windows)

Window 1 — Willow watches

willow watch

Willow says *"starting up"*, then *"watching … I'll t