Observed sessions

Updated 16 August 2026 · written next to the code it describes

Besides the agents you drive inside Helmry, the fleet can show the claude sessions you run yourself — in a Cursor terminal, VS Code, iTerm, anywhere. They appear as rows with the same status colours, so one screen answers “who needs me?” for both kinds.

This is optional. In-app agents work fine without any of it.

Requirement, stated plainly: observed sessions work through Claude Code hooks, and installing those hooks is the job of the helmry command-line tool, which the desktop installer does not include today. If you don’t have the CLI on this machine, observed sessions are unavailable and nothing in the app will change that. The rest of this page describes what the hooks do and how to manage them if you do have it.

What the hooks do

Claude Code can call an external program on lifecycle events. Helmry registers a tiny shim for twelve of them:

SessionStart · UserPromptSubmit · PreToolUse · PostToolUse · PostToolUseFailure · PermissionRequest · Notification · Elicitation · Stop · StopFailure · SessionEnd · CwdChanged

The shim POSTs to the local server and exits. Three properties matter and are enforced in code:

  • It never blocks your Claude. Short timeout (250 ms by default), soft-fail, always exit 0.
  • It sends metadata, never content. A whitelist sanitizer runs before anything is stored: prompt text, responses, transcripts, full bash commands, tool inputs and outputs, environment variables and file contents are dropped. Bash commands are classified for test-detection in memory, then discarded.
  • It is authenticated locally. Ingestion requires the ~/.helmry/token file (mode 0600).

lite mode drops PreToolUse, which removes a hook invocation per tool call at the cost of live “running tool” tracking. Set it in Preferences → Hooks & timing, then re-run the install command — this setting is baked into the hook command itself.

Installing, previewing, removing

helmry install-hooks --dry-run   # show exactly what would change, write nothing
helmry install-hooks             # apply
helmry install-hooks --lite      # apply without PreToolUse
helmry uninstall-hooks           # remove ONLY Helmry's entries
  • A timestamped backup of ~/.claude/settings.json is written to ~/.claude/backups/settings.json.helmry-<timestamp>.bak before any change.
  • The install is idempotent and atomic, and preserves your other hooks and your status line.
  • A malformed settings.json is never overwritten — the command stops and tells you.
  • Restore by hand if you ever need to: cp ~/.claude/backups/settings.json.helmry-<timestamp>.bak ~/.claude/settings.json

Removing hooks removes Helmry’s entries only; it matches them by a marker inside the command string, so hooks you added yourself are untouched.

Two levels of reliability

Hook-only. Start any session normally and it appears:

claude

Metadata is limited to what hooks report. There is no reliable liveness signal, so a session that goes quiet is only reclassified after a timeout (generous by default — one long tool run is legitimate).

Launcher. Start it through Helmry instead:

helmry run --name "CMS redesign" --ticket PROJ-8168
helmry run --name "REST API hotfix" -- claude --model opus

You get an exact PID, heartbeats, disconnect detection, an exit code and a ticket field. The launcher pre-generates the session id and preserves the terminal completely — colours, Ctrl+C, resize, exit code. Anything after -- is passed through to claude.

Hooks and in-app agents

Installed hooks also enrich the agents you drive in the app: the per-tool Activity timeline comes from them. Helmry marks its own headless turns so they do not churn an observed session’s lifecycle, and so a claude an agent starts itself is not mistaken for a member of your fleet.

Managing observed rows

  • Archive session hides the row. The session itself keeps running — archiving is a view decision.
  • Ended and archived sessions are pruned after the retention window (14 days by default), together with their events. See Settings.
  • If you also work inside WSL, hooks must be installed inside the distribution, not on the Windows side. See Windows & WSL.

Terminal tab titles

Helmry can reflect a session’s status into the terminal tab (✅ ready · repo) and ring the terminal bell when a session wants you. Both are in Preferences → Terminal, and both are baked into the hook command, so changing them needs another helmry install-hooks.