Troubleshooting

Installing

macOS says it can’t verify Hoku

That’s expected for a DMG you downloaded yourself. Click Done, then System Settings → Privacy & Security → Open Anyway. See Install and update. The install script doesn’t trigger this prompt.

macOS says Hoku is “damaged”

The download is incomplete or was changed. Delete it and download it again, and check it. Don’t try to work around the message.

The script says Hoku releases are built for Apple Silicon

You’re on an Intel Mac. Build Hoku from source instead.

The script can’t write to /Applications

Install for your user only:

mkdir -p ~/Applications
curl -fsSL https://raw.githubusercontent.com/joao-afonso-p/hoku/main/scripts/install.sh | bash -s -- --dir ~/Applications

Finding sessions

A scan finds nothing, or says “Not found on this Mac”

That source’s data isn’t on this Mac: you haven’t used that app here, or it keeps its data somewhere else. Integrations shows what Hoku detected. Claude Desktop chats always say Manual only. Add them by link.

A session is missing from the map

It may be older than your recent window. Switch to All (⌘⇧A), use +N older in its project, or search for it with ⌘K. Search covers everything.
A status filter may be fading it. Click Clear.
Its project may be archived. Check Projects → Archived.
You may have forgotten it. It comes back after new activity in its provider, or when you add it again by hand.

A session is in the wrong project

Pick the right one under Project in its inspector, or drag it onto that project. To make future sessions land correctly, give the project a Root folder. See Projects.

A session I forgot came back

It had new activity in its provider after you forgot it, so the next scan added it again as a fresh entry. See Will it come back?

Opening sessions

“macOS blocked Hoku from controlling iTerm” (or Terminal)

Open System Settings → Privacy & Security → Automation, find Hoku, and turn on iTerm or Terminal. After an update, Hoku may appear as a new entry. Turn on the new one.

Hoku says the session is on another desktop

macOS is set not to follow apps between desktops. Open System Settings → Desktop & Dock, and under Mission Control turn on When switching to an application, switch to a Space with open windows for the application. Hoku shows this setting’s current state, and it updates when you come back to Hoku.

“This session is already running in a terminal Hoku can’t switch to”

It’s running in Warp, tmux or another terminal Hoku can’t control. Go to it there. Hoku won’t start a second copy of a live session.

VS Code comes forward, but not the right terminal

Selecting the exact VS Code window and terminal needs the optional Hoku extension for VS Code. Hoku’s message says what happened:

“Hoku couldn’t select its window and terminal”: the extension isn’t installed, or no VS Code window is reporting. Install it from Integrations (under Claude Code, VS Code extension → Set up…), then reload VS Code’s open windows.
“VS Code may be asking whether to allow the Hoku extension to open a link”: find VS Code’s Allow ‘Hoku’ extension to open this URI? question, choose Open, tick Do not ask me again, and click Go to terminal again. Finish VS Code setup asks it in the front window.
“This session’s window isn’t reporting to Hoku”: reload that VS Code window, and check the extension is installed in that window’s VS Code profile. Remote windows (SSH, containers, WSL) never report.
“Hoku couldn’t tell which window holds this session”: two copies of VS Code are running at once. Hoku doesn’t guess.
“didn’t confirm the session’s window and terminal”, “didn’t have its terminal any more”, “reached the window too late” or “a different window answered”: the window was busy, reloading or closed. Pick the terminal yourself, and try again later. If VS Code is still asking whether to allow the link, Finish VS Code setup brings that question forward.

Sessions in the Claude Code extension’s panel, rather than a terminal, always get VS Code brought forward without a window or terminal picked. See VS Code extension for every message.

“Transcript no longer on disk”

Claude Code deleted that transcript, so the session can’t be resumed. Its entry, notes and history stay in Hoku.

Nothing happens for a Codex or Claude session

Codex: if Codex Desktop isn’t installed, Hoku copies the thread ID instead of opening it.
Claude chats open on claude.ai in your browser if Claude Desktop isn’t installed.
If the link no longer works, the conversation may have been deleted in the provider.

Status and alerts

A session shows the wrong state

A state marked Likely: or inferred is Hoku’s best guess from local files. See the provider pages for what each one can report.
Switch back to Hoku: it re-checks immediately when its window comes forward.
Cowork and chat sessions can’t report most states, by design.

No notifications arrive

Make sure Settings → Needs You alerts → Notify me when a session needs me is on.
Hoku must be running. And while its window is in front, it doesn’t notify, because you can already see it.
Check System Settings → Notifications → Hoku, and your Focus mode.
Notifications are only for real blocks: a permission, a question, a sign-in. Finished (Ready) sessions and ordinary errors don’t notify.

The Dock icon shows no number

Check that Show the Needs You count on the Dock icon is on, and that Badge application icon is on for Hoku in System Settings → Notifications.

AI drafts

I can’t turn on AI drafts

Settings says why under the switch:

Claude Code CLI not found: install Claude Code.
Too old: update it.
Signed out: run claude auth login in a terminal.

A draft fails

Read the message. If Claude Code isn’t signed in, run claude auth login, then Retry. Drafts stop after two minutes. Review again rebuilds the preview.

Still stuck?

Open an issue with your macOS version, Hoku version (bottom of Settings) and what you expected. Please leave out real session titles, prompts, emails, IDs and paths that contain your username.