Troubleshooting

First three things to check

The connection light in the top bar (live / offline). Click it for System vitals — server, event stream, Claude platform status, fleet. offline means the window lost the event stream, not necessarily that the server is gone.

The logs. Help → Open logs (press Alt for the menu bar), or read ~/.helmry/logs/main.log. Each line is TIMESTAMP LEVEL <json>, so the line as a whole is not valid JSON — strip the prefix first:

grep -o '{.*}' ~/.helmry/logs/main.log | jq 'select(.level=="warn" or .level=="error")'
grep -o '{.*}' ~/.helmry/logs/main.log | jq 'select(.component=="agent")'

The agent component covers process spawn/kill and turn lifecycle. When an agent’s process dies, the log line always carries a reason (idle-timeout, warm-pool-lru-evict, turn-abort:…, respawn-config-mismatch, …) — that is the fastest answer to “why did my agent stop?”.

Logs contain metadata and decisions only — never prompt text, responses, tool input/output or secrets. They rotate at 1 MB and keep one previous generation.

~/.helmry/logs/hook-client.log only ever contains the hook shim’s own failures. A non-empty file there already means something is wrong with hook delivery.

The health endpoint, for a machine-readable answer:

curl -s http://127.0.0.1:4317/api/health | jq
# { ok, version, uptime_ms, platform, wsl_distro, protocol, claude: { source, ok } }

claude.ok = false means the Claude CLI could not be resolved — that is the single most common cause of “agents don’t work”.

Agents

An agent won’t start / fails immediately. claude.ok = false in the health output means Claude Code is not installed or not on the PATH the app inherited. On Windows, an npm-installed claude is a .cmd shim; Helmry resolves it to node.exe plus the CLI entry point, so Node must be present too. Install or fix Claude Code, then restart Helmry.

Every turn errors with an authentication problem. Open Preferences → Claude account. The whole fleet runs as one machine-wide Claude login; if it was signed out (or the credentials expired), sign in there. Signing into claude.ai in a browser does not change it.

An agent is stuck on “working” and nothing is streaming. Either it launched background work — in which case that is correct, the agent stays working until the task lands — or the turn is genuinely wedged. Press Esc (stop keeps everything done so far), then look at the last agent-component log lines for a reason.

A turn died when I restarted the app. Expected: restarting stops the agents driven from that window. With Continue interrupted turns on (the default) they are told to carry on when the server returns; otherwise each chat offers Resume.

Memory is high. Up to 12 agents stay warm at ~300 MB each by default. Lower Preferences → Agents → Keep agents warm, or set it to 0. Nothing degrades except the token bill.

“Undo send” or “Edit & resend” is refused. Both rewind the real transcript, and Helmry refuses rather than cut in the wrong place when it cannot measure the position exactly — for example before the full conversation has loaded, or if the transcript file is unreadable. Reopen the agent and wait for its history to finish loading, then try again.

The Diff & review tab is missing. It only exists for an agent that owns its working tree (launched with Isolated worktree). Review a shared checkout in the left rail’s Diff mode instead. See Reviewing & committing.

Repositories, files and the terminal

“Not a valid/allowed repo directory” when launching an agent. Folders you add must live under your home directory, and the path must exist. Repos Helmry already knows are allowed wherever they are.

A terminal tab won’t open. Shells only start in an allowed workspace root. Add the folder first (project menu → Add repository…).

The file-edit feed shows nothing. It needs a git repository (it is computed from git), and it only runs for the agent a window is actually watching. Open the agent’s conversation and give it a moment.

Notifications

No desktop notifications. Open the bell menu in the top bar — that is what asks the browser/OS for permission. Then check Preferences → Notifications: the master switch and the per-status choices are applied on the server, so a status you turned off will never notify anywhere. On macOS also check System Settings → Notifications for the app.

The screenshot button does nothing (macOS). Grant Screen Recording to the application that hosts Helmry, then restart it. As a fallback, capture with ⌘⌃⇧4 and paste into the composer with ⌘V.

Updates

“Check for updates” never finds anything. Releases live in a private repository, so an install without a token cannot see them. Use Check for updates… once — Helmry writes a pre-commented update-token file and offers to reveal it. Paste a token with Contents → Read-only access and restart. See Install & updates.

It says “This is a development build.” Auto-update only applies to packaged installs.

I pressed “Restart now”, the app closed, and nothing happened. Windows refused to launch the downloaded installer. On Windows 11 the usual cause is Smart App Control, which blocks unsigned executables and — unlike SmartScreen — has no “run anyway”; a notification saying so appears separately from Helmry. From 0.1.10 the app reports this instead of just closing, and shows you where the installer is. Check the log for spawn UNKNOWN next to Executing: …Helmry-Setup-<version>.exe (see Open logs) — that line is Windows declining, not a failed download. The fix is either to turn Smart App Control off (it cannot be turned back on without reinstalling Windows) or to install that version by hand from %LOCALAPPDATA%\helmry-updater\pending, which will show you the same block.

Every update downloads the whole installer (~110 MB). Expected for now. Differential download needs a blockmap, and the private-feed provider builds the blockmap URL from the asset’s API URL, which does not resolve — the updater logs Cannot parse blockmap … incorrect header check and falls back to the full download.

Windows and WSL

A second launch did nothing visible. By design: Helmry folds a second launch into the running window. Two instances would fight over the same database and re-point every installed hook at the second server’s port.

The connection screen keeps coming back. The saved choice (a WSL distro or a remote URL) stopped answering. The screen retries behind itself; pick another target, Rescan, or forget it to return to hosting on Windows.

The window title warns about a version mismatch. An auto-update replaced the desktop app but not the Helmry install inside WSL. Update the WSL side too.

“Couldn’t connect to <distro>… running as "standalone", not as an environment node.” Something in that distribution is already running Helmry as its own install — most often an helmry start you launched in there by hand, or an Helmry dev stack. Only one server may own a distribution’s Helmry data directory, so Helmry cannot add a node beside it, only instead of it:

wsl -d <distro> -- pkill -f "helmry.*start"   # then press Connect again

If you want to keep that server running — you are developing Helmry itself, say — give it a data directory of its own and the two stop competing:

HELMRY_DATA_DIR=~/.helmry-dev npm run dev

“Helmry did not come up in <distro> within 40s.” The hub asked the distribution to start a node and nothing answered. Run the same thing by hand to see the error it hit: wsl -d <distro> -- bash -ic "helmry start". If starting it by hand works, check <dataDir>/logs/main.log for a line naming the launcher — that is a different failure from a node that started and crashed, and Helmry now reports which one it was.

“…too old to be driven as an environment.” The helmry on that distribution’s PATH is a hand-built install from before environments existed: its start has no --role, so it can only come up as a standalone. Rebuild and re-link it inside the distribution (git pull && npm install && npm run build && npm link), or remove it (npm unlink -g @helmry/cli) and let Helmry install its own build there.

“The Helmry on <distro>’s PATH speaks an environment protocol this hub cannot use…” The same situation one step later: the hand-built install is new enough to be launched as a node, but too old to talk to this hub — and this Helmry has no way to fetch a build of its own (an unpackaged install, or no update token configured). A packaged desktop app installs one beside your npm link automatically, and you never see this. Otherwise rebuild the checkout inside the distribution (git pull && npm install && npm run build), or remove the link and let Helmry manage its own build there. Nothing is left running in the distribution meanwhile — that is deliberate, so the rebuild is not fighting a live server for the data directory.

Observed sessions inside WSL never appear. Hooks must be installed inside the distribution: wsl -d <distro> -- bash -ic "helmry install-hooks".

Accounts

I forgot my password. There is no reset. The only recovery is deleting ~/.helmry/helmry.db, which also deletes chat metadata, saved prompts and preferences. Your conversations are not in there — Claude’s transcripts live in ~/.claude/projects — but Helmry’s index of them is, so chats will have to be re-opened from disk.

Registration is closed and I need another account. The first account closes registration permanently. An Helmry account is not a tenancy boundary anyway, so a second one buys nothing but a second name; see Privacy & security for what real separation would require.

If you have the CLI

helmry doctor is the fullest health report available: Node version, whether Claude Code is on the PATH, whether the hook receiver is built, whether Helmry’s hooks are installed / out of date / broken, whether the data dir is writable, whether the server is reachable, log file sizes, and whether the session database is internally coherent. It is not part of the desktop installer.