hydraui, the desktop app.

Install and first start

Run the installer: it installs hydraui and hydra for you alone, with no admin prompt, puts hydraui in the Start menu and hydra on your PATH. Prefer a single file? The portable hydraui-x86_64-pc-windows-msvc.exe from the latest release runs from anywhere and doesn't need hydra.exe. Either way hydraui reads and writes the same ~/.hydra folder as the CLI, so environments made with either show up in both.

The first time, hydraui opens a terminal in your home folder. With no environments yet, it asks you to name one and creates it, as hydra env new does. From then on hydraui starts on a page of your recent layouts: pick one, or New window for a plain terminal. A window saved as a layout keeps its file up to date as you work (its environments, their terminals and folders, the file tree and the files in each file pane); an untitled window isn't kept when you close it.

A new window's first environment is the one bound to the home folder, else default_env from the settings, else you pick one:

Environments and terminals

The tab strip shows one tab per environment in the window, tinted with its colour (color in its env.toml). A dot on a tab shows its busiest terminal: working, waiting or idle, so a background environment that needs you is easy to spot. + at the end of the strip lists the environments not yet in the window, with New environment… last; choosing one adds its tab with a terminal and selects it.

Down the left side is the selected environment's list of terminals, in the order you made them and grouped by project (terminals in the same repository, its worktrees included, sit together, with a line in the environment's colour between one project's terminals and the next's), each with an activity dot and a close button on hover. In a terminal running Claude, the dot follows what Claude says it is doing, through hooks hydra adds for you, and the row says working, needs you (when Claude is asking a question or for permission) or idle (finished, your turn). When a Claude session out of sight finishes or starts asking for you, its environment tab and row get an amber dot until you look at it, the taskbar button flashes if hydraui is in the background, and a toast names the terminal: click it to go there. Click one to show it. + New at the top (or Ctrl+T) adds a terminal in the same environment, in the environment's root folder (its home, else the folder bound to it), else the shown terminal's folder. A terminal is named after its folder until you give it a name: the name is yours, and a program's own title never replaces it. The button at the left end of the tab strip collapses the list to give the terminal more room, and brings it back.

• Right-click a terminal: Rename… (an empty name goes back to the folder's), Restart (in the folder it was in, so an edited env.toml applies) or Close.
• Right-click an environment's tab: New terminal, Restart environment (all its terminals) or Close environment. Closing or restarting asks first if a command is running, and closing also if a file has unsaved edits.
• Closing a single terminal also asks when a command is running in it. An environment whose last terminal closes keeps its tab, with a New terminal button.
• Ctrl+PageDown and Ctrl+PageUp move between terminals in the list; Ctrl+Tab and Ctrl+Shift+Tab move between environment tabs; Ctrl+W closes the shown terminal.
• Terminals you aren't looking at keep running and keep their scrollback.
• Selecting text copies it, with a brief "Copied" label. Ctrl+V or Ctrl+Shift+V pastes text, and Ctrl+F finds in the scrollback. When the clipboard holds no text, such as a screenshot, Ctrl+V goes to the program instead, so Claude Code can paste the image.
• Scrolled up into the history, a ↓ button appears at the bottom right and jumps back to the latest output.
• Tab and Shift+Tab go to the shell, so PowerShell's completion cycles through matching folders and files.

The status bar shows the shown terminal's environment, its tools with a ✓ or ✗, the git branch and changes (⎇ main · +1 ~2 ?1) and the current folder. If an environment can't start (a missing SSH key, a secret that isn't stored), the pane shows hydra's error and how to fix it, with Retry.

Task board

While Claude is busy in a terminal you will think of what to do next. The task board is a place to jot those ideas down without interrupting it, then pick them up later. Right-click a terminal in the list and choose Tasks: that terminal gets a Tasks tab beside it, with the terminal and Tasks ✕ in a small strip at the top. ✕ closes the tab, and the cards stay. Each terminal has its own tabs, so another terminal shows its own view, and the layout file remembers which terminals have a Tasks tab.

The board belongs to the terminal's project: the git repository its folder is in (a linked worktree shares its repository's board), or, outside a repository, the folder itself. A folder inside a repository, including a home folder that is itself a repository, shares that repository's board, and terminals in the same project show the same cards.

There are five columns, side by side, each with its own color on the dot before its heading and down the left edge of its cards:

• Backlog (grey): ideas not yet picked up. Its + adds a new card at the top.
• Pickup (blue): what you want to explore with Claude next. Right-click a Pickup card and choose Take in new worktree to give it a branch of its own (task/…) in a worktree beside the repository, with a Claude terminal there already working on it; when you move the card to Done, hydraui offers to merge the branch and remove the worktree.
• InProgress (orange): what is being worked on now.
• Verify (yellow): work that is committed and waiting for you to check it.
• Done (green): finished. Its Clear button removes every card in the column, after asking how many.

A card is a short paragraph, with no title and plain text. A card shows its first two lines; click it to see the rest, and again to fold it. Double-click a card to edit it where it is. Enter saves it, Esc cancels, and clicking elsewhere on the board saves it too, as does switching to the terminal tab, another terminal or another environment. Saving an empty card deletes it, and so does the trash icon that shows while the pointer is over a card, after asking. Drag a card within a column or into another, and a line shows where it will land. Right-click a card for Move to any other column (the top of it), Move up, Move down and Delete (which also asks first). Every change is written to the file at once, so there is no Save button. If a save fails, the card stays open with its text and a message says why, and neither the Tasks tab nor the window will close until the save works.

Auto-pickup

Move a card into Pickup and hydraui types it into a free Claude session of that project, then presses Enter. Claude takes the card from the board and gets on with it. A session is free when it is idle, in the project's main work tree rather than a linked worktree, has nothing typed at its prompt, and isn't the terminal you are looking at (unless that terminal's Tasks tab is showing). A session that has clearly finished always counts: it is new, or it has just moved a card to Verify. A terminal restored from a layout, or a session you resumed with claude -c or claude -r, doesn't count as new, since its conversation may end in a question. Without a Jev API key, those are the only sessions that count; with one, Jev also judges the others (idle after other work) and says whether each is waiting for something to do. To judge a session, hydraui sends the last 60 lines of its terminal to TypeSafe's API (api.typesafe.ai). If no session is free, a message says No free Claude session for this card (with the reason when Jev couldn't be asked, such as Jev: HTTP 401 for a bad key) and the card stays in Pickup. When one is sent, you see Sent to terminal in env. A card isn't sent again while it is on its way; moving it out of Pickup and back in sends it again. To see why a card went where it did, or why it went nowhere, open Open hydraui log from the launcher: it lists each terminal and why it was or wasn't free, and Jev's answers with the lines sent.

Right-click a Pickup card for Send to a free session, which does the same on demand, or Send to, which lists the project's idle Claude sessions so you can pick one yourself.

The file

Cards live in .hydra/tasks.md in the project, created when you save the first card. It is ordinary markdown, so you can read and edit it in any editor, and so can Claude. The board watches the file and shows what changes in it, and a change you make on the board is applied to the file as it now is rather than over it, so neither side loses an idea. If the card you were editing was moved, changed or removed in the file meanwhile, what you typed is added as a new card at the top of Backlog and a message says so.

# Tasks

## Backlog
- Let the terminal list show which terminals have unread output, maybe a dot
  that clears when you look at it.

## Pickup
- Ctrl+K should open the launcher from anywhere, including the file pane.

## InProgress
- [hydra] Add the terminal list dot for unread output.

## Verify

## Done
- Collapse button for the terminal list.

• One card is one top-level list item; a long card wraps onto lines indented by two spaces. Headings match whatever the case or spacing, so ## In Progress is InProgress. Checkboxes ([ ], [x]) are accepted and dropped.
• Order in a column is the order in the file, top first.
• Any other text in the file is kept, moved under a ## Notes heading at the end of the file.

Claude and the board

In an environment with a [claude] section, a Claude session running in a hydraui terminal finds the board itself, through a hydraui tool server that hydra adds for you and whose five tools it pre-approves, so Claude doesn't ask permission. Claude can read the whole board, add an idea at the top of Backlog, take a card from Pickup (it moves to the top of InProgress), move a card it took to Verify once its work is committed (giving the commit), and list the cards it took. Reading the board also tells it which other Claude sessions are working in the same project; when there are others, it is told to work in a git worktree of its own so the sessions don't change files under each other. Everything else stays yours: only you move cards into Pickup or Done (so a card goes from Verify to Done when you have checked it), move them back, edit, reorder or delete. A card you move into Pickup is typed into a free session (auto-pickup); otherwise ask Claude to check the board. It is also told to look at Pickup after finishing a piece of work.

A card Claude takes is written - [name] text, and the Tasks tab shows the name as a small badge: click it to go to that terminal. The name is the terminal's title if you gave it one, else the name of the folder it started in, with -2, -3 added if another terminal in the window has the same name. Renaming the terminal changes it; a cd doesn't. A card Claude moves to Verify is written - [name @5e9a827] text: the card shows the commit beside the name, and clicking it opens what that commit changed as a diff in the environment's file pane, so checking the work is one click. Moving a card back to Backlog or Pickup clears the name (and commit), and Verify and Done keep it. The [name] prefix is only read in InProgress, Verify and Done. If a session creates the board file in a git repository, you get the same Keep tasks private? question. To leave an environment out, set mcp.exclude = ["hydraui"] in its [claude] section; outside hydraui the server quietly offers no tools.

Tasks: all projects

At the top of the terminal list, above the terminals, Tasks: all projects shows every project that the selected environment has a terminal in, one swimlane each, in place of the terminal. Each lane is that project's own board, so you can edit, add, drag and send cards just as on its Tasks tab. It shows every column except Done, since it is there to show outstanding work, and the lane's header says how many Done cards it leaves out. A card can't be dragged into another project's lane. Click a terminal, or press Ctrl+W, to go back. The lanes follow your terminals: open one in another project, or cd into one, and its lane appears.

Commit or keep private

In a git repository, the first card you save in a new project asks Keep tasks private?, unless the project's .gitignore already keeps the file out of git: Keep private adds .hydra/tasks.md to the project's .gitignore, and Commit tasks leaves things as they are so the file can be committed. You can change your mind later with the ⋯ menu at the right of the Done column's header, which offers the other choice. If another .gitignore rule already ignores the file, the menu says Ignored by another .gitignore rule instead. The menu, and the question, appear only in git repositories.

Orchestrator

The orchestrator takes one ticket at a time through a pipeline of stages, such as understand and replicate, develop, review and verify. It is a Claude session in a hydraui terminal that coordinates and never does a stage's work itself: each stage runs in a fresh Claude session of its own, which hydraui opens beside you without taking the focus, in the run's own worktree when the stage asks for one. A stage ends by reporting a confidence rating: a score from 0 to 100, the evidence behind it, and its reasons for and against. The next stage can start only once that score clears the stage's bar (80% unless the pipeline or the stage sets its own). hydraui enforces this itself: nothing, no setting and no button, lets a stage past its gate.

Start one from the launcher with Start orchestrator…: pick an environment with Claude configured and a pipeline, and a terminal named orchestrator opens with Claude ready; tell it the ticket. Its run shows as a card at the top of the terminal list: the pipeline's name, the ticket and current stage, a state (Working, Needs you, Paused, Done) and a bar per stage. The run's stage terminals sit under it, named 1. Understand and replicate, 2. Develop and so on, framed under their orchestrator, and the foot of the list shows how much of the environment's seven-day Claude limit is left. Click the card for the Pipeline tab: the ticket's timeline of stages with their gate scores and every session each stage ran, and on the right whichever session you pick, live in its own terminal, or its rating with the reasons and evidence.

When a stage scores below its bar, reports that it is blocked, or fails three times (its session ended without reporting), the run needs you: a toast names the ticket, the stage and why, and the Pipeline tab offers Step into the session to work in it yourself, Re-run the stage with a note for its next session (it still has to clear the bar), or Stop this ticket. Runs also wait when less than min_week_left of the seven-day limit is left (30% by default; see Settings). Pause orchestrator in the title bar holds the next stage until you resume. hydraui types a one-line note into the orchestrator whenever a stage is decided, but only while it is idle with nothing typed, so it never writes over you.

Tickets from Linear. Give a pipeline a [linear] table, or turn on Pull tickets from Linear in its settings: the team's key, the state that triggers a pickup (Ready for Investigation by default, or say Ready for Review), whether to take only unassigned tickets or anyone's, the state a claimed ticket moves to, the state it moves to when every stage passed, and how often to look (every 5 minutes). Then switch the card to Automatic (its pill shows Automatic, Manual or Stopped, with one line on what happens next; in Manual, Pick next ticket picks one and says what it found): while the orchestrator has no ticket, hydraui checks Linear, takes the ticket whose SLA breaches soonest, claims it (assigns it to you if nobody has it, moves it, and comments), and types it into the orchestrator. Check now looks at once. When the run ends, the ticket gets a comment with each stage's score and the PR links, and moves on when every stage passed. Only one orchestrator watches a team. A rejected key, or three failed checks in a row, stops watching with a toast. The card shows the ticket's SLA (amber when close, red once breached) and Open in Linear; Ticket history shows whether each run ended inside its SLA. The environment needs a Linear personal API key: hydra add linear or Add account… → Set up linear….

A pipeline is a file in ~/.hydra/hydraui/pipelines/; hydraui writes an example, ticket.toml, the first time. Pipeline settings under the card edits its name, default bar and stages (order, name, skill, the folder its session starts in, and bar) and keeps each stage's prompt and comments, which you edit in the file itself (Edit pipelines in the launcher). Ticket history lists every run with how it ended and how long it took. Every run is logged to ~/.hydra/hydraui/runs/, and when a run ends its worktree is removed, keeping its branch, unless it holds work that isn't committed. The pipeline never merges: what it opened waits for a person.

File tree and git

Ctrl+B shows the file tree on the right, rooted at the shown terminal's current folder; it follows you as you cd and as you switch terminals or environments. Drag its edge to resize it; the terminal list on the left drags the same way. It respects .gitignore and updates as files change.

• Click a file to open it in the environment's file pane.
• Ctrl+click a file to type its quoted path at the terminal's cursor.
• Double-click a folder to cd there, when the shell is at its prompt.

In a git repository, files show their status: M modified in yellow, A added and ? untracked in green, D deleted in red, ignored files dimmed. A folder that holds changes gets a dot. Right-click a changed file and choose Show changes for a side-by-side diff against the last commit:

Right-click a file or folder for New file…, New folder…, cd here, New terminal here (folders), Reveal in Explorer, Rename…, Delete… (to the Recycle Bin, after asking), Copy path and Copy relative path. Open files follow a rename.

The file pane

Opening a file splits the middle: the shown terminal on the left, the file pane on its right, next to the tree, with a tab per open file. Each environment has one file pane, and it stays beside whichever of its terminals is shown.

• Raw is an editor with syntax highlighting (including C#, Java, SQL, GraphQL, Protobuf, TypeSpec, Dockerfiles and HCL/Terraform), line numbers and find. Ctrl+S saves, keeping the file's line endings and encoding, so a save changes only what you edited.
• Rendered shows Markdown as a page. Markdown files open rendered; the header switches between the two. Links open in your browser, and images load only from local files.
• OpenAPI 3 specs (.yaml, .yml, .json) open as API docs: endpoints grouped by tag. Click one to open it as a card: its parameters and request body as tables of fields, types and rules (required ones marked *), and its responses as tabs, each with Schema or an Example made up from the schema. Copy as curl puts a ready-to-run command on the clipboard, and Go to line shows the endpoint in the file. A filter finds endpoints by path, method, summary or operation id, and Expand all opens every one. Raw shows the file, and your edits show up in the docs as you type; if an edit breaks the YAML, the docs say which line, with Go to line.
• Open in editor hands the file to your editor (editor in the settings, else Windows' default).
• If the file changes on disk it reloads; if you have unsaved edits you get Reload or Keep mine. Closing a file with unsaved edits asks first.
• PNG, JPEG, GIF and ICO images show as pictures, shrunk to fit the pane, with their size in the header; an animated GIF plays. A change on disk shows the new picture. An SVG shows as a picture too, with Raw to edit its text; the picture follows your edits.
• A PDF shows its pages one under another, fitted to the pane's width, with its page count and size in the header. Pages show as they are drawn; the first 300 are shown. A change on disk draws it again. Text can't be selected here: Open in editor opens it in your PDF reader (or your editor, if you set one).
• Other files over 5 MB and other binary files aren't shown, with Open in editor instead.

Finding files

All three search the shown terminal's folder and respect .gitignore.

Clickable paths

Hold Ctrl over terminal output and a path under the mouse is underlined; Ctrl+click opens it at its line. Compiler errors, test failures and grep -n output all work: src/main.rs:42, src/main.rs:42:7, src\main.rs(42,7), even when a long path wraps onto the next row. Web links, such as the URL a sign-in prints, open in the browser the same way.

Quick open Ctrl+Shift+O

Type a few letters of a file's name; matches are ranked so consecutive letters, word starts and the file name count most. name:42 opens at line 42.

Search in files Ctrl+Shift+F

Results appear as you type, as file:line and the line. Aa matches case and .* searches with a regular expression. Enter opens the file at the match.

Accounts

The status bar lists the shown environment's tools, each with a ✓ when its login matches and a ✗ when it's missing or wrong. Click the environment's name to open its page in Settings, with the details checked again as it opens:

• Add account… turns a tool on for the environment, as hydra add does. Tools that only need a sign-in (Claude Code, GitHub, Azure, Google Cloud, Codex, Google Workspace) sign in straight away in a new terminal; git, AWS, Gemini, Jev, Linear and Kubernetes ask for their settings first (Gemini's, Jev's and Linear's API key is stored as a hydra secret).
• Use from… on a tool borrows another environment's login for it, so you sign in once and use it in both.
• Switch account… on a tool runs its sign-in again in a new terminal, to move the environment to another account.
• On a Claude Pro or Max account, the status bar also shows how much of Claude's limits the environment has used: claude 5h 42% · 7d 18%, amber from 80% and red from 95%. Hover it for the account and when each limit resets; click it for the accounts. The numbers come from Claude's own status line, which hydra passes to hydraui; if you have a status line of your own, hydra keeps it and runs it for you.
• A borrowed login says which environment it comes from.

Settings

The gear in the tab strip (or the launcher's Settings) opens Settings in the middle, in place of the terminal; pick a terminal or Close to go back.

• General: default environment and shell, editor, theme, terminal font and size, keyboard shortcuts, the Jev key and questions for auto-pickup, version and updates. Each change is written to config.toml and applies at once.
• Each environment: its label, colour and home, its accounts (as above), its [env] variables, and Delete. A plain value whose name looks secret is masked, with a nudge to store it as a secret.
• Credentials: hydraui's own Jev key, then each environment's secrets with where each is used and whether it is stored, with Set… or Replace…. A secret that becomes a variable has Agents can see: turn it on and describe what it is for, and Claude sessions in that environment find it with the hydra_access tool, which lists the environment's tools and those credentials but never a value. What agents see shows that reply. It is saved as [agents] in env.toml.

The launcher

Ctrl+Shift+P opens the launcher: type to filter, Enter to run.

Layout files

A layout file (*.hydraui) is a window written down: its environments in tab order, each one's terminals (their names and folders) and file pane, the file tree and terminal list widths and what is selected. Each window has one layout, named in its title bar; the name's ▾ menu has Save layout as…, Open layout file…, Recent and Reveal in Explorer. Once saved, the window keeps the file up to date. Opening a layout in a window that already has one opens a new window; opening one that's already open brings its window forward, so two windows never write the same file. With the installer, double-clicking a .hydraui file opens it.

version = 2
active_env = "work"
list = { width = 240.0 }       # optional: the terminal list's dragged width (hidden = true when collapsed)

[[env]]
name = "work"

[[env.terminal]]
title = "claude"                  # optional: the name you gave it
cwd = "E:/work/api"
command = "claude"                # optional, hand-written: runs whenever the layout opens

[[env.terminal]]
cwd = "~/blog"
claude = true                     # written by hydraui: Claude was running here

• An environment that no longer exists, or a terminal whose folder is gone, is skipped with a message but kept in the file.
• Scrollback, running programs and unsaved edits aren't saved, with one exception: a terminal that had Claude Code running when the layout was saved (closing the window counts) starts it again with claude --continue when the layout reopens, picking up that folder's latest conversation.
• Layouts made by earlier versions of hydraui (without version = 2) aren't opened, and the file is left as it is. Sets and group files are gone; ~/.hydra/hydraui/sets is no longer read.

Keyboard shortcuts

The help icon (?) in the title bar (or Keyboard shortcuts in the launcher) lists every key hydraui answers to, with your own [keys] changes.

Change any of them under [keys] in the settings: new_terminal = "ctrl-alt-n", or "" to unbind. Key changes apply the next time hydraui starts.

Settings

hydraui's own settings live in ~/.hydra/hydraui/config.toml. Every key is optional, and a mistake in one is reported without costing you the rest. Reload config in the launcher applies changes without restarting.

font = "Cascadia Mono"          # the default
font_size = 14
theme = "dark"                   # or "light": hydraui's own controls
default_env = "work"             # for new windows in folders nothing is bound to
default_shell = "pwsh"           # or "bash"
editor = "code"                  # for Open in editor
min_week_left = 30                # % of the seven-day Claude limit a pipeline stage needs left

[colors]                          # the terminal's colours, #rrggbb
background = "#0b1116"

[keys]
new_terminal = "ctrl-alt-n"

[colors] also takes foreground, cursor, selection and palette, a list of the 16 ANSI colours.

Updates

The title bar shows the version you're running (hydra version) on the right. hydraui checks GitHub for a new release when it starts and every hour after, and the launcher's Check for updates (Ctrl+Shift+P) checks straight away and says what it found. When there is one, the title bar shows Update hydra version beside the version:

1. Clicking it downloads hydraui.exe and, if it finds your hydra.exe (next to hydraui, or on your PATH), that too, and checks both against the release's SHA-256 checksums. It won't update while a hydra command is running.
2. Nothing is replaced until everything has downloaded and checked out; if replacing one fails, the other is put back.
3. The button becomes Restart to finish. Restarting reopens your layout (an untitled window is saved first), but stops what's running in it, so it's always your call.

Builds you compile yourself never offer updates.