Working with agents

An agent in Helmry is one Claude conversation bound to one repository. It keeps its model, its reasoning effort, its permission mode and its history for life, and you can have many of them at once.

Launching one

New agent (fleet rail, or ⌘K → New agent…) asks for six things:

Environment — Local, or a WSL distribution (Windows & WSL). An agent’s environment is fixed once it is created.

Repository — one of your allowed roots. The dialog only offers repos you have not hidden.

Model

Reasoning effort

high is the default on purpose: measured on the same task, xhigh spent 27% more output tokens than high for an answer of the same length — the extra went into thinking, not into what you got.

Permission mode

Change it any time from the pill in the composer; the choice is remembered per agent.

Isolated worktree (optional) — creates a git linked worktree on a fresh branch (you can name it) and runs the agent there. Two agents in the same repo then cannot step on each other, and the agent gets its own Diff & review tab, because in that tree git status describes exactly its work. Without it, the agent edits your shared checkout and you review through the project-wide Changes rail instead.

The composer

Everything you do with a running agent happens here.

Sending. Enter sends. If the agent is mid-turn, Enter queues the message and it goes out when the turn ends (you can see and remove queued messages, or exit the queue). ⌘Enter interrupts and sends now. Right after sending you get an Undo send button — that kills the turn and rewinds the transcript, so it is as if you never sent it, and your text comes back to the composer with its attachments.

Stopping. Esc, or the stop button: the agent stops but keeps everything it has already done.

Going back

• Jump back to your message — navigation only; nothing changes.
• Edit & resend from here → Save & resend: rewinds the conversation to that point and sends your edited message instead. Everything after it is dropped from the transcript, so treat it as an edit to history, not a branch.

Both work on the real transcript on disk. Helmry refuses a rewind it cannot measure exactly (e.g. before the full conversation has been loaded) rather than cutting in the wrong place.

Background work

A turn ending is not always the work ending. If the agent launched something in the background — an async sub-agent, a run_in_background command — the agent keeps reporting as working and posts the task lifecycle as it goes. When a background task lands, the agent runs a full cycle of its own to report it, which is why you may see it “talk” without you having sent anything.

Two consequences worth knowing: an agent holding unfinished background tasks is never shut down for being idle, and the pending-task list belongs to the agent — every window looking at it sees the same list.

Cost, context and warm processes

• Every turn shows a receipt under the answer: time, response duration, tokens and cost. Hover the token count for the input/output/cache split and how full the context window was when the turn ended.
• The context meter turns amber past 60% and red past 85%. When a conversation gets long the composer says so — continuing it stops being cheap, and starting a fresh agent for the next piece of work is often the right move.
• Agents stay warm. After a turn ends, the agent’s claude process is kept alive (an hour by default, up to 12 agents at once) so the next turn reuses the prompt cache it already paid for. This is a deliberate RAM-for-tokens trade — roughly 300 MB per warm agent against ~3× the tokens on a cold turn. Both numbers are adjustable in Preferences → Agents; 0 warm agents turns reuse off.
• After a restart, agents whose turns the server killed on the way out are told to continue by default. It costs tokens (a resumed turn starts on a cold cache), so it is a setting — off leaves it to the Resume button in each chat.

Saved prompts

A library of prompts you reuse. Open it with ⌘/ from any composer, or Manage saved prompts… from the palette. You can pin the ones you use most, edit and delete them, and dispatch one straight to the current agent with ⌘Enter instead of loading it into the box first. On the Orchestrate board the same picker dispatches to whatever you have targeted.

Agent names

By default a card is named after the first words of your newest prompt — free and instant. In Preferences → Agents you can switch to Summary, which spends a cheap Claude call (~$0.003) to refine long prompts into a 2–6 word label, or turn naming off and keep repo / branch / id. Rename any agent by double-clicking its title.

Deleting, archiving, keeping

• Delete chat removes the agent from Helmry. Claude’s transcript on disk stays.
• Archive session (observed sessions) only hides the row; the session keeps running.
• Archive conversation copies the transcript into ~/.helmry/archive, and Helmry reads it from there if the live file is ever gone. Nothing is archived automatically — a copy of every conversation would double the size of ~/.claude/projects.