Troubleshooting Nook

SmartScreen blocks the installer

Symptom

“Windows protected your PC” appears and there is no obvious way to run the installer.

Cause

The installer is not code-signed yet, and SmartScreen does not know new unsigned programs.

Fix

1. Check the download first: Get-FileHash .\Nook-Windows-0.1.0-setup.exe -Algorithm SHA256, then compare with SHA256SUMS.txt from the release.
2. Choose More info, then Run anyway.

Details in the install guide. Signing through SignPath is planned.

Antivirus flags nook-hook.exe

Symptom

Your antivirus quarantines or warns about nook-hook.exe, so sessions stop showing up.

Cause

It is a small, unsigned, little-known program that other programs start often, which heuristics dislike. This is a false positive.

Fix

1. Verify the file’s hash against SHA256SUMS.txt (it lists nook-hook.exe too).
2. Restore it from quarantine or restart Nook, which copies it back to %LOCALAPPDATA%\Nook\bin at launch.
3. Report the false positive to Microsoft at www.microsoft.com/wdsi/filesubmission as “Software developer” and “Incorrectly detected”; this usually clears Microsoft Defender within days. Other vendors have similar forms.
4. Or build Nook from source and check the code yourself.

The island does not appear

Symptom

Nook is running but you cannot see the island.

Cause

It usually auto-hid. The folded island hides after a while (one minute by default), leaving a hidden strip at the top of the screen. It can also be on another display, or hidden because a full-screen app is in front.

Fix

1. Move the mouse to the top edge of the screen to wake it, or press Ctrl Alt Space.
2. Check the notification area for the Nook icon and choose Open Nook. If Pause was chosen, choose it again.
3. In Settings → General, check which display Nook uses (the main display, or the one under the cursor).
4. In Settings → Island, raise Auto-hide the folded island after or set it to never.
5. No tray icon at all? See Nook does not start.

No sessions show up

Symptom

Claude Code is running but the island is empty.

Cause

Usually one of: the hooks are not installed; the session started before the hooks were installed; old shell-form hooks fail in PowerShell; or the relay is missing.

Fix

1. Install the hooks: Settings → Claude Code should say Connected. If it says Not installed, click Install hooks….
2. Restart the session. Hooks are read when a session starts, so a session that was already open will not report until you open a new one.
3. PowerShell ParserError. If Claude Code reports a hook error such as Unexpected token 'Stop', the hooks were written in an old shell form that only works in Git Bash. Open Settings → Claude Code and click Reinstall… (or Install hooks…) to rewrite them in the exec form. See why.
4. Relay missing. If Settings says Relay missing, restart Nook; it copies nook-hook.exe to %LOCALAPPDATA%\Nook\bin at launch. Antivirus may have removed it (see above).
5. Status line only: a relay path that contains a space or special character is refused for the usage status line, because Claude Code reads that command through a shell. Hooks themselves are fine with spaces. The status line needs a path made of letters, digits and _ - . / :, so a user folder with a space can block it.

Hooks are installed but nothing happens

Symptom

Settings says Connected, you started a new session, and still nothing appears.

Cause

The relay may not be reaching Nook, may be failing to start, or Claude Code may be reading a different settings file than the one Nook edited.

Fix

1. Open the log, which records event names and decisions: %LOCALAPPDATA%\Nook\nook.log.
2. From the terminal where the session runs, run the diagnostic. It prints JSON and proves the relay starts:
   & "$env:LOCALAPPDATA\Nook\bin\nook-hook.exe" --whereCopy
3. Make sure Nook itself is running (tray icon) and not paused.
4. Check that %USERPROFILE%\.claude\settings.json contains entries whose command contains nook-hook.
5. If Nook runs elevated (as administrator) and Claude Code does not, or the other way round, the relay usually refuses the connection because the integrity levels differ. Run both normally.

Permission requests or questions cannot be answered

Symptom

A request shows in the island but Allow or the answer does nothing, or a question never appears there.

Cause

Claude Code versions differ in which prompts they send through hooks. Some questions or permission types may not reach Nook, and the request times out after about two minutes.

Fix

Answer in the terminal: the same question is always shown there too. If it keeps happening, update Claude Code, and open an issue with your Claude Code version (claude --version) and the kind of prompt it was.

Usage limits are missing or stale

Symptom

The usage meters are empty, show an old number, or read 0%.

Cause

Limits come from Claude Code’s status line, so they only appear if the usage status line is installed, only on subscription plans, and only update while a session runs. They are “as of the last Claude Code activity”. After a window resets, Nook shows 0% until Claude Code reports again.

Fix

1. In Settings → Claude Code, install Usage limits.
2. Run a session; the numbers update when Claude Code reports them. Numbers older than about two hours are shown as old.
3. Using an API key instead of a subscription plan usually means there are no limits to show.
4. If another tool owns your status line, Nook chains it; if the numbers are still missing, open an issue.

High CPU use

Symptom

Nook shows up high in Task Manager.

Cause

Nook is a small app that mostly waits for events. Sustained high use usually comes from animation on a very busy desktop, a Shelf widget left open (Media is polled about once a second while it is on screen), or a bug.

Fix

1. Fold the island and close any expanded widget, then watch Task Manager again.
2. In Settings → Appearance, set reduced motion to on and switch off playful reactions.
3. Check that the usage in the island’s CPU readout is not simply your own agents working.
4. If it stays high with everything folded, open an issue with the log and your Windows and graphics driver versions.

The island hides in full-screen apps

Symptom

You are watching a video, playing a game or presenting, and the island is gone.

Cause

This is a setting, on by default: Nook stays out of the way of full-screen apps. A permission request or a question still shows.

Fix

Turn off Settings → Island → Hide in full-screen apps if you want the island to stay visible.

Multi-monitor, 125% scaling, blur or wrong position

Symptom

The island is on the wrong monitor, off-centre, or blurry at 125% or 150% scaling.

Cause

The island sits on one display. If your displays have different scale factors, or the layout changed after Nook started, the window may need to be placed again.

Fix

1. In Settings → General choose the main display or the display under the cursor.
2. Quit and start Nook again after changing the scale, resolution or monitor layout.
3. Blur usually points to a display with a different scale than the one Nook started on. Move Nook to that display via the setting, then restart it.
4. If it is still wrong, open an issue with your monitor layout and scale factors.

Shortcuts do not work

Symptom

Ctrl Alt Space (or another Nook shortcut) does nothing.

Cause

Another app has already registered that key combination as a global shortcut, and only one app can hold it. Or the shortcut is switched off.

Fix

1. Open Settings and change the shortcut to a combination nothing else uses, or switch it on if it is off.
2. Quit the other app to test whether it is the one holding the key. Common culprits are launchers, clipboard managers and input-method tools.

The defaults are Ctrl Alt Space (expand or shrink), Ctrl Shift Space (open the panel) and Ctrl Alt Enter (go to the session that needs you).

Mirror: the camera does not work

Symptom

Mirror says the camera was refused, is missing or is busy.

Cause

Windows camera privacy settings, no camera detected, or another app using the camera.

Fix

1. Refused: Windows Settings → Privacy & security → Camera: turn on camera access and let desktop apps use your camera. If you chose Block when asked, that choice is remembered; change it there and try again.
2. Missing: plug a camera in, or check that Windows can see it in Device Manager.
3. Busy: close the other app (a video call, a camera tool) and press Turn camera on again.

The camera only runs while Mirror is open and is never recorded.

The Media widget shows nothing

Symptom

Media says nothing is playing while music is playing.

Cause

Media shows what Windows’ system media controls know about. A player that does not report to Windows is invisible to it. It also only polls while a Media card is on screen.

Fix

1. Open the Shelf so a Media card is visible, and start playback.
2. Check that Windows shows the same track in its own media overlay (volume flyout). If it does not, the player does not report to Windows; try another player or the browser.

“Go to session” cannot select a Windows Terminal tab

Symptom

The jump button or Ctrl Alt Enter brings Windows Terminal forward but not the right tab.

Cause

Nook can usually bring a window forward, but Windows Terminal does not offer a way to select a particular tab from outside. All tabs belong to one window.

Fix

Look for the tab with the session’s project name. Running nook-hook --where in a tab shows which terminal the relay detects there. Separate Windows Terminal windows, VS Code and Cursor are easier for Nook to find than tabs.

Nook does not start

Symptom

Double-clicking Nook does nothing, or there is no tray icon.

Cause

Usually one of: the WebView2 runtime is missing; Nook is already running (only one instance is allowed); or a previous crash left a process behind.

Fix

1. Already running: look in the notification area (click the ^ arrow). Starting Nook a second time just opens the one that is running. In Task Manager, end any leftover nook.exe and start it again.
2. WebView2: it ships with Windows 11 and current Windows 10. If it is missing, install the Evergreen WebView2 Runtime from Microsoft and start Nook again.
3. Security software: check that it did not quarantine nook.exe.
4. Look at %LOCALAPPDATA%\Nook\nook.log for the last lines.

How to collect logs and open an issue

A good issue gets fixed faster. Open one at github.com/zubairbinshaukat/nook/issues/new and include:

• What you expected and what happened, with steps to repeat it.
• Your Nook version (Settings → About; this site documents 0.1.0), your Windows version (winver), and your Claude Code version (claude --version).
• The last lines of %LOCALAPPDATA%\Nook\nook.log. The log has event names and decisions, never the content of your sessions.
• If it is about hooks, the output of nook-hook --where, and the Nook entries from settings.json (only those).
• A screenshot if the problem is visual.

A false positive from an antivirus can be reported to its vendor, see above.