Settings
Open Preferences with ⌘, / Ctrl+,, or from the account menu. Settings are stored on the server
(per account for the workspace layout, machine-wide for the server configuration), not in the browser —
so they follow you to another window on the same install.
Some rows carry a badge:
| Badge | Meaning |
|---|---|
| restart | Captured once when the server started. Restart Helmry to apply. |
| install-hooks | Baked into the hook command in ~/.claude/settings.json. Re-run helmry install-hooks to apply. |
Appearance
Themes for this device: Cockpit, Graphite, Midnight, Nebula, Cursor, Daylight. Also reachable from the palette button in the top bar.
Agents
| Setting | Default | What it does |
|---|---|---|
| Card titles | Prompt | Prompt — first words of the newest prompt, free and instant. Summary — a cheap Claude call (~$0.003, only for prompts too long to read as-is) refines it into a 2–6 word label. Off — keep repo / branch / id. |
| Keep agents warm | 12 | How many idle agents keep their claude process alive so their next turn reuses the prompt cache. ~300 MB each. 0 turns reuse off — cheaper in RAM, roughly 3× the tokens on a cold turn. |
| Keep them warm for | 1 hour | Idle timeout for the above. An hour matches the cache tier the CLI asks for; longer only saves process startup. |
| Continue interrupted turns after a restart | on | When the server stops mid-turn (restart, quit, sleep), tell those agents to carry on when it comes back. It costs tokens — a resumed turn starts on a cold cache. Off leaves it to the Resume button in each chat. |
How agents should write
These become a system-prompt addition on every in-app turn — never a suffix on your message, so they never show up inside your own text in the transcript.
| Setting | Default | What it does |
|---|---|---|
| Reply language | Auto | Auto adds no instruction at all (the agent follows the language you write in). Or force English / Russian / German. |
| Compact answers | off | Terse replies — no preamble, no recap of work already visible in the UI. |
| Stay in scope | off | A behavioural instruction, not a formatting one: only what was asked, and no sub-agent for something that can be done in place. |
| Your own instructions | empty | Standing instructions appended verbatim, up to 2000 characters. This rides along on every turn of every agent, which is why it is bounded. |
Claude account
Which Claude login every agent on this machine runs as, with sign-out and sign-in. The whole fleet shares one login — see Privacy & security.
Signing into a different account in your browser does not change anything here; there is no local signal for it, which is why this is a button rather than something Helmry detects.
Notifications
| Setting | Default |
|---|---|
| Desktop notifications | on |
| Play a sound | off |
| Needs approval · Needs input · Ready for review · Failed · Disconnected | all on |
The decision to notify is made on the server, so every window agrees about it: repeated identical states are de-duplicated and bursts are collapsed. Your browser still has to grant permission — use the bell menu in the top bar, which asks for it.
Terminal
| Setting | Default | Badge |
|---|---|---|
Status in the tab title (✅ ready · repo) |
on | install-hooks |
| Ring the terminal bell on “your turn” states | on | install-hooks |
Both only affect observed sessions in your own terminals.
Workspace
The folders agents may be launched in, plus which repos are hidden from the cockpit. Folders added here must live under your home directory; repos Helmry already knows (because something ran there) are allowed wherever they are.
Data & retention
| Setting | Default | What it does |
|---|---|---|
| Keep ended sessions for | 336 hours (14 days) | Ended and archived sessions, and their events, are pruned past this age |
| Events kept per session | 200 | Bounds the activity history one session can accumulate |
Neither affects Claude’s own transcripts in ~/.claude/projects, which Helmry does not own.
Network & startup
| Setting | Default | What it does |
|---|---|---|
| Check Claude platform status | on | Polls status.claude.com so the header can warn when Claude itself is degraded. This is Helmry’s only outbound request — turn it off to keep the tool fully offline. |
| Open the dashboard on start | off | Opens the UI when the server starts |
Hooks & timing
Only relevant with hooks installed.
| Setting | Default | Badge |
|---|---|---|
| Hook coverage — Full / Lite | Full | install-hooks |
| Spool events while the server is down | on | install-hooks |
| Hook POST timeout | 250 ms | install-hooks |
| Launcher heartbeat | 5 s | restart |
| Disconnect after silence | 15 s | — |
| Give up on an unverifiable session | 6 hours | — |
| Move a silent “working” agent to ready | 30 min | — |
| Refresh git metadata | 60 s | restart |
Two notes the UI also gives you: the launcher heartbeat only applies to sessions started afterwards, and values above 5 s do not change the server’s sweep cadence. “Give up on an unverifiable session” only applies when there is no PID to probe — keep it generous, because one long tool run is legitimate.
About
Where this install keeps its data. Useful when you need the paths from Troubleshooting.
The file behind all of this
Server configuration lives in ~/.helmry/config.json (or $HELMRY_DATA_DIR/config.json). Everything
above writes there; you can also edit it by hand and restart. Anything you omit takes its default.
| Key | Default | Notes |
|---|---|---|
host |
"127.0.0.1" |
Do not change this. See the warning below. |
port |
4317 |
|
retentionHours |
336 |
min 1 |
maxEventsPerSession |
200 |
min 10 |
heartbeatIntervalMs |
5000 |
restart |
disconnectTimeoutMs |
15000 |
min 3000 |
staleActiveTimeoutMs |
21600000 |
6 h, min 1 min |
idleActiveTimeoutMs |
1800000 |
30 min, min 1 min |
hookTimeoutMs |
250 |
50–5000, install |
spoolCriticalEvents |
true |
install |
gitRefreshIntervalMs |
60000 |
min 5000, restart |
hookMode |
"full" |
"full" | "lite", install |
extraTestPatterns |
[] |
Extra regexes that mark a command as a test run |
workspaceRoots |
[] |
Constrained under $HOME by the server |
autoOpen |
false |
|
checkPlatformStatus |
true |
|
agentTitles |
"prompt" |
"summary" | "prompt" | "off" |
agentWarmAgents |
12 |
0–12 |
agentWarmIdleMs |
3600000 |
1 min – 4 h |
autoResumeTurns |
true |
|
agentStyle |
{language:"auto", compact:false, scoped:false, custom:""} |
custom ≤ 2000 chars |
terminal |
{title:true, bell:true} |
install |
notifications |
{enabled:true, sound:false, perStatus:{…all true}} |
A rejected edit is reported rather than silently ignored: a single bad field leaves the whole file unapplied, and the app tells you which field and why.
Never set
hostto0.0.0.0or a LAN address. Helmry has no TLS and no remote-access model yet. An install that has no account is deliberately open — the first registration has to be able to reach the server — so on a reachable address whoever finds the port first registers and owns the machine. Even with an account, there is no HTTPS, so the session cookie travels in cleartext. This is not enforced in code; it is on you. See Privacy & security.