Skip to content
Hoku

Claude Code

Claude Code is the provider Hoku can see best.

Finding sessions

Section titled “Finding sessions”

Hoku reads Claude Code’s transcripts in ~/.claude/projects, read-only, and keeps only:

  • the title, in this order: the name you gave the session (/rename or --name), its agent name, Claude Code’s own title, or the first real prompt
  • a preview of the first prompt, up to 200 characters
  • the details Claude Code records: folder, Git branch, a linked pull request, the model.

Transcripts themselves are never copied into Hoku.

While Hoku is running, it also notices new Claude Code sessions on its own, within seconds, from Claude Code’s live-session registry in ~/.claude/sessions. You don’t need to rescan for those.

Live state: full

Section titled “Live state: full”

Claude Code keeps a small file per running session saying whether it’s busy, waiting or idle, and, when waiting, on what: a permission prompt, input, a dialog, a sandbox request. Hoku reads that and checks that the process is still alive. So these states are reported by Claude Code itself, with high confidence.

Hoku also reads the last part of the transcript, in memory only, to name what’s happening:

  • the tool that’s running or waiting, such as Running Bash or Waiting for permission · Bash
  • a question Claude asked, which Hoku shows as Asked a question with the question
  • a plan that needs approval
  • errors: Authentication required (needs you), Usage limit reached, Request failed.

Hoku doesn’t install Claude Code hooks. Hooks would mean changing your ~/.claude/settings.json, and Hoku never writes to provider files.

Getting back to a session

Section titled “Getting back to a session”

Go to terminal decides at click time: switch to the tab it’s running in, switch to its VS Code window and terminal, attach to a background session, or resume it with claude --resume in a new iTerm tab or Terminal window. See Getting back to a session.

For VS Code, picking the exact window and terminal needs the optional Hoku extension for VS Code, which comes with Hoku. Without it, Hoku brings VS Code forward and you pick the tab.

Account

Section titled “Account”

Integrations shows the email, organization and plan that claude auth status reports. Hoku never opens Claude Code’s credential files.

Limitations

Section titled “Limitations”
  • Old transcripts disappear. Claude Code deletes transcripts after a while (its cleanupPeriodDays setting). Hoku keeps those sessions, marked Transcript no longer on disk and drawn hollow, but they can’t be resumed.
  • Only iTerm, Terminal and VS Code can be switched to. In VS Code, Hoku picks the exact window and terminal only with the Hoku extension installed, and only in local windows. Sessions in the Claude Code extension’s panel and in remote windows get VS Code brought forward, and you pick them. Sessions in Warp, tmux or other terminals aren’t switched to. Hoku tells you where the session runs instead of starting a second copy.
  • Switching tabs needs macOS Automation permission for iTerm or Terminal, asked once per Hoku version.
  • VS Code forks (Cursor, VSCodium, Windsurf) aren’t recognized.