First run
Five minutes from a fresh install to an agent that has written code you reviewed.
1. Create your account
Helmry requires a sign-in, so the first launch shows a registration form: email, an optional display name, and a password of at least 8 characters (typed twice).
Three things worth knowing before you pick a password:
- The first account closes registration. Nobody else can register on this install afterwards. That is what protects a fresh install, where nothing could be signed in yet.
- There is no password reset. The only recovery is deleting
~/.helmry/helmry.db, which also deletes chat metadata, saved prompts and preferences (your Claude transcripts survive — they live in~/.claude/projects). - A session lasts 30 days and renews as you use it, so you sign in roughly once a month per browser/window.
An account names you and holds your workspace layout. It is not an isolation boundary — see Privacy & security.
2. Windows only — where your repos live
The server runs on Windows, always. You do not choose that; you choose it per repository, when you
add one: This PC for repos on C:\, or a WSL distribution for repos that live inside one. An
agent then runs entirely on that side — its claude, its terminal, its git.
The rule behind it is worth getting right rather than clever: an agent runs where its code is. See Windows & WSL.
3. Check that Claude is signed in
Open Preferences (⌘, / Ctrl+,) → Claude account. It shows the Claude login every agent on
this machine will run as, and lets you sign in or switch accounts without leaving Helmry.
If Claude Code is not installed at all, agents fail to start and the header says so. Install it and restart Helmry.
4. Add a repository
Open the project menu in the top bar → Add repository…, and browse to the folder. It should be
the root of a git repository (the folder containing .git) — that is what makes branch badges,
the file-edit feed, Diff & review and commits work.
Two rules the server enforces:
- Folders you add manually must live under your home directory. Repos Helmry already knows about (because an agent or an observed session ran there) are allowed wherever they are.
- Paths are resolved through symlinks, and nothing outside an allowed root is readable — a
..in a request cannot climb out.
You can hide a repository from the workspace later without removing it, from the same menu.
5. Launch your first agent
New agent (from the fleet rail or the command palette, ⌘K / Ctrl+K) asks for:
| Field | Suggestion for a first run |
|---|---|
| Environment | Local — unless the repo is inside WSL |
| Repository | the repo you just added |
| Model | opus (the default) — a strong all-rounder |
| Permission mode | Ask for your first agent, so you see every action before it happens. The app’s default is Full-auto, which is right once you trust the setup. |
| Reasoning effort | High (the default) |
| Isolated worktree | leave off for a first look; turn it on when you want the agent to work on its own branch in its own checkout |
| Pin | optional — keeps the agent at the top of the rail |
Launch, and Helmry opens the new agent’s Conversation. Nothing has run yet: an agent is just a seat in a repo until you send it something.
6. Send it something small
Ask for something you can verify in a glance — for example:
Read README.md and list the three commands a new contributor is most likely to need. Do not edit anything.
While the turn runs you will see the agent’s text stream in, the tools it calls, and — in Ask mode — approval prompts for anything that touches the machine. Answer them inline. If the agent asks you a question (rather than for permission), it appears as a question with your options, not as an approve/deny.
Enter sends. Shift+Enter is a newline. If the agent is already busy, Enter queues your
message for when the turn ends, and ⌘Enter / Ctrl+Enter interrupts and sends now. Esc stops the
agent but keeps what it has already done.
7. Now let it edit, and review the result
Send a real change — a typo fix, a small refactor — and watch the file-edit feed in the conversation: a card per file the agent created, modified or deleted, as it happens.
When the turn ends, open Diff & review (the tab only exists for an agent that owns its working
tree, i.e. one launched with an isolated worktree), read the diff, stage what you want and commit from
the rail on the right. For an agent working in your shared checkout, use the project-wide Changes
view in the left rail instead — in a shared tree git status describes the tree, not the agent.
Full walkthrough: Reviewing & committing.
Where to go next
- The Cockpit — the whole screen explained, plus the keyboard shortcuts
- Working with agents — models, permission modes, worktrees, queueing, rewinding
- Settings — cost/RAM knobs worth knowing about early (warm agents, card titles)