Docs

Using Ephorhelm

This page is generated from the app's own help pane, which you can open any time with F1.

Requirements

Windows only for now: Windows 10 or Windows 11, 64-bit (x64). No macOS or Linux build yet. Both are on the list, with no date promised.
Claude Code installed and signed in. Ephorhelm drives your install and never holds your Anthropic credentials.
Git Bash, used by the hooks that report session activity. Git for Windows includes it.
An Ephorhelm account for activating the machine.

Shortcuts

Ctrl+Shift+N: Open a project (the picker). Tick several to open them together.
Ctrl+Shift+W: Close the active session (asks first while it is live). Plain Ctrl+W is left to Claude Code for delete-word.
Ctrl+Shift+L: Insert a saved prompt into the active session. Enter inserts without sending; Ctrl+Enter inserts and sends.
Ctrl+P: Quick switcher: jump to an open session or open a project by name.
Ctrl+Shift+P: Command palette: every action, including Hand off and exit.
Ctrl+1 … Ctrl+9: Jump to session 1 to 9 in sidebar order.
Ctrl+Tab / Ctrl+Shift+Tab: Next / previous session.
Ctrl+Shift+G: Search every open scrollback and the saved transcripts of every project; Enter jumps to the hit.
Ctrl+Shift+F: Find in the active terminal scrollback.
Ctrl+V / Ctrl+Shift+V: Paste into the terminal (Windows Terminal convention).
Ctrl+Shift+C: Copy the terminal selection (plain Ctrl+C still interrupts Claude).
Ctrl+Shift+Up: Jump to the previous turn in the scrollback. A "Turn N of M" overlay confirms the jump.
Ctrl+Shift+Down: Jump to the next turn in the scrollback.
Ctrl+Shift+Y: Copy the last assistant answer to the clipboard, in full.
Ctrl+Shift+R: Open the read-only review pane on the file Claude changed most recently (j / k step hunks, Esc closes).
Ctrl+Shift+B: Collapse or expand the sidebar to a rail of ring gauges.
Ctrl+,: Open Settings.
Ctrl+H: The Helm view is not built yet; Ctrl+H is held for it.
Ctrl+Shift+D: Read-only headless summary of every open session, one run per isolation orbit.
Ctrl+\ / Ctrl+Shift+\: Split the focused pane side by side / top and bottom, then choose what goes in the new pane.
Ctrl+Alt+Arrows: Move focus between split panes.
Ctrl+Shift+T: Every project’s task list in one pane, plus the backlog, AI prioritise and history harvest.
Ctrl+Shift+Space: Push-to-talk: hold to record (or toggle, per Settings). Text lands in the prompt box without Enter.
F1: This help.
Esc: Close any dialog or menu.

Ctrl+B (Claude Code background tasks), Ctrl+C, Ctrl+D, Ctrl+L, Ctrl+R, Ctrl+Z, Ctrl+W (delete word) and every other chord go straight to the terminal - Ephorhelm will not let you bind over them. Settings › Keyboard rebinds everything else.

What Ephorhelm is

One window for all your Claude Code sessions. The sidebar lists what is OPEN; the picker opens new sessions from your project catalog with a named session and its first prompt already sent.

Each row shows the session’s state, git branch, model, spend so far and context used ([[ind:ctx-ok]] green to 50%, [[ind:ctx-warn]] amber to 80%, [[ind:ctx-danger]] red from 81%: hand off soon). The footer shows machine CPU and memory (same green / amber / red bands) plus the total spend across the sessions listed.

Session states

[[ind:launching]] Launching: the shell and Claude are starting (blue, pulsing).

[[ind:working]] Working: Claude is on a turn (blue, pulsing). A badge counts running subagents.

[[ind:idle]] Waiting on you: the turn ended; the row gets an unread dot [[ind:unread]] until you look at it.

[[ind:attention]] Needs you: Claude is asking for a permission decision (red, pulsing). The row and the Helm card get a red edge [[ind:edge-attention]] too.

[[ind:exited]] Exited: Claude quit. By default the shell ends with it and the row closes itself; Settings can keep the shell open instead.

When the window is not focused, a finished turn flashes the taskbar and shows a Windows toast; enable the sound in Settings if you want it audible.

Opening and closing

Groups (InSys › EMS, AMS) start expanded in the picker; the arrow collapses them. Click a project to open it now, or tick several and press “Open N sessions”; Ctrl+click also ticks.

The ⟲ button on a project lists its recent sessions to resume with claude --resume.

Sessions running in another terminal appear under ELSEWHERE. Click one to move it into Ephorhelm once it is idle (or force it). The old console window keeps a dead shell; close it by hand.

Closing a live session (Ctrl+Shift+W) terminates its shell and everything running in it; transcripts stay on disk and can be resumed. Closing the window offers “Hand off, then close”.

Hand off and exit

Right-click a row, or use the palette, to hand a session off: when it is idle Ephorhelm types the hand-off prompt (see Settings), waits for Claude to finish, then sends /exit. A permission prompt aborts it so nothing is typed into the wrong place.

“Hand off and exit all sessions” does this for every live row; the close-window dialog can quit Ephorhelm when the last one is done.

Keyboard

Settings › Keyboard opens the shortcut editor: search by action or by chord, click a chord to record a new one, reset one row or all of them, and apply a preset (Ephorhelm default, Windows Terminal-like, Terminal-safe).

The editor knows which chords Claude Code and the shell need - Ctrl+B, Ctrl+C, Ctrl+D, Ctrl+L, Ctrl+R, Ctrl+Z, Ctrl+U, Ctrl+K, Ctrl+A, Ctrl+E, Ctrl+W, Ctrl+G, Ctrl+O, Ctrl+T, Ctrl+_, Ctrl+V, Esc, Enter, Tab, Shift+Tab and the arrows. It refuses to bind any of them and says why; they are listed read-only under “Reserved by Claude Code”.

“Press a key to see what it does” tells you, for any chord, whether Ephorhelm handles it, whether it is reserved, or whether it goes straight to Claude Code. Overrides can be exported and imported as JSON.

Attention inbox

When a session asks for a permission decision it jumps into the NEEDS YOU box [[ind:edge-attention]] at the top of the sidebar, with the tool and what it wants: “Bash git push”, “Edit C:...index.ts”, the URL for WebFetch. The full text is in the tooltip.

Answer without switching terminals: Allow sends Enter, Always sends 2 (“yes, and do not ask again”, only when Claude Code offers it), Deny sends Esc. Click the session name instead to go and read the prompt yourself.

Click a row (or Tab to it) and press y to allow or n to deny. The same two answers are in the command palette as “Allow / Deny pending request for …”. Collapsed, the sidebar shows just a red count [[ind:attention]]; click it to jump to the first waiting session.

The session row itself swaps its branch line for “Needs you: …” while a prompt is pending, and an unfocused window flashes the taskbar and raises a Windows notification carrying the same one-liner.

Voice (push-to-talk)

Hold Ctrl+Shift+Space, speak, release. REC pulses in the sidebar header while recording, then a blue dot while transcribing. The text is typed into the active prompt box without Enter so you can read it before sending.

Recognition runs locally with Whisper (faster-whisper, CPU). Nothing leaves this machine. Ephorhelm ships a standalone speech sidecar, so no Python install is needed; in the dev tree it falls back to scripts/stt_server.py. Settings › Voice shows which one it found.

First use of a model size downloads it once (tiny.en 75 MB to medium.en 1.5 GB) into %APPDATA%\Ephorhelm\models. “Download model now” in Settings does it ahead of time with a progress bar. If Settings says the engine is not available, rebuild the sidecar with npm run build:stt.

Over Remote Desktop the microphone must be redirected to this machine (RDP client › Local Resources › Remote audio › Record from this computer). If no device is visible you get a “Microphone” error toast.

Reviewing what Claude changed

The files-changed panel lists what Claude edited this session, newest first, with +N -M against HEAD. Click a row to open the Review pane: the file’s diff, or the whole file with the changed lines highlighted (the Diff / File toggle in its header).

The pane is READ-ONLY. j and k step through the hunks, Esc closes it, and the header buttons open the file in VS Code or reveal it in Explorer. Drag its left edge to resize; the width is remembered. On a narrow window it covers the terminal instead of sitting beside it.

Ctrl+Shift+R (or “Review changed files” in the palette) opens the pane on the newest edit. Git runs in a worker thread, so nothing here blocks the app.

Deck brief

Ctrl+Shift+D (or “Deck brief” in the palette, or Brief in the sidebar footer) asks a headless Claude to read what every open session has been doing and write one short paragraph each, plus a “Needs Doug” list at the top. Click a paragraph to jump to that session.

The overseer runs with every tool switched off, so it can only read the notes Ephorhelm hands it: your session states, context and git line, the last few assistant messages, and the head of each project’s HANDOFF.md. It never types into a session and never touches a file.

Sessions are grouped by the orbit set in catalog.json (“orbit”: “litigation” on a project, inherited by its children). Each orbit gets its OWN run, so notes from one orbit are never in the same prompt as another’s. Anything untagged is the default orbit.

Each run costs a few cents and takes some seconds per orbit; the pane shows the spend and the time of the last run. “Auto every N min” repeats it in the background.

Split panes and tabs

Ctrl+\ splits the focused pane side by side, Ctrl+Shift+\ splits it top and bottom. The quick switcher opens in "choose a session for the new pane" mode: pick a session that is open but not on screen, or a project to launch straight into the new pane.

Ctrl+Alt+Left / Right / Up / Down move focus between panes; clicking a pane focuses it too. Drag a divider to change the share, and the × on a pane header takes that session out of the view without closing it (the palette has "Unsplit (show only this pane)" as well).

Sessions sharing the view are bracketed together in the sidebar with a shape glyph such as 1 | 2 side by side or 1 / 2 stacked. Clicking a row inside the bracket focuses that pane; clicking any other row replaces the whole view. Closing a session gives its space back to the sibling. The split is not restored on relaunch - you start on one pane.

Settings › Layout chooses where the session list lives: the sidebar, a tab strip above the terminal, or both. Tabs carry the same colour stripe, state dot, context gauge and unread dot as the rows; middle-click a tab to close it and + opens the picker.

Tasks

Ctrl+Shift+T (or the ☑ button under the sidebar) opens the task tracker: one collapsible block per project, and inside it the task list of each OPEN session plus a Backlog of tasks Ephorhelm owns.

Session lists are READ-ONLY mirrors of what Claude Code itself keeps, so ticking one off in the pane is not possible; drive it from the session instead. The Backlog is yours: type in the box at the bottom of a project to add a task, then mark it done or dropped.

“History” on a project reads its most recent saved transcripts (Settings sets how many) and shows the task lists of sessions that are no longer open.

“Prioritise” sends the open items to a headless Claude (print mode, no tools) and writes a rank plus one line of reasoning under each. Projects are grouped by isolation orbit and each orbit gets its own call, so work that must stay apart never shares a prompt.

“Harvest” scans a project’s saved chats for task items that were never completed and for wish-list wording in your own messages (“would be nice”, “later”, “we should”), then has the same headless pass de-duplicate them. Nothing is saved until you pick from the review list.

“Send to session” types “work on: …” into a chosen open session’s prompt box without pressing Enter, so you can read it before sending.

Colors and the catalog

Right-click a row to pick a color for its project; colors are written back to catalog.json and the file watcher picks up hand edits. “Edit catalog.json” is in the picker footer and in Settings.

Source host (ADoS and GitHub)

Ephorhelm reads each session’s git origin. For Azure DevOps Server on intfs05 (the Technoir and InenviProjectCollection collections) and for github.com it can say more than the branch: ↑2 ↓1 next to the branch means 2 commits to push and 1 to pull, and a "PR 1" chip appears when the branch has open pull requests. Click the chip to open them in the browser; the row tooltip names the provider (ADO or GH).

Pull-request counts come from the ADoS REST API using the PAT in C:\Users\Doug\.secrets (never sent to the window, never logged) and, for GitHub, from the gh CLI when it is on PATH. Everything is read-only and cached for five minutes; if a host cannot be reached the chip is simply absent.

“New project from repo…” in the command palette clones a repository into C:\Users\Doug\projects, adds it to catalog.json and opens a session in it. The clone runs off the main thread and streams its progress into the dialog; ADoS URLs are cloned with certificate checking off because intfs05 serves a self-signed certificate.

Prompt library

Ctrl+Shift+L opens a searchable list of saved prompts, global and per project. Enter inserts the rendered text into the active session without sending; Ctrl+Enter inserts and sends it.

Entry 1 is always the hand-off prompt from Settings; each project also carries its catalog first-prompt as a read-only entry. Prompt text can use {project}, {cwd}, {branch}, {date} and {prefix}; anything else in braces is left as-is.

“Manage prompts…” (Settings, or the palette) adds, edits, pins and deletes your own saved prompts.

Search everywhere

Ctrl+Shift+G searches two places at once: the scrollback of every session open in Ephorhelm, and the saved Claude Code transcripts of every project in your catalog. Results are grouped by session, newest transcripts first, with a count on each heading.

Arrow keys move through the hits and Enter jumps. A scrollback hit scrolls that terminal to the line and highlights the term; a transcript hit focuses the session if it is still open, otherwise it offers “Resume this session” (same as the picker’s ⟲) and “Copy claude --resume”.

The toggles are case sensitive, regex (an invalid pattern is reported under the box rather than throwing), the two scopes, and “tool output”, which also searches tool inputs and results - far more text, so leave it off unless you are hunting for a command you ran.

Transcript scanning runs in a worker thread, streams in as it goes, and stops at 500 hits or 25 seconds; the footer says when results were cut short.

The Helm view

Ctrl+H (or the helm button in the sidebar header) shows every open session as a card backlit with its project colour: state, context, model, spend, git branch, what it said last, and its own prompt line. Ten sessions can be driven from one screen.

Type in a card and press Enter to send to that session; Shift+Enter adds a line, Ctrl+Enter sends and jumps to the next card. Ctrl+1 to Ctrl+9 focus a card’s prompt, Tab and Shift+Tab step between them. Typing into a session that is still working is fine - Claude Code queues it, and the card says so.

Cards sort by what wants you: Needs you [[ind:edge-attention]] first (with Allow / Deny buttons), then Waiting on you [[ind:idle]] (most recently finished first), then Working [[ind:working]], then Starting [[ind:launching]]. Working cards dim [[ind:card-dim]] and get a shimmer on the top edge; a finished card lifts and pulses [[ind:card-pulse]] until you look at it.

Click a card’s name to open that session in the terminal view. Esc leaves the Helm (Esc in a card prompt clears it first). Drafts you have not sent are kept while you go and look at a terminal.

Account and licence

Settings › Account signs this machine in: press Sign in, Ephorhelm shows a short HELM-XXXX code, you approve the machine once at ephorhelm.ai/activate, and the app keeps a licence bound to this machine. Registration is free during the beta.

The app checks in every 3 days and sends only the licence id, a hash of this machine, the app version and the Windows version. Nothing about your sessions, prompts, paths or projects ever leaves the machine.

If the licence lapses, Ephorhelm degrades softly: a banner appears and no NEW sessions can be opened, but every terminal that is already running keeps working until you close it. A week of network trouble is tolerated before that happens, and development builds skip the check entirely.

Updates

Installed from EphorhelmSetup.exe, the app checks ephorhelm.ai for a new version shortly after launch and every six hours, downloads it in the background, and offers a Restart to update toast. Settings › Updates has a manual check and the on/off switch.

The portable build cannot update itself - Settings says so - and until code signing is in place Windows SmartScreen warns on first install.

What’s New (the sidebar pill, or F1 › What’s New) lists what changed in this version; the dot clears once you have read it.

Troubleshooting

Empty context bar or spend: Claude Code’s statusline command must be quoted in ~/.claude/settings.json; a session started before the fix keeps the old value until restarted.

A row stuck on Launching: the shell is slow to start on this machine (process creation can take seconds); the registry promotes it as soon as Claude is up.

Restore prompt lists sessions you did not want: choose Start fresh; the list is the last saved layout.

Everything feels slow: open Settings › the event port is listed; the debug build exposes /debug/mainstats for the main-process timings.

The ⇅ button in the header (also in Settings and the palette) cycles how sessions are listed. Stack, the default, floats what needs you to the top automatically: needs you [[ind:attention]], then waiting on you [[ind:idle]] (most recently finished on top), then launching [[ind:launching]], then working [[ind:working]] (a session you just sent a prompt to drops to the bottom). Name is alphabetical; Opened is launch order. Hover a row for a ↓ button, right-click it, or use the palette to send it to the bottom by hand; it pops back up the next time that session changes state. Ctrl+1 … Ctrl+9 and the collapsed rail always match this order.

A soft two-note chime plays when a session finishes and goes idle, and a sharper double tap when one needs a decision, whether or not the window is focused. Turn either off, or set the shared volume, in Settings › Notifications, which also has a Test button for each.

Activating a machine

Ephorhelm asks your account once per machine, using a short code rather than a password typed into a desktop app.

The app shows a code in the form HELM-4K7Q, good for 15 minutes.
Open ephorhelm.ai/activate in a browser and sign in.
Enter the code. The page shows which app version and Windows version asked, and a label for the machine, before you approve it.
Approve. The app polls and picks up its licence within a few seconds.

The licence is tied to that machine. Your account page lists every activated machine with its last check-in, and can remove one - the next check-in from a removed machine stops it opening new sessions.

If the licence lapses

The app checks in every three days. If it cannot reach the site it keeps working for a week on the token it has, and only shows a banner. Past that, or if the device was removed, it stops opening new sessions and says why; the sessions already open keep running until they run out of context.

What the check-in sends is listed in full on the privacy page.