03 - Session#
A session is the conversation between you and a coding agent inside a workspace. It records every prompt, agent response, tool call, and file edit — forming a complete history of a unit of work.
What a session contains#
- Messages — your prompts and the agent's responses, streamed in real time.
- Tool activity — file reads, edits, command executions, and other actions the agent performed.
- Metadata — agent type, model, effort level, permission mode, and timing.
- Provider session ID — allows the session to be resumed after interruption.
Session states#
| State | Meaning |
|---|---|
| Idle | No active streaming. You can send a new prompt or review history. |
| Streaming | Agent is actively producing output. Messages arrive in real time. |
Starting a session#
Send a prompt from the workspace composer. Helmor:
- Persists your message immediately.
- Launches the sidecar process (if not already running).
- Streams agent output back through the pipeline.
- Displays tool calls, reasoning, and file edits as they happen.
Resuming a session#
When you send a follow-up message to an existing session, Helmor passes the stored provider_session_id to the sidecar. The agent provider resumes from where it left off — full conversation context is preserved.
If the session was interrupted (app restart, network drop), the same mechanism restores continuity. A 45-second heartbeat timeout detects unresponsive sidecar processes and surfaces errors clearly.
Concurrency#
Only one session can stream at a time per workspace. Helmor's active-stream locking prevents accidental concurrent sends that would corrupt conversation state.
Persistence#
Messages are written to SQLite as they arrive — user messages on send, assistant messages on each completed turn. If the app crashes mid-stream, all finalized turns are preserved.
Related#
- Continue an Existing Session — how to send follow-up prompts.
- Agent — supported agents and their capabilities.