Hive Desktop User Guide

Hive Desktop (Hive for short) is a desktop workspace for coding with AI agents. It runs coding agents (Claude Code and Codex) for each project you're working on, side by side, and keeps track of what each one is doing, how many tokens it uses, and the skills and MCP servers it has.

Getting started

1. Install Hive Desktop. Download Hive-Setup-<version>.exe from the latest release and run it: it adds Hive Desktop to the Start menu and the desktop. The installer isn't code-signed yet, so Windows SmartScreen may warn you; choose More info → Run anyway. From then on Hive keeps itself up to date (see Updating Hive).
2. Choose your coding agents. Hive runs the standalone command-line tools of Claude Code (Anthropic), Codex (OpenAI) and GitHub Copilot (GitHub); they aren't included with Hive. A new install starts with all of them turned off: turn on the ones you use in Settings → Providers (the banner at the top links there). Help → Agent Setup… finds each CLI and offers a one-click install with the official installer if it's missing, and walks you through signing in (and, for Codex, its one-time Windows sandbox setup). The copies inside VS Code (or Cursor) extensions are not used. See Coding agents.
3. Open or create a workspace (File → Open Workspace… or New Workspace…). A workspace is any folder whose subfolders are your projects.
4. Mark the projects you're working on with the toggle next to each project.
5. Add an agent and start it. A new project has no agents: New Session (Ctrl+Shift+N) adds one with your default provider and starts it, or use Add Agent above the terminal. The agent opens in the Session tab. Switch to another project and start another — sessions keep running in the background.

Tips

Hive shows a tip about something it can do when it starts, at most one a day, in a small card in the bottom-right corner: Try it does it, Learn more opens the part of this guide about it, and Next tip shows another. A few tips come at the moment they help, once each: the first time a transcript turns amber, the context passes your Compact threshold, you add a second agent, or you paste a screenshot. Tips about things you already do are skipped. The card never blocks anything: it steps aside while you type in a terminal under it, sits left of the Assistant's panel while that is open, and moves up above a bar with buttons (such as Resume and New when a conversation has ended). Don't show tips turns them off (Settings → General → Show a tip when Hive starts turns them back on); Help → Tips… lists them all, searchable, either way.

With several Hive windows open, they share what the tips remember: a tip seen, the day's tip shown, a moment's tip used or a command you've run in one window counts in all of them, and stays that way after a restart. Another window doesn't show you the same tip again.

Moving dialogs

Any dialog (Add Agent, Agent Settings, a card, a question…) can be moved out of the way: drag it by its header. It stays inside the window, and Escape while dragging puts it back. A dialog opens in the middle again next time. A question over a dialog moves on its own, and Escape closes just the question. The image viewers stay where they are. When a dialog closes, the keyboard goes back to what had it before, such as the button that opened it. Pressing Enter to confirm a name (New Mode…, a rename) never presses that button again, so the dialog doesn't reopen.

Search and filter boxes

Every search and filter box (the board's search, Settings, the Files and Sessions tabs, the sidebar's filters, tables' filters, Tips, Keyboard Shortcuts and the command palette) shows an × at its right while it has text: click it, or press Escape, to clear it and see everything again; the cursor stays in the box. In a dialog or the command palette, the first Escape clears the box and the next one closes it.

Coding agents: Claude Code, Codex and GitHub Copilot

Hive calls the coding agents it can run providers. Each agent in a project chooses its own, so a project can have a Claude Code agent and a Codex agent working side by side. Hive shows each CLI's own terminal, exactly as it looks when you run it yourself.

• Turning providers on and off. Settings → Providers lists them with their install state. A provider that is off can't start agents; its agents stay listed, greyed out. Turning one off while its agents run asks whether to stop them now or let them finish. Default provider is what new agents use (a project can choose its own in Project Settings). It starts as Automatic: new agents use the first provider that is turned on and installed (Claude Code, then Codex, then GitHub Copilot), so if you only use Codex or Copilot, nothing asks you for Claude Code. Choose a provider instead to always use it; if it's turned off or not installed, an empty project says so. A project with no agents warns only when no coding agent is installed (or none is turned on). Hive's banner, the status bar and Agent Setup flag a missing CLI only once something uses it: a provider that is turned on but not installed, which neither your default nor any agent uses, just shows as "not installed" in the status bar. If you chose a default that is turned off, Add Agent keeps it chosen and says so: turn it on, or choose another provider. Just after Hive starts it is still looking for the CLIs: Automatic shows as Automatic (checking…), and anything that needs it (Add Agent, New Session, starting the Assistant) waits a moment for the answer rather than guessing, so it never picks Codex just because Codex answered before Claude Code. If Hive is still looking after about 20 seconds, it says so and does nothing: try again in a moment.
• Setup. Help → Agent Setup… has a tab per provider: install, sign in, and updates. Claude Code signs in with a Claude plan or an Anthropic Console account; Codex with a ChatGPT plan or an OpenAI API key; Copilot with a GitHub account that has a Copilot plan (see GitHub Copilot). On Windows, Codex also needs its sandbox set up once (without it, Codex asks before every command); see Codex's Windows sandbox. No restart after an install: installers add their folder to your PATH and often say to restart your terminal. Hive needn't restart: when an install ends (and with Check again) it looks again on the PATH Windows gives new programs, shows the CLI installed, and agents you start from then on can use it. Agents, Agent Setup's terminals and Open External Terminal Here also get that PATH whenever Hive starts them, so something you installed outside Hive is there too. Agents already running get the new PATH when they restart.
• Settings per provider. Each provider has its own page (Settings → Claude Code, Settings → Codex): the CLI's path, default model, effort and permission mode, extra arguments, update checks, the fallback lists of models and effort levels, and its price table (see Models, effort levels and prices). Settings → Claude Code → Use 200K context (instead of 1M) is off by default: current Claude models have a 1M-token context window, and turning this on holds sessions to 200K, so Claude Code compacts a long conversation sooner and each message sends less. Projects and agents can choose for themselves, and it applies to sessions started afterwards. Settings → Claude Code → Allow background sessions is off by default: in Claude Code, pressing ← on an empty prompt (easy to do while moving through text) opens its agent view and moves the session into Claude Code's background service, where Hive can no longer see or stop it. Hive turns that off for the sessions it starts; claude in your own terminals is unaffected. If a session is in the background anyway (you turned the setting on, or moved it there outside Hive), resuming it shows a notification with Stop It and Resume, which stops Claude Code's background job and resumes the conversation here. Projects override them per provider in Project Settings.
• The icons on agent tabs, pane headers and the Sessions list show which provider each agent and session uses.
• Conversations stay with their provider. A Claude Code session can only be resumed by a Claude Code agent, and a Codex session by a Codex agent. To move work to another provider, use Hand Over to… (see Sessions).
• What both share. The workspace's Hive skills (those for project agents), its MCP servers and Hive's own hive tools reach every agent, whichever provider it uses. Neither CLI loads MCP servers from your user settings in Hive sessions. Hive never changes either CLI's own configuration files.

GitHub Copilot

Hive runs the GitHub Copilot CLI (the copilot command), not Copilot in VS Code. Any Copilot plan includes it, Copilot Free too. Turn it on in Settings → Providers, then choose GitHub Copilot when you add an agent. Its agents get what the others get: statuses, file locks, the hive tools, the workspace's skills, sessions you can resume, usage and cost.

• Installing. Help → Agent Setup… → GitHub Copilot → Install runs winget install GitHub.Copilot in a terminal. Installed with npm (npm install -g @github/copilot) works too. Agent Setup shows the version it found and how (WinGet, npm, PATH, or the path in Settings → GitHub Copilot). Update goes through the same installer. Hive's Copilot agents run the installed version, so a version copilot update downloads on its own isn't used.

• Signing in. Signed out, Sign in opens copilot login in a terminal: it opens GitHub in your browser to authorise Copilot. With copilot login --device-code, you enter a code on GitHub instead. Hive never signs in for you.

• Which sign-in Hive uses. Agent Setup says who Copilot is signed in as, and how, in the order Copilot itself checks:

  • COPILOT_GITHUB_TOKEN: a token you set in your environment for Copilot (a fine-grained token with the "Copilot Requests" permission) comes first. Agent Setup can't tell whose it is.
  • Copilot login: your own copilot login (the account comes from Copilot's settings; the token stays in Windows Credential Manager).
  • GitHub CLI: with no login of its own, Copilot uses the GitHub CLI's (gh auth login).

  Copilot would also take GH_TOKEN or GITHUB_TOKEN, but Hive doesn't pass these to Copilot agents: other tools set them, and they shouldn't sign Copilot in by accident. When Copilot is signed out and one is set, Agent Setup says so. Hive only checks whether a token variable is set, never what it holds. It reads only the account names in Copilot's settings, and never asks the GitHub CLI for its token.

• Modes. Accept edits (the default) edits files in the agent's own folder (the project, or its worktree) without asking, and asks before other commands, other MCP tools, web access and changes anywhere else. Copilot can't approve edits in a folder whose path has parentheses (New folder (2), Program Files (x86)): there an agent in Accept edits asks before each edit, as in Ask, and Hive tells you so when it starts. Ask reads files and runs harmless commands without asking, and asks before edits too. Plan plans the work and asks before changing anything. Allow all approves every tool, path and web request without asking, in the agent's folder and outside it: choose it knowing that. Autopilot is Allow all that also carries on by itself until the task is done, without handing back to you: once a turn has run in it, Copilot approves everything for the rest of the session, even after you switch out of it (Copilot says Permission policy: Allow All for this session, and Hive's mode badge then shows Allow all). Autopilot appears only after you tick Settings → GitHub Copilot → Enable the Autopilot option (turning it off moves projects and agents using it back to Inherit). In every mode, Copilot uses Hive's own hive tools without asking, as Claude Code and Codex agents do (Settings → Agent API decides what they may do). See Permission modes. Shift+Tab in its terminal switches to Plan and Autopilot and back while it runs; switching between Accept edits, Ask and Allow all needs a restart (and after Autopilot, Ask and Accept edits need one too). In Accept edits, Copilot's own footer still says Manual Approval: Hive starts it with edits in the agent's folder approved, which Copilot's label doesn't show (the mode badge's tooltip says so too). The mode has taken: Hive's footer shows the mode the agent runs in.

• Trusting a folder. The first time Copilot starts in a folder, it asks in its terminal whether you trust the files there. The agent shows as waiting for you until you answer.

• Instructions. Copilot reads a project's AGENTS.md, CLAUDE.md and .github/copilot-instructions.md. It also runs the hooks in a project's .claude/settings.json, as Claude Code does.

• Models. Copilot Free uses Auto only (Copilot picks the model). Choosing a model needs a paid plan; Agent Setup reminds you, since Copilot can't tell Hive which plan you have.

• Cost. Copilot counts usage in AI credits (one credit is $0.01), not tokens. It writes a session's token totals only as it exits, so Stop ends a Copilot agent as you would, with Ctrl+C (it takes a second or two), and the Sessions tab keeps its tokens. If Copilot doesn't exit, Hive ends it after 10 seconds (Settings → Advanced → Stop: exit grace, under GitHub Copilot). Your plan's monthly allowance is in Copilot's /usage.

• "Third-party agents" on Copilot Pro. Pro's Claude Code and Codex agents are GitHub's cloud agents, which work on issues and pull requests on github.com. They aren't the local CLIs: a Copilot plan doesn't sign in Hive's Claude Code or Codex agents. With Copilot, Hive's Claude and GPT models come through Copilot agents (on a paid plan).

Git

Worktree agents, merging, the Git tab, the unmerged counts on agent tabs, agent templates with worktrees and Remove All's clean-up all use git. Install Git for Windows, version 2.38 or later (git-scm.com). Help → Agent Setup… shows a Git row under every tab: the version Hive found and where, or Git not found with how to fix it and a Git for Windows button. With an older git, the row says what doesn't work (for example, squash-merged branches still count as unmerged, so their worktrees are kept).

Hive uses the git on its own PATH, together with the PATH Windows gives new programs. If you install git while Hive is open, or add its folder to your PATH, click Check again: no need to restart Hive. While git is missing, the status bar shows Git in red, and the screens that need it say "Git isn't installed (or isn't on Hive's PATH)" rather than that the project isn't a git repository. Hive never deletes a worktree or branch it can't check with git: they're kept, and it says why. Claude Code also uses Git for Windows' Bash for its commands when it's installed (else PowerShell).

Tested CLI versions

Claude Code, Codex and Copilot update on their own schedule, and a new version can change what Hive relies on. Each Hive release says which version of each it was tested with: Help → Agent Setup… shows it under the CLI it found, as Tested with 2.1.287 · installed 2.1.290.

• The same version: a tick.
• Newer than tested: "This version came out after this Hive release was tested. Most updates work; if something behaves oddly, report it (Copy Diagnostics)." Nothing is blocked.
• Older than tested: "Older than tested; consider updating."
• Version unknown: Hive says it couldn't tell which version is installed.

Help → Copy Diagnostics lists the tested and installed versions for each CLI, so a bug report says how they compare, and the Hive Assistant can see them too when you ask it about a CLI behaving oddly.

Models, effort levels and prices

Hive asks each CLI which models it has and what each can do, so a new model, or one your plan now includes, shows up without waiting for a Hive update. Claude Code and Codex answer for your installed version and your account (asking uses no tokens, and never starts a session). Settings → <provider> → Models (fallback) says where the models come from now, for example From Claude Code 2.1.289.

• Model pickers list the models the CLI reports; any other model can still be typed as a custom model ID.
• Effort pickers offer the levels the chosen model takes: Haiku 4.5 has no effort setting, Haiku 5.5 takes low, medium, high, xhigh and max (as Claude Code reports them), Opus 4.6 stops at Max, GPT-5.5 at Extra high. An effort you chose that the model doesn't take stays chosen and is marked (not offered with …), with a warning; Hive doesn't change it for you.
• Default effort. With no effort chosen, the agent's footer and the pickers show the model's own default once the CLI has said what it is, for example Medium (default).
• When the CLI can't be asked (not installed, an older version, an unexpected answer), Hive uses the fallback lists in Settings → <provider>: Models (fallback) and Effort levels (fallback). You can add, remove and rename entries (mark a model Older to keep it behind Show older versions), and Reset to defaults goes back to Hive's own list, which then follows Hive's updates. The lists stay folded while the CLI's answer is in use; Show the list opens them.
• API prices are Hive's starting prices, labelled with the date they were checked: edit any that are out of date, add a model, remove one, or Reset to defaults. Hive never fetches prices. Each table also lists the models the CLI has, so a model a CLI update adds appears on its own, marked No price: enter one until you do (its sessions' cost shows as unknown meanwhile, never $0). A model Hive has a price for that the CLI no longer lists stays, greyed and marked not in <provider>'s list, for older sessions. Codex doesn't report costs, so its table is the only source of its estimates, and the page links to OpenAI's pricing to check them against.
• Session costs (Claude Code and GitHub Copilot, which report each session's cost themselves): <provider>'s reported cost (the default) uses the CLI's own figure. It follows the CLI's own price table and updates with the CLI; Hive never recomputes it, even when that table lags a price change. My prices (the table below) uses Hive's estimate from the table instead, for your own rates (a discount, another tier). Either way the table is used for sessions with no reported cost. Haiku 5.5's starting price covers prompts up to 100,000 tokens and five-minute cache writes. Longer prompts cost five times as much, and one-hour cache writes ($0.20 per million) are not modelled, so Hive's estimate for such sessions is low. Where Claude Code reports a cost, that figure is the one to trust.

Workspaces and projects

A workspace is a folder of projects. When you open one, Hive creates a .hive folder in it:

MyWorkspace/
  .hive/
    shared/       notes, instructions and handovers for every project
    skills/       Hive skills (one folder per skill, Hive's own included)
    mcp/          MCP server definitions (one .json per server)
    tasks/        the task board (one .json per card)
    workspace.json
  ProjectA/
  ProjectB/

The workspace .hive folder is meant to be committed so a team can share skills, MCP servers and notes. Don't put secrets in it.

Each project (every subfolder except dot-folders) gets its own .hive folder for Hive's metadata: project settings, the session list and transcript backups. Hive adds it to the project's .git/info/exclude, so it's never committed and your .gitignore is left alone.

What Hive keeps in a project

A project's .hive folder is this computer's, not the project's: its settings, the session list, transcript backups and archive, attachments (files pasted or dropped into sessions), and each agent's launch folder (the skills, MCP servers and hooks it started with). None of it belongs in commits or shared copies. What could hold a secret isn't kept there at all: the key the hooks use to report an agent's status, and each session's settings and MCP server configuration (which may carry your servers' keys or a --settings file's env), go in Hive's own data folder instead, for as long as that session runs.

Hive keeps .hive out of git by adding it to the repository's .git/info/exclude, never your .gitignore. It checks again whenever it refreshes the project and before every agent starts, so a repository you create later (git init), or one in a folder above the project (a workspace kept in git), is covered too.

Where Hive can't do that, the project's Overview and Project Settings say so:

• No git repository: nothing is excluded yet. If you use another version control system (Mercurial, Subversion and others are named), add .hive to its ignore list.
• A sync service (OneDrive, Dropbox): it copies the whole project folder, .hive included. Exclude .hive there if the service lets you, or keep the project in a folder it doesn't sync.
• A git repository that still doesn't ignore .hive: Hive couldn't write its exclude file, or a rule in a .gitignore (a line starting with !) brings .hive back; Hive asks git itself, so it notices. Exclude tries again and says which. Hive never edits your .gitignore.
• Files in .hive already committed to git (with git add -A before Hive excluded it, say): excluding only keeps new files out, so git goes on tracking these and committing their changes. The notice says how many, and the command that fixes it: git rm -r --cached .hive in the project folder, then commit; the files stay on disk. Untrack… does it for you after listing the files, and only for those: if git tracks other files there by the time you confirm, nothing changes and it says so (it stages their removal; you commit it). Hive checks again whenever the repository's index changes, so the notice goes once they're untracked, whoever did it.

The Overview's notice has ✕ to stop showing it for that project; it comes back if the situation changes, and Project Settings always shows it.

Recent workspaces

File → Open Recent and the welcome page list the 12 workspaces you opened last, the most recent first.

• Remove one with its ✕ (on hover) or by right-clicking it → Remove from Recent. Only the list forgets it: the folder is left alone.
• File → Open Recent → Clear Recently Opened… (also in the command palette) forgets them all, after asking; workspaces open in a window stay.
• A folder that isn't there any more (moved, deleted, or on a drive that isn't connected) is greyed, with not found. It stays in the list, since a drive may come back. Opening it says it can't be found and offers Remove from Recent.
• A workspace open in another window says open in another window; choosing it brings that window forward. The same goes for the folder by another name (through a junction or a link, or a short name such as C:\Users\RUNNER~1\…): Hive goes by where the folder really is, so a workspace is never open in two windows, and opening the one a window shows by another name keeps it as it is.

Every window's list follows a change made in another.

Moving a workspace

Move the workspace folder (in Explorer, to another drive…) while Hive doesn't have it open, then open it from its new place. A few things are kept by full path and still point to the old folder: agents' worktrees (and git's links to them), the folders sessions ran in, and Claude Code's conversations and memory, which it files under each folder's path in ~/.claude/projects. Hive notices and says so in a banner, This workspace was moved from … (the same folder opened by another name, through a junction or a short name, hasn't moved, and brings no banner). Repair… shows what it will do, and does it when you choose Repair:

• Worktrees. Hive keeps them in a folder beside the workspace (<workspace>.worktrees). Move that folder along, or leave it where it was: Repair finds each agent's worktree either way and links it to the moved project again (git worktree repair). One it can't find is listed: Recreate worktree makes it again on the agent's branch, which is kept in the repository, with its commits (Create a new worktree when the branch is gone too); or Locate… its folder; or Remove the agent's worktree link (the agent then works in the project folder; the worktree's folder, if it turns up, is left as it is). Locate or deal with every missing worktree you mean to keep before recreating another: recreating tidies git's list of missing worktrees, which would lose the links a moved one still needs, so Repair refuses and says which.
• Sessions point to the new folders, so they resume where they ran.
• Claude Code's conversations and memory are copied to the folder for the new path, so agents keep what they remembered. The old folders stay, and a file already there is never overwritten (Repair lists it).
• Open Recent lists the new folder instead of the old one, and the projects you had marked Working on are marked again.

Stop the workspace's agents first: Repair waits until none is running. It never moves or deletes anything at the old place, and running it again repeats nothing it has done. A file it couldn't copy (a folder it can't write to, say) is listed, and the banner stays: Repair tries it again, after a restart too. A file of Claude Code's that is already at the new place with other content is shown and left as it is. A project folder renamed or moved into the workspace on its own is repaired the same way. If the workspace was copied rather than moved, worktrees left beside the original stay with it.

The banner's ✕ hides it for now; Repair Moved Workspace… in the command palette opens Repair until it's done.

Renaming a project. Rename or move a project folder within the workspace (in Explorer, while no agent of it runs) and its cards go with it: on the board and in Archived they show under the new name, with their agents. So do lane records, agents' card and agent watches, and a merge left half done when Hive closed (the warning names the project as it is now), because Hive names a project by an id kept in its own .hive folder, not by the folder's name. Watches also come along when you move the whole workspace folder. The project also keeps its handovers (an agent picking up still finds its latest one), its Performance history, its kept comparisons, its Progress runs, and how you left its Skills and Sessions tabs, also when two projects swap names; a new project that takes the old name starts without them. If Hive couldn't move them at once (a file in use, say) and you rename the project again meanwhile, they follow it to its newest name. Hive keeps the projects' names in .hive/project-names.json and whose each handover is in .hive/handover-owners.json. That holds when two projects swap names, and when a new folder takes the old name: the cards stay with the project they were made for. A copy of a project folder gets an id of its own and starts with no cards. If a project leaves the workspace and another folder takes its name, its cards show as name: gone: they aren't the new project's, and you can give them to a project in the card. The first time Hive opens a workspace with ids, it keeps a copy of each card, of lanes.json and of watches.json it changes beside it (….before-ids.bak). Cards saved by Hive 0.5 and earlier, before projects had ids, still name their project's old folder. When a project like that was renamed, the banner says so ("9 cards of hive-website belong to website"), and Repair gives them to the project they belong to now: the project renamed from that name, or else the one whose agents worked on them. Each card's history says so, and an archived card keeps the date it was archived. Repair also gives that project the handovers and kept comparisons saved under its old name; if it can't, it says so and the next Repair finishes it. An older handover whose project name is now another project's goes to the project whose conversation wrote it; when nothing tells which, it is left out of both rather than guessed.

A worktree folder that's gone. If an agent's worktree folder was deleted (after its work was merged, say) or never came along (a workspace copied to another computer), starting the agent offers to Recreate the worktree on its branch, with its commits, at the same place; the project's worktree setup command runs first, as for a new worktree. When the branch is gone too, it offers a new worktree on it from the branch it started from, or to remove the agent's worktree link. If the old place can't be used (a drive that isn't connected), the worktree goes where Hive makes new ones, and the agent's sessions follow it.

Several windows

Like VS Code, Hive can show several workspaces at once, each in its own window: File → New Window (Ctrl+K Ctrl+N) opens one on the welcome page, where you open or create a workspace. Each window is a full Hive with its own projects, agents, shared notes, skills and MCP servers; settings, the tray and updates are shared.

• Open Workspace replaces the workspace in the current window. If its agents are running, Hive asks first (Switch workspace?), then stops them; to keep them running, open the other workspace in a new window instead. If the workspace is already open in another window, that window comes forward instead, so two windows never run agents on the same project. A folder inside a workspace open in another window (or one containing it) can't be opened as a workspace: its projects would belong to both.
• File → Close Workspace stops every agent in every project of the workspace, asking first (Close this workspace?), and keeps the window open, on the welcome page.
• Closing a window (its X, or File → Close Window, Ctrl+Shift+W) closes its workspace and stops its agents, asking first as quitting does (Close this window?). Closing the last window keeps Hive in the tray, or quits Hive (asking first) when Settings → General → Close to tray is off.
• Quitting (File → Exit, Ctrl+Q, or the tray's Quit) stops the agents of every window. With several windows open, the menu says Exit Hive (all windows), and its dialog says it closes them all and lists the agents under their workspaces (two workspaces with the same folder name also show the parent folder that tells them apart; hover a workspace for its full path); Close this window only there closes just the window it is shown in, as Close Window does. When Hive starts again, it reopens the windows that were open, each with its workspace, where they were. A window that wouldn't fit on its display (it was last on a larger one, or that display is gone) is made smaller and moved onto the display, as is a new window; only a display smaller than Hive's smallest window (900 × 560) leaves part of it off the display.
• Notifications and the tray menu take you to the window showing the project.

Always on Top

Keep a Hive window above your other apps, so a test run, an emulator or a browser can work underneath without covering it: click the pin in the title bar, just left of the window buttons, or use View → Always on Top (Ctrl+Alt+O), or the command palette. The pin is lit, and the menu item checked, while the window stays on top; click it again to turn it off.

• Each window has its own. Pinning one window leaves the others as they are.
• It's remembered with the workspace. Reopen the workspace, or start Hive again, and its window is on top again. A new window, and a workspace you never pinned, start off; so does the welcome page.
• It's your desk's preference, kept by Hive on this computer, not in the workspace's .hive folder: someone else opening the same workspace isn't affected.
• On top means above other apps' windows. Windows' own system screens (sign-in prompts, the Start menu) still come in front.

Working on a project

The switch next to a project marks it as one you're working on. Only active projects run sessions, show live status and send notifications, so a workspace with dozens of projects stays quiet. Turning a project on never starts a session by itself.

Status dots:

A pulsing dot changes shade rather than fading, so it stays easy to see. Hive's grey text (timestamps, counts, hints) and its orange text and icons are drawn to be readable in both the light and dark themes, on hovered and selected rows too (they meet the WCAG AA contrast level).

The sidebar and the lists in the Sessions, Files, Git (Changes) and Memory tabs can be made wider or narrower by dragging their right-hand edge, as can the two halves of a split view in the Files tab. Double-click the edge to reset it. Hive remembers the sizes. When the Git tab's Changes has little room (a narrow window, with the sidebar and panels open), its list gets narrower to leave room for what you selected, and with less room still it moves above it, so the changes or the unused worktrees always show.

A project's tabs (Session, Overview, Performance, Tasks and the rest) shrink to icons when their names don't fit, as in a narrow window or with the sidebar and panels open; the tab you're on keeps its name. Hover a tab for its name and shortcut. They get their names back once there's room. In a very narrow window the tabs scroll sideways, keeping the one you're on in view.

Removing a project

Project → Remove Project… (also in a project's right-click menu and the ⋯ at the top of a project) offers three ways. The dialog lists what each one touches: running agents (stopped first; their conversations are kept), the folder, the project's handovers, its cards on the task board and its worktrees.

• Hide: Hive leaves the project out until you restore it. Nothing is moved or deleted; its cards are archived meanwhile.
• Remove from Hive: the folder stays on disk, and its handovers and cards are packed into it (.hive/removed), so you can move it somewhere else, or into another workspace. Wherever Hive sees the folder again, the project shows a banner offering to Restore them (or Discard them). A worktree can't go with the folder: if one has work that isn't merged yet, merge or discard it first.
• Delete: the folder, its worktrees and its handovers go to the Recycle Bin, and its cards are deleted. Type the project's name to confirm. If something has a file in the folder open for a moment (an antivirus scan, say), Hive waits a moment and tries again. If a program keeps it open (a terminal, an editor), Hive says so and deletes nothing: close it, then delete again. Every other delete to the Recycle Bin in Hive tries again the same way.

The coding agents' own transcripts (in ~/.claude and ~/.codex) are never touched. Settings → Workspace lists the hidden and removed projects, with Restore, which brings each back with its cards (and, for a removed one, its handovers). If a removed project's folder has left the workspace, Forget stops listing it.

Compact project list. To give the terminals more room while keeping an eye on every project, collapse the Projects sidebar to a narrow rail of status dots: click the ‹ chevron at the top of the list, press Ctrl+Alt+B, or drag the sidebar's edge almost all the way left. Each project shows as a tile with its initials and status dot; hover it for the name, status and a table of its agents (each one's state, its card and what it waits for, a builder beside its reviewer), click to open it, right-click for the usual menu. Click › at the top of the rail (or press Ctrl+Alt+B again, or drag the edge out) to get the full list back. Shared Notes, Skills and MCP Servers always open at full width.

Sessions

Each agent of a project runs one session at a time (most projects have just one agent; see Several agents in one project). A project without agents shows No agents yet: New Session and Resume add one for you.

Where things are. The project header is about the project: its name and combined status, the Active switch, Resume All Agents while any stopped agent has a session to resume (running agents are left alone, except those an expired sign-in stopped, which it tells to carry on; if one can't resume, a notification says which and why, and the others still resume), Stop while any runs (it lists them and asks first), Start New and Archive and Start New, Remove All, and ⋯ for Explorer (reveal the folder), Terminal (open an external terminal there), Project Settings and Remove Project….

With several agents, each of these buttons says how many agents it acts on: Stop (3) stops the three running agents, Resume All Agents (2) resumes the two stopped ones, Start New (6) and Archive and Start New (5) the agents their question lists. When the header runs short of room (a narrow window, the side panels open, or a language with longer words), the buttons fold step by step as soon as their labels no longer fit beside the project's name: first Start New and Archive and Start New become icons, then Resume, Stop and Active too (Remove All moves into ⋯), then Start New and Archive and Start New move into ⋯ as well. The count stays beside each icon; hover for what it does. The project's name and status are cut with "…" only once the buttons have folded as far as they go. Each question lists its agents as a table: what each is doing, its card, its worktree, and what happens to it (stopped first when it's running, in amber when that interrupts something).

Each action has its own colour wherever it appears, in the project header, the agents' panes and menus, the Assistant and the questions that ask before it: Stop is red, Remove violet, Start New (and New Session) green, Archive and Start New teal and Resume amber.

Fresh sessions for every agent. Start New gives every agent of the project a new session at once: it lists them and asks once, saying which are in the middle of something (a working agent is interrupted). Running agents are stopped first; their conversations stay in the Sessions tab, to resume later. Archive and Start New does the same for every agent that has a session, archiving each one first (as an agent's own Archive and Start New… does), so the old transcripts move to the project's .hive/archive. If an agent can't start, one notice says which and why; the others still start. Both are also in the Session menu and the command palette. Agents are added from the agent strip's Add Agent button. Everything about one agent is on its own pane, whether a project has one agent or four:

• The agent header: its status, provider, name, a worktree icon if it works in its own worktree (hover it, or Tab to it, for the branch and folder) and card, then its buttons: Compact and Stop while it runs; Resume, Resume a Session… and New Session when it doesn't; Merge for a worktree agent; and ⋯ with everything else. Compact, Stop and Merge are always small icon buttons (hover for what they do; Merge shows its count of work not merged yet beside its icon); as the pane gets narrower the other buttons show only their icons too, then they all fold into ⋯, and they get their labels back as soon as there's room again. In a narrow pane the agent's name, branch, status and card shorten (hover for the full text) so the buttons always fit. While the conversation is compacting, Compact shows a turning spinner until it has finished.
• The agent footer: its model and effort (click for Agent Settings), its permission mode (click to switch), and on the right the session it's running (its icon: hover for its name), the context it uses, with how full the model's context window is once the CLI has said (84k · 42%: the last request's input plus its output, thinking included, which is what the CLI compacts on, so a turn that thinks a lot shows at once; hover for the two parts and where Claude Code compacts by itself: by default about 167K of a 200K window (967K of 1M), or as its settings change it, which the tooltip names: an auto-compact window set with autoCompactWindow (also per model), --autocompact or CLAUDE_CODE_AUTO_COMPACT_WINDOW, an earlier percentage, or auto-compaction turned off (autoCompactEnabled, DISABLE_AUTO_COMPACT, DISABLE_COMPACT), whether those variables come from the environment or from the env block of a settings file, and a --settings file or JSON in the agent's own arguments (only the settings files Claude Code reads: --setting-sources and --restricted in the agent's arguments leave some out); Hive reads them when the session starts and never changes them, says it's an estimate when it couldn't read one or can't tell which Claude Code reads (with --safe-mode or --bare), and calls Claude Code's default an estimate, since managed policies it can't read (Windows registry policies, your organisation's settings) could change it; amber past your Compact threshold; click to see the session in the Overview, with its compaction history, as its tooltip says), the size of the conversation's transcript (amber past Settings → Sessions → Warn when a transcript is over; click for Hand Over to…) and the session's cost (click it to see the session's details in the Overview: that agent's session, scrolled to). In a narrow pane, items show just their icon to make room, in turn: the transcript size, then the context's tokens, then the whole context (hover any of them for the figures); then the permission mode's name shortens, and only in a very narrow pane is the cost cut off.
• Silent · state unknown: an agent's status follows its CLI's turns. When Hive has heard nothing of a turn for five minutes and sees no sign that it ended (no word from the CLI, nothing in its own records, no idle prompt on its screen), the header says Silent 23 min · state unknown instead of guessing. Nothing is typed into it meanwhile, and the Assistant doesn't give it work. If its terminal shows it waiting at its prompt, click Mark idle; anything the agent does next puts it back to Working… by itself.

The status bar keeps what concerns the whole app: the workspace, branch, running agents (hover for a table of them: project, state, card and what each waits for), the agents that need you (see Agents that need you), plan limits, the Agent API, each CLI's version and Hive's updates.

An agent's header and the Session menu let you:

• New Session — start fresh. If one is running, Hive stops it first (after asking).
• Resume — continue a previous conversation. If the prompt cache has expired, Hive shows how many tokens resuming will re-cache and offers Archive and Start Fresh instead. A new agent can resume sessions whose agent is gone (for example after the upgrade to 0.2, which starts every project without agents).
• Stop — end the session. The conversation is kept and can be resumed.
• Compact — summarise the conversation so far so every later message is cheaper. Available once the agent has finished; it turns orange when the context passes your threshold (Settings → Sessions → Suggest compacting above, 200,000 tokens by default, and overridable per project in Project Settings). The Hive Assistant has its own threshold, since it usually runs a bigger context: Settings → Assistant → Highlight Compact over, 500,000 tokens by default. You can add an optional focus ("keep the API decisions, drop the test output"); left empty, the agent decides what to keep. Nothing is lost: the full history stays in the session's transcript. Anything you had half-typed is cleared first; press Ctrl+Y in the session to get it back.
• Hand Over to… (agent menu) — hand this agent's work to another agent of the project, which may use another provider, or to the agent itself in a new conversation (see Long conversations). Hive asks this agent to write a handover (if it's running and idle; untick to use the latest handover instead), then starts the other agent, or messages it if it's already running, and tells it to read that handover and carry on. Hive waits for a handover from that agent's own conversation, so one another agent writes meanwhile isn't picked up. Every handover an agent writes starts with a header Hive fills in: the project, the author (the agent and its CLI, e.g. Claude (Claude Code)), the session it was written in (to resume it with questions) and the date, in your time with UTC in brackets. The new session shows a handed over badge in the Sessions tab that links back. It needs Settings → Agent API → Provide Hive tools to sessions. If the other agent's CLI asks something first (for example whether to trust the folder), answer it in its terminal.
• Archive and Start New… (in the agent's ⋯ menu, or Archive Session and Start New… in the command palette) — archive the current conversation and start a clean one. This is the cheapest way to continue after a long session: the new session starts with an empty context instead of re-caching the old one. Write a handover first (see below) so the new session knows where to pick up.

Processes agents leave running

An agent can start programs that keep running in the background: a preview server (npm run serve), a tail -f on a log, a shell. Stopping the agent ends its terminal, but not always what it started, and those can go on holding the project's folder (Windows then won't rename or delete it: "in use") or a port long after the agent has stopped.

Hive keeps track of every process an agent's session starts, however it was started (also through the Microsoft Store's PowerShell 7, whose processes Windows starts outside the session's tracking: Hive takes them back in), and when the agent stops it looks at what is still running:

• Ask (the default): a notification lists them (site left 2 processes running: node serve.js, tail -f capture-1.log) with End Them and Keep Running, and the agent's pane header shows ⚠ 2 left running until you decide or they end by themselves. Hover it for the list; click it to end them or keep them. Keep Running leaves them running and stops listing them.
• End them: Hive ends them as the agent stops, without asking.

Choose in Settings → Agents → Processes left running. When you quit Hive with some still listed, it asks once whether to end them or leave them running (a quit with no window shown, or to install an update, leaves them running). Those Hive didn't ask about stay listed: when Hive next starts, it lists again the ones still running and offers to end them, checking that each is still the same process.

Agents are also told to stop what they start: to watch a test run with something that ends with it (hive-progress, or their CLI's notice that a background command ended) rather than a tail -f, and to end the watchers, servers and app copies they started before their card goes to Review, unless the card or you need them running.

Hive only ever ends processes the agent's session started: never one you started yourself in the same folder. If Windows doesn't let Hive end them, they stay listed in the pane header, so you can try again or keep them. On a PC where Hive can't keep track of agents' processes (PowerShell blocked by a company policy, for example), agents start as usual, Hive tells you once, and Help → Copy Diagnostics says why; what they leave running then isn't listed. Processes the agent's CLI already ends with its terminal (those attached to it) are never listed. One gap remains with PowerShell 7 installed from the Microsoft Store (Codex runs its commands in PowerShell 7 when you have it): a program it starts and leaves running as it exits within about a second, before Hive has seen it (Start-Process returning at once), isn't tracked. Commands Codex leaves running in the background keep their PowerShell open, so they are.

Reading past sessions

The Sessions tab shows every session of the project on the left as a tree, like the Files tab: by provider (Claude Code, Codex), then by agent, then the sessions themselves, newest first, with when each was last used, its context size and the size of its transcript file (amber past Settings → Sessions → Warn when a transcript is over, with a tip to hand it over to a new conversation; — when the CLI no longer has the file). Sessions started outside Hive (in VS Code or a terminal) and adopted ones go under Not from an agent; started outside Hive, they show as external: Adopt them to manage them in Hive. A session keeps its own agent: if you remove an agent and add another with the same name, the old sessions stay under Coder (removed) (or Removed agent, for sessions from before Hive kept agents' names). Each session says where it ran, such as Project folder or Worktree · hive/reviewer (hover for the full folder), and the Ran in line over its transcript names the agent too. Resume in … says which agent would resume it now, and its ▾ menu shows where each agent works. Tick Archived to include archived sessions.

A folder's sessions are found wherever its coding agent filed them, whatever the folder was called when they ran: a project opened through a junction or a link, or by its short 8.3 name (C:\Users\RUNNER~1\…), shows the same sessions as by its usual path, and the files its tools touched show by their path in the project.

Every branch shows how many sessions it holds. Branches start folded, except your focused agent's and the way down to the session you're reading; Hive remembers what you open and fold for each project. Expand All and Collapse All are in the header, and on every branch's menu.

Sub-sessions. Some sessions are started by the CLI for another one rather than by you: in Approve for me, Codex starts a short guardian review to judge each action, and saves each as its own session. They sit under the session that started them, which says how many it has (3 guardian reviews), so they don't crowd the list. They can be read like any session, but never resumed. One whose session isn't listed any more stays under its own agent.

Keys work as in the Files tab: ↑ and ↓ move (moving onto a session shows it), → opens a branch, ← folds it or goes up to the branch above, Enter folds or opens a branch, F2 renames and Delete deletes.

Archive or delete a whole branch. Right-click a provider, an agent or a session with sub-sessions (or use the ⋯ on its row) for Archive All…, Unarchive All and Delete All…. Hive asks once, naming how many sessions and which branch, then archives or deletes each of them. Sessions that are running, or whose files are in use (another program has the transcript or Hive's copy of it open, its CLI is still writing it, Hive is reading it for an export or search, or it's open in another Hive window), are left alone, and the result says which and why: Deleted 2 sessions; 2 skipped: 1 running, 1 in use. Try those again once they're free. A session is never half deleted: either all of Hive's copies of it go, or none. If the transcript you're reading is one of them, Hive closes it first and says so.

Clean up old sessions. Clean Up Old Sessions…, the clean-up button in the list's header beside Refresh, archives or deletes every session of the project that was last active more than 24 hours, 7 days or 30 days ago. Pick the age and Archive (the default: Hive's own sessions are hidden and kept, and you can unarchive them) or Delete (archived ones too: Hive's copies go to the Recycle Bin, what they used stays in the totals, and each CLI keeps its own transcript). The dialog says how many will go (2 sessions older than 7 days) and which it leaves alone: running sessions, the one you're reading, the Hive Assistant's current conversation and any whose files are in use are never touched. The result says what was done and what was skipped, as for a branch. Last active is a session's last message, not when it started. The Assistant's All Conversations has the same button.

Sessions you can't resume show a muted can't resume marker, and their Resume button is greyed out: hover it to see why. A sub-session isn't a conversation; its provider is turned off or not installed; neither the CLI nor Hive has its transcript any more; or no agent can run it (it ran in a worktree no agent of its provider uses). A conversation always resumes in the provider it ran in, never in whatever your default provider or the agent's provider is now. If its agent was removed, hovering Resume says which agent resumes it now.

Select a session to read its transcript on the right, including everything before each compaction. It opens at the latest messages; scroll up to load earlier ones. A running session doesn't update on its own unless you switch on Follow (the Session tab always shows the agent working); otherwise click Refresh. Settings → Sessions → Follow running sessions sets the default.

• Your messages and Claude's replies are shown in full.
• Thinking and each tool call are collapsed to one line (for example "Bash · Run the login tests" or "Edit · src/app.ts"). Click one to see its input and result; very long output is shortened, with Show all. The expand button in the toolbar opens or closes them all.
• Each compaction is a divider showing whether it was manual or automatic, the context size before and after, and the size of the first request after it (which also carries Claude Code's instructions and tools). Click it to read the summary the agent continued from.
• Slash commands such as /compact appear with their output, and pasted images as thumbnails; click one to view it.

The transcript opens at the latest message. For the running session it updates as the agent works, and scrolls with it while you are at the bottom.

Search (Ctrl+F in the tab) looks through every session: names, dates, providers and agents, and the transcripts' messages, replies, tool calls and results, and compaction summaries. The tree keeps only the sessions that match, with their branches opened and each session's matches listed under it; the line under the search box counts them. Click a match to open the transcript at that point with the matches highlighted. Clear the search to get the whole tree back.

From the toolbar you can Copy a message or reply (hover it), Export as Markdown to save the whole conversation as a readable file, Resume a session that isn't running (with several agents, ▾ chooses which one continues it), Show the agent that is running it, and rename (the tag), archive, delete or adopt it. Rename, delete and ⋯ (the rest) also show when you hover a session in the tree, or right-click it.

Deleting a session removes it from Hive: Hive's copies of its transcript go to the Recycle Bin and it no longer shows in the tree. What it used (tokens, cost, prompts) stays in the Overview's totals. A running session has to be stopped first, and one whose files are in use waits until they're free. Claude Code and Codex keep their own copy, so their own resume lists still have it.

Dates and times

Hive shows dates as 2026-10-04 and times as 14:05 by default: sessions named by when they started, the session lists and their tooltips, transcripts, exports and the rest. Settings → General → Date format chooses yyyy-mm-dd, dd/mm/yyyy, mm/dd/yyyy or System (as your Windows regional format shows them), and Time format 24-hour or 12-hour (2:05 PM). Names you give sessions stay as you typed them; only the automatic ones follow the format. How long ago a session was last active (2 hours ago) stays as it is: hover it for the date and time.

Language

Hive's window, menus and messages come in eight languages: English, Deutsch (German), Español (Spanish), Français (French), Polski (Polish), Português (Brasil) (Brazilian Portuguese), 日本語 (Japanese) and 简体中文 (Simplified Chinese). All but English were translated by AI.

Hive shows them in the language Windows displays, when Hive has it, else in English. Settings → General → Language chooses another: Automatic follows Windows (and says which language that gives), then each language by its own name. Languages translated by AI say so after their name, such as Polski (AI), with a note in that language under the list: improvements are welcome. Anything a language hasn't translated yet shows in English, and Automatic only picks a language once Hive has translations for it. In any language but English, the setting's title also says Language, so you can always find your way back.

Help → Improve This Translation opens the guide for translators on GitHub: how to fix a translation, or add a language, with a pull request.

Numbers, sizes, percentages, money and the words in dates (weekdays, months, AM and PM) follow the language too: 1,5 MB and pon., 5 paź in Polish. The date and time formats you chose above stay as they are.

A new language shows at once. A few parts that come from Chromium, the engine Hive is built on (the PDF viewer, date pickers), change when Hive next starts, and the setting says so.

What stays in English: this user guide and the other documents in the Docs view, for now (the Hive Assistant knows Hive well and can answer your questions in your language); the Performance view and the developer console, which are tools for developers; and what Hive tells agents and the Hive Assistant (their instructions, skills, notices and the hive tools' replies), so they work the same whatever your language; they can still answer you in yours. Names you gave things, and what agents wrote, stay as they are. The installer follows Windows' display language too.

Starting Hive in a language: --lang=<code> (for example Hive.exe --lang=pl) starts Hive in that language for one run, whatever the setting says, which is how translators check their work. While Hive runs that way, the setting says it applies from the next start.

Several agents in one project

A project can have up to twelve agents working at once (more, up to 24, with Agents per project in Settings → Advanced: see More than twelve agents below), for example one building a feature while another reviews or writes tests. All agents are equal: any of them can work in a worktree, and any can be removed once stopped. Add Agent above the terminal (Configure Agent and Add…) opens Add Agent…; its ▾ has the same and Add Agent from Template (see Agent templates). To add one straight away, with your default provider (Settings → Providers → Default provider, or the project's in Project Settings) and its default settings, working in the project folder, press Ctrl+Alt+Shift+N (Add Agent in the command palette, or right-click the project). In Add Agent… you choose:

• Name — "Agent 2" by default; rename it any time (double-click its tab). Names are unique across the workspace, so an agent is never confused with another project's on the board, in notifications or by the Assistant: a name another agent already has is refused, and Hive offers one with your project's initials in front (B1 in a project called hive becomes HB1; a word gets the project after it, Builder (hive)). Agents that shared a name from before keep working: Hive says so once, with a button to rename one. Its Role (Agent Settings), such as builder or reviewer, says what it is for; templates save it (see Agent templates).
• Where it works:
  • Project folder — shares the folder with the project's other agents.
  • New worktree — its own checkout of the project on its own branch (hive/<workspace>/<project>/<agent> by default, such as hive/HIVE/amberlight/amb1, based on the branch you pick: hive/ marks branches Hive made, so it can reuse and tidy them up). The workspace and project are always in it, so several workspaces can share one repository, even with projects of the same name, and their agents' branches never clash; characters git doesn't allow in a branch name become -. Branches made before this (hive/b4) are still Hive's: reusing worktrees and tidying unused ones recognise both. Its work stays separate until you merge it. Hive creates worktrees next to the workspace, in <workspace>.worktrees\<project>\<agent>, and copies git-ignored files such as .env into them (Project Settings → Agents & Worktrees → Copy into new worktrees). If the project needs setting up first, set a Setup command such as npm install: it runs in the agent's pane before the agent starts, and if it fails you can retry or start without it. If the project already has an unused worktree on that branch (one you kept when removing B4, say, and you add a new B4; with the default branch, one on B4's branch from before, hive/b4, counts too), Hive uses it again instead of making a -2 one, as long as it is merged into the branch you picked, has nothing uncommitted, and nothing is using it (no program or terminal working in its folder, no git command running in it): it brings it up to that branch first, so the agent starts from the latest code with node_modules and the rest already there. The setup command runs again only if a lockfile (package-lock.json, yarn.lock, Cargo.lock…) changed. The dialog says so before you add; afterwards a notice says what happened ("Reused hive/b4, brought up to main at 66ce11b"). If that worktree holds work (commits not merged, or uncommitted files), Hive leaves it as it is and makes a new one, and the dialog offers to reuse it instead, keeping its work.
  • Existing worktree — a worktree of the project that no agent uses, such as one you kept when removing an agent. One that is merged into the project folder's branch and clean is brought up to that branch first; any other is taken as it is, with its work.
• Provider — Claude Code or Codex (only enabled providers can be chosen). Changing an agent's provider later clears its model settings and its last session (Resume then picks up its new provider's last conversation). Its earlier conversations still resume from the Sessions tab, each in the provider it ran in; new conversations use the new provider.
• Settings — the agent can use its own model, effort and permission mode, for example Sonnet for a reviewer while Opus codes, or a Codex reviewer next to a Claude Code agent. Left on Project's, it follows Project Settings for its provider (an effort nobody chose reads Claude Code's default until Claude Code says which level that is).

Layouts. The layout follows as you add agents: two columns for two, three for three, a 2×2 grid for four, a 3×2 grid for five or six. The buttons at the right of the agent row choose one yourself: one at a time (click an agent to switch), two columns, three columns, a grid of four or a grid of six. A layout you choose stays as agents are added; choosing the one that shows all the agents makes it follow them again. Three columns and the grids work best on a wide window, or with the sidebar hidden (Ctrl+B).

Pages. The project has one layout, and a page holds as many agents as it has panes, so every agent on a page has its own pane: with four agents in three columns, page 1 shows three and page 2 the fourth; six agents in a grid of four are two pages (4 and 2). Left automatic, the layout shows every agent up to a 3×2 grid, and a seventh opens page 2. One at a time has no pages: the agent tabs choose who is shown. The numbered buttons next to the layouts switch pages, or press Ctrl+Alt+PageDown / Ctrl+Alt+PageUp; a dot on a page's button shows its most urgent agent (one waiting for you, say), and its tooltip says which agents are there. With more than six pages (more than 12 agents in two columns), they become ‹ 3 / 12 ▾ ›: ‹ and › go to the previous and next page, and the middle lists every page with its agents. Changing the layout re-pages at once. When the agent tabs don't all fit the row, it fades out at the end that has more, with a small › (or ‹) there: click it, or turn the mouse wheel over the tabs, to scroll to the others. When the row is very short of room, Add Agent shows only its +, the layout buttons become one button with a menu, and the page buttons become 3 / 6, a menu of the pages, so the agent tabs keep some room. Clicking an agent on another page goes there. Each agent runs its own copy of its CLI, so Hive notes the memory use when you add the seventh. Each pane has its own header with the agent's status and buttons; click a pane to make it the focused agent. The buttons in the project header, the Session menu, pasting screenshots and Insert into Session act on the focused agent. Ctrl+Alt+] and Ctrl+Alt+[ move between agents, across pages. With One at a time, clicking an agent shows it.

More than twelve agents. A project can have twelve agents. If you need more, raise Agents per project in Settings → Advanced (up to 24), for all your workspaces or, in its This workspace box, for this one. Each agent runs its own copy of its CLI and they all share your plans' usage limits, so above 12 the setting shows what that costs on your computer: the memory your running agents take now, and how much your computer has free. Lowering it again removes no agents: a project with more just can't add another until it's below. Templates keep to it too: one with more agents than a project can have can't be loaded there.

Arranging agents. Drag an agent (its tab, or its pane by the header) onto another agent's pane to swap them, running or not; onto an empty pane to move it there. Drag a tab along the strip to move it between others, like browser tabs (a bar shows where it will land). To swap with an agent on another page, hold the dragged agent over that page's button for a moment: the page shows, and you drop it on a pane there. Drop it on a page button itself to move it to that page's last place. The panes always show the agents in their order, so what you see is what's saved. Or use Move Left / Move Right in the agent's menu, or Ctrl+Alt+Shift+Left / Right for the focused agent. The order is saved with the project; nothing is stopped or restarted.

Which conversation each agent has. Each agent's footer shows the session it is running as an icon, on the right before the context: hover for its name and when it started, click to read it in the Sessions tab, right-click to rename it. Until a session has a name, it is named by when it started, e.g. 2026-10-04 14:05, and keeps that name when you resume it (in your date and time format: Settings → General → Date format and Time format). You can rename a session in Hive (the footer or the Sessions tab) or in Claude Code with /rename: whichever you did last is the name Hive shows, and resuming the session keeps it. A conversation can only be open in one agent at a time. Resume reopens the agent's own last session and is greyed out when it has none. Its ▾ lists the recent sessions from the agent's folder: pick one to continue it in this agent, including a paused conversation another agent in the same folder started. Sessions that are open in another agent are greyed out; clicking one takes you to that agent. Agents in their own worktree only see that worktree's sessions.

The sidebar keeps one status dot per project, showing the most urgent agent (needs input, then working…), with the number of running agents next to the name. The project header's status says how many agents are in that state (for example Working · 1 of 2 agents); hover it for each agent's state. Notifications name the agent, e.g. "hive · Agent 2 finished".

Background tasks. An agent can start something and end its turn while it runs, such as a long test run. Claude Code is told when the task ends and carries on by itself, so Hive shows the agent as waiting on background tasks ("Waiting on 1 background task") rather than finished, and only says it has finished (chime and notification) once it really has. Meanwhile the Assistant waits for it and won't give it a new task, and quitting asks first, since the task would stop. Codex isn't told when its background terminals end, so a Codex agent shows as finished with the count next to it ("Finished · 1 background task running"). Hive can't tell a test run from something that never ends, such as a dev server, so it stops counting a task after an hour; change that in Settings → Agents & Worktrees → Count background tasks for up to.

File locks. Agents sharing the project folder could otherwise edit the same file at the same time. When an agent edits a file, Hive notes that it is working on it; if another agent then tries to edit that file, Hive tells it to wait or work on something else, and it carries on with other work. The claim ends when the first agent finishes its task. The files an agent holds show as a lock with a count on its tab, named by their path in the agent's folder, even when the folder is reached by another name (a junction, or a short name such as C:\Users\RUNNER~1\…). Settings → Agents & Worktrees → File locks (or per project) chooses what happens: Block (default), Ask me (you approve the edit; Codex can't show its own approval for this, so Hive holds the edit back and shows a notification with Allow, and Codex waits until you allow it; Hive tells it to go ahead as soon as it has finished replying and you aren't typing in its terminal), Warn (the edit goes ahead, the agent is told), or Off. Locks cover the agents' file edits, not shell commands (formatters, npm install, git checkout), and not files agents share outside the project such as the CLIs' own settings or memory — keep that in mind when several agents work in one folder. Agents in their own worktrees never get in each other's way.

If git can't read the changes, the Git tab's Changes says why, with Retry. The same goes for every list and search: if one can't be read, Hive says so with Retry rather than showing nothing, and if a refresh fails the last results stay, with a note saying when they're from. They are always the same project's (or workspace's): switching to another project never shows the last one's.

Reviewing and merging a worktree agent's work. In the Git tab's Changes and the Files tab, the selector at the top switches between the project folder and each agent's worktree. For a worktree, Changes lists everything the agent changed since its branch started (its commits and uncommitted edits). Open file, above a diff, opens that folder's copy of the file: the worktree's, not the project's. When it is done, choose Merge (pane header, agent menu or Changes tab):

• Uncommitted changes are committed on the agent's branch first, with the message you enter.
• The branch is merged into the branch checked out in the project folder: Merge (the default; keeps the agent's commits and their messages, plus a merge commit) or Squash (one commit, with the message you enter). Change the default in Settings → Agents & Worktrees → Default merge style.
• If the same files changed on both sides, nothing is merged. Hive lists the files and can send an agent in the project folder instructions to do the merge and resolve the conflicts, or copy them for you.
• Remove the worktree and branch afterwards (and the agent) is off by default: an agent can keep its worktree and work on task after task, merging as it goes. Tick it when its work is finished (stop the agent first).
• Squash with the worktree kept offers Move the branch to main afterwards (ticked). The squash commit holds all the branch's work, so the branch is moved there and the agent's next merge brings only what is new. Without it, the branch keeps its old commits and its next merge may conflict with its own earlier work. Hive only moves it when nothing would be lost, and tells you if it couldn't.

Working with one agent for a while. With Merge and the worktree kept, an agent can do a task and merge it, then the next task and merge again, or several tasks and one merge. When the project folder's branch moves on (another agent's work was merged), ask the agent to merge it into its branch before its next task, so it works on current code.

One merge at a time: the merge slot. When several agents finish close together, each merging main into its branch, checking it and merging, one agent's merge can land while another is still checking, and that one has to merge and check again. So agents take turns: an agent claims the project's merge slot for the branch it merges into, merges main in, runs its checks, merges, and releases it. The others wait in order, and their status reads Waiting for the merge slot (B4 is merging #305). While an agent holds the slot, nothing else merges into that branch through Hive, so its checks run once. Agents do this by themselves when they merge (the merge-ready skill).

• Who holds it and who waits shows in the project's Overview, on each agent's status, and as a card at the top of the Progress panel with the branch going in and the step its checks are on (see Merges and lanes).
• It is never stuck. The slot is released when its agent's session ends, and a hold lasts 60 minutes (longer while the agent keeps reporting progress, or when it claims again). A hold that runs out goes to the next in line, and Hive tells you, since that merge may not have finished. Release beside a holder (in the Overview or the Progress panel) frees it yourself, after a question; if the slot changed hands while you answered, nothing is released and Hive says so. If Hive closed while an agent held the slot, it tells you when the workspace opens again, so you can check the project folder for a merge left half done.
• Your own merges take the slot too: while an agent holds it or waits for it, the Merge dialog says who is merging and waits until the slot is free. Merges made outside Hive (in a terminal) aren't controlled; agents still check that main hasn't moved before they merge.

A worktree agent has a worktree icon after its name, on its tab and in its header: hover it (or Tab to it) for its branch, its folder, the branch it started from and what's left to merge.

Work not merged yet shows on the agent: the Merge button in its header (its icon is a branch merging) turns orange with the number of commits on its branch that aren't in the project folder's branch, and its tab in the agent strip shows the same number with an up arrow. A • instead of a number means uncommitted files only. Hover either for the details ("2 commits not merged into main · 1 uncommitted file"). Hive checks when the agent finishes a turn or stops, when you come back to Hive's window, after a merge, and every minute while something is left to merge. Merge… is greyed out while the agent is in the middle of a task (working, asking you something, or waiting on background tasks it started), because merging commits its unfinished files; hover it to see why, and merge once it has finished.

Remove Agent asks whether to keep a worktree agent's worktree and branch or delete them; Discard deletes them straight away. Their sessions stay in the Sessions tab, labelled with the agent and branch. A worktree kept before the project's setup command ever finished in it (the agent removed before its first start, say; this goes for Remove All below too) still needs setting up, and Hive remembers that: the next agent given that worktree, with Add Agent → Existing worktree or by a template that reuses it (see Agent templates), runs the setup command first. A worktree whose setup already ran isn't set up again.

Remove every agent at once. Remove All (4) in the project header (also Session → Remove All Agents (4)… and the command palette) removes all of the project's agents after one question. It lists them in a table, says which are working (running agents are stopped first) and, for each worktree agent, whether its worktree is merged and clean or always kept (with the reason, such as "2 commits not merged into main"). Worktrees and branches are kept unless you tick Also delete the worktrees and branches fully merged into main with no uncommitted changes: then only those are deleted; anything not merged or not committed is always kept. If the agents have open cards, you're asked once what to do with them. Their sessions stay in the Sessions tab. If an agent can't be removed, one notice says which and why, and the others still go. In a narrow window it moves into the header's ⋯. Two dev servers from different agents can clash on the same port; give them different ports.

Unused worktrees

A worktree you keep when you remove its agent (Keep worktree and branch, or Remove All without its tick box) stays on disk with its branch: Hive says so in a notice with Review unused worktrees. They live in the Git tab's Changes, with every other worktree. Its picker starts with Unused worktrees (n), for worktrees no agent of the project uses right now (for example ones from another template, or ones an agent made itself with git worktree add), then lists the worktrees agents work in, then the project folder. Unused worktrees lists them, each with its branch, who made it (was B4, the Hive agent that last worked there; made by Hive; or not made by Hive), its last commit and its size, and whether it is merged into main and clean or what it holds that is nowhere else ("3 commits not on main · 2 changed files"):

• Remove deletes a merged, clean worktree and its branch. Remove all merged (n)… does them all after one question. Hive checks each again first: one that changed since (a new commit, a file written) is kept, and the notice says why.
• Open (or picking it by name in the folder picker) shows its changes since main, file by file, as an agent's worktree does. If it holds work, Merge opens the usual Merge dialog, which waits its turn like an agent's merge; tick Remove the worktree and branch afterwards to tidy it once its work is on main.
• A worktree that holds work has no plain Remove. Give to an agent… opens Add Agent with Existing worktree and that worktree chosen. Remove anyway… checks the worktree and asks first, naming exactly what goes (its unmerged commits, or for a worktree not on a branch the commits only it has, its uncommitted files and the files git ignores in it, such as build output). If anything in it changes before you confirm (a file added, renamed or edited, ignored ones included, or another branch checked out), nothing is removed: Hive checks it again and asks you again, saying what changed and showing what it holds now, so you confirm what would really go. The same goes for a question left open more than 15 minutes. If Hive can't check what a worktree holds, it doesn't offer to remove it anyway.

The project's Overview shows one line, such as "7 unused worktrees (7 merged) — Review in Changes". Changes' project folder says when an unused worktree has work that isn't on main, with Review. Project Settings → Storage has a line for unused worktrees with their total size, linking to Changes. Deleting a template never touches worktrees, but if its worktree agents left worktrees that no agent uses now, Hive says how many, once. The Hive Assistant can see how many unused worktrees a project has and mention them; only you can remove them. Without git (see Git), nothing is listed or removed.

Agent templates

Set a project's agents up once, see them work, and reuse the setup anywhere: a template saves each agent's name, role, provider, model, effort, permission mode and context setting, whether it works in its own worktree, and the project's layout. Conversations, worktree folders and branches aren't saved: they belong to the project.

Two buttons on the agent strip hold everything about templates: Template ▾, on the right before the page buttons and the layouts (just its icon when the window is narrow), and the ▾ of Add Agent. Their menus work from the keyboard too: ↑ and ↓ to move, Enter to choose, → to open Add Agent from Template.

• Template ▾ → Save Template… names the template and saves it for this project only (kept in its private .hive folder) or, ticked, for every project in the workspace. Saving with a name that's already there asks before replacing it; saving again is how you change a template.

• Template ▾ then lists the workspace's and this project's templates (the same name can be in both): choose one to load it. Loading replaces every agent of the project: Hive first lists who goes and who comes. The new agents are a table, in the template's order: each one's coding agent, model, effort and mode (a muted (default) where the template leaves it to the project or your defaults), and where it works: the project folder, or its own worktree by its branch, with the folder Hive will make for it in this project when you hover over it (a template made in another project never uses that project's worktrees). An agent replaced by a new one with the same name is marked, and if the project has a worktree setup command, Hive says each new worktree runs it.

  Naming the new agents. Beside each agent's name in the template (kept as it is, for reference) is a box for the name the new agent gets: change any of them before you load. Agent names are unique across the workspace, so a template saved from another project usually brings that project's names: each name another project's agent has is marked, saying whose it is, and Load template stays greyed out until you've changed them all. Hive doesn't fill in names for you. The agents being replaced don't count, so loading a template into the project it came from works without changes, and its agents work in their worktrees again. Where each new agent works follows its new name (a worktree of that name is worked in again, below).

  Worktree agents need git. An agent that works in its own worktree needs the project to be a git repository on a branch. Loading a template with worktree agents into a folder that isn't one (or a repository with no commit yet, or on a detached HEAD) is refused, and Hive says which agents need git and why: make the folder a repository with a first commit, or edit the template to put those agents in the project folder. A template whose agents all work in the project folder loads anywhere.

  Worktrees are reused, not piled up. A new agent with the same name as one it replaces works in that agent's worktree again, if it's clean (nothing uncommitted), instead of getting a new -2 one. So does one whose worktree was kept from an earlier load, when you switch templates and back. Its branch is left as it is. If a worktree of that name has uncommitted work, the new agent gets a new worktree and the list says why; nothing is removed. Add Agent from Template reuses a free, clean worktree of the agent's name the same way, and tells you.

  Tidying old worktrees. The replaced agents' worktrees that no new agent reuses stay on disk by default. The list says, for each, whether it's merged into the main branch and clean, or why not ("2 commits not merged into main"). When some are merged and clean, a tick box (off unless you tick it) removes them with their branches as the template loads. Worktrees with unmerged commits or uncommitted files are never removed. As the template loads, Hive checks each ticked worktree again and removes it only if, at that moment, it is merged into the main branch the dialog showed and clean: commits not merged by then, or uncommitted files, keep it. Only its state at that check counts, so a worktree that is merged and clean then is removed even if a branch moved while the dialog was open. After that check, it is kept if either branch moves or uncommitted files appear in it. A branch can also move at the very last step, after the clean folder has already gone: then the folder stays removed but the branch is kept, with its commits. Hive's notice afterwards says which worktrees went with their branches, which folders went while their branch was kept, and which worktrees were kept, and why. It won't load while an agent runs or is starting (stop it first), while a worktree agent has uncommitted work (commit or discard it first) or Hive can't check its worktree, or while a provider the template needs is turned off or not installed (it says which, with a way into Agent Setup). The removed agents' conversations stay in the Sessions tab, their worktrees and branches stay on disk (to merge, or reuse with Add Agent → Existing worktree), and their open cards go back (Doing ones to Todo). No agent of the project can start while a template loads. If an agent can't be created, or the agents change meanwhile, nothing changes.

• Add Agent ▾ → Add Agent from Template lists each template's agents: choose one to add it and leave the others alone. If an agent of the workspace already has its name, the new one gets a number ("Builder 2").

Roles. An agent's Role (Agent Settings), such as builder or reviewer, says what it is for: templates save it, and the agent's tab tooltip shows it. Leave it empty and the agent's name is its role. Save Agents as Template…, Load Template… and Add Agent from Template… are in the command palette too (the last two open the agent strip's menus).

Managing and sharing templates

The Templates view (its icon is next to Skills on the activity bar) lists the workspace's templates and each project's, grouped by where they're kept; the drop-down at the top shows all of them, the workspace's, or one project's. A project's Templates tab lists its own templates and the workspace's, each marked with where it's kept.

Select a template to see what it holds: each agent's name, role, coding agent, model, effort, mode and whether it works in its own worktree, and the layout. In a narrow pane (a small window, or the side panels open) its settings wrap rather than run off the side, the editor puts each field's name above its box, and a project's Templates tab shows its list above the template; when even that doesn't fit, scroll the agents table sideways. With a template selected:

• Load into Project… (in the view, you choose the project) or Load into This Project… (in a project's tab) replaces the project's agents and layout, with the same list of who goes and who comes, and the same checks, as Template ▾.
• Edit… changes it where it's kept. Give it a new name, a short description and a layout, and change its agents. Add Agent… adds one, and each row has buttons to edit, copy, move up or down, and remove that agent. Editing an agent opens the same Agent Settings dialog as a project's agent: name, role, coding agent, model, effort, mode, 200K context, and whether it works in its own worktree or the project folder. Settings left as Project's follow whichever project the template is loaded into. Saving an agent in that dialog saves the template too, with your other changes, and the editor stays open. Save Template checks it (1 agent up to as many as a project can have, each with its own name) and saves it with changes made in the editor itself (name, description, layout, order, removed agents). Changes not saved yet are marked: Changes not saved in the editor, and Not saved beside the template in the list. They stay if you leave the editor for another template or view, and it opens with them again; Cancel asks before discarding them. Quitting Hive, closing the window and Reload Window ask about them too, as they do for unsaved files. While a save is in progress, the editor can't be changed. If the template was saved again meanwhile (from a project, or another window), Hive tells you instead of overwriting it. Editing never changes a project you loaded the template into earlier. Saving a project's agents again under the same name (Save Template…) still works too.
• Rename… renames it where it's kept. Another template there can't have the same name.
• Duplicate… copies it into the workspace or any project. A name that's already taken there gets a number: "Pair (2)".
• Export… saves it as one file, such as Build and review.hive-template.json, wherever you choose. Templates live in .hive, which git ignores, so exporting is how you share one. The file holds only the template: no folder paths, sessions or names of people.
• Delete sends it to the Recycle Bin.

Import… (the download icon at the top of the list) opens a template file and asks where to keep it: the workspace, or a project. Hive checks the file first and refuses one it can't use, saying why: not a template, made by a newer Hive, or more than 24 agents. A template with more agents than a project can have (Agents per project) can't be loaded there: its Load dialog says so. Nothing is half imported. If a template of that name is already there, choose Replace or Keep Both (the imported one gets a number). A template whose coding agent this Hive doesn't know, from a newer Hive say, is imported and marked: Hive won't load it until it knows that agent.

Archiving and backups

Claude Code and Codex delete old transcripts after a while. Hive keeps a copy of every session transcript in the project's .hive/sessions folder, and archived sessions in .hive/archive. Files you paste or drop into a session are kept in .hive/attachments. Hive only deletes them when you ask (deleting a session sends its transcript copies to the Recycle Bin; its attachments stay). If the CLI has removed a transcript, Hive restores it from the backup when you resume.

Storage. Project Settings → Storage (or Project Storage and Clean Up… in the command palette) shows how much space Hive keeps for the project: transcript backups (.hive/sessions), the archive (.hive/archive), attachments (.hive/attachments) and each agent's worktree. It's measured in the background, so a large worktree never holds up the window, and leaving the page stops measuring; Refresh measures again. The coding agents' own transcripts (in ~/.claude and ~/.codex) aren't counted. Settings → Workspace → Storage shows the workspace's total and every project, the Hive Assistant included, biggest first; Storage next to one opens its page.

Clean Up… on that page moves old files to the Recycle Bin. Nothing is cleaned up automatically. Choose what goes:

• Attachments of archived sessions last active more than 90 days ago (or the number of days you set). This is the only option on at first.
• Attachments of deleted sessions, and of launches that never got a session (folders named run-…).
• Hive's backups of archived sessions last active more than a number of days ago, only where Claude Code or Codex still has the transcript. The session stays: you can still resume and read it, from the CLI's copy, for as long as the CLI keeps it.
• Backups of archived sessions the CLI no longer has. Hive's copy is the last one, so these sessions are deleted, as Delete Session does: they can't be resumed or read afterwards. The dialog warns you when this is on.

The dialog lists every file that will go, with its size and the total, before anything happens; Move … to the Recycle Bin removes exactly those. Running sessions and sessions that aren't archived are never touched, also when one is resumed or unarchived while the dialog is open: it's skipped and listed in the result. What the cleaned-up sessions used still counts in the Overview and the Workspace Overview.

Antivirus scanning

On Windows, Microsoft Defender's real-time protection scans every file as it is created or opened, and Hive's work creates and opens a great many: installs, builds, tests, git, worktrees, transcripts. With several agents at once that adds up. Settings → Workspace → Antivirus scanning (or Antivirus Scanning of the Workspace in the command palette) shows how Defender treats the workspace:

• whether Defender is the active antivirus and real-time protection is on (if another antivirus is active, Hive names it and leaves it alone);
• the folders Hive's work goes through: the workspace (every project is in it), its worktrees folder once an agent has one, and, if you develop Hive itself, its test area. For each, whether Defender scans it: Excluded, Scanned, or Unknown, because Defender shows its exclusions only to administrators. Check with Administrator Rights… reads them (Windows asks once);
• whether each is on a Dev Drive: a trusted Dev Drive, with Defender's performance mode on, is scanned much more lightly. Without administrator rights Hive can only see that a drive is ReFS (maybe); Check with Administrator Rights… confirms it. Microsoft recommends a Dev Drive for code: About Dev Drive explains how to set one up (Hive doesn't create drives).

Add Exclusions… asks Defender to stop scanning exactly those folders, never anything broader: Hive never offers a whole drive, your home folder or a system folder, even if the workspace is one. It lists them first, one folder per row (a long path wraps, its next lines indented), with a button beside the list, Copy (Copy all when there are several), that copies every path, one per line. Then it asks for administrator rights once; if the folders change before you answer (an agent makes a worktrees folder), it asks you again rather than add more. A folder you had already excluded is left as it is. Think about the trade-off: Defender won't scan anything in an excluded folder, including node_modules and whatever agents download there, so only exclude folders whose contents you trust. Remove Hive's Exclusions… lists the folders it will take away the same way, and takes away only the ones Hive added; exclusions you added yourself stay. If your organisation manages Defender, it may refuse the change; Hive says so.

On the machine Hive is developed on, with several agents at work, Hive's full test run took about 3 to 5% less time with these folders excluded (for example 12.0 minutes before, 11.6 after); a single heavy install or build may gain more or less.

When Defender scans the workspace and it matters (two or more agents running at once, or a command in the Progress panel that took two minutes or more), Hive suggests this, with Review… and Don't Ask Again (for this workspace). If you close it, or review without adding exclusions, Hive reminds you later: at most once a day, and only when scanning matters again. It stops when you pick Don't Ask Again, or once the folders are excluded or on a trusted Dev Drive, or Defender isn't the active antivirus. A folder added since, such as the worktrees folder, is suggested straight away. The Performance view says so too.

Token use, cache and compaction

The Overview tab updates as sessions change (at most every 15 seconds; Settings → Sessions → Overview updates can make it every minute or only when you click Refresh). It starts with the project's cards at a glance, as on the Workspace Overview but for this project only: how many are On Hold, in Todo, Doing, Waiting for review, Passed and Done, and how many are stalled or blocked. They update as cards change, and clicking a number opens the project's Tasks tab. A project without cards says so, with Open Tasks. Then a project summary for the period you choose (All time at first, or Today, 7 days, 30 days), across every provider: tokens, API-equivalent cost, sessions and prompts. Periods are calendar days (Today is since midnight; 7 days is today and the six days before), and they count only what happened in them: a session that has been running since Monday adds only today's work to Today. For 7 and 30 days a small chart shows the tokens of each day; hover a day for its cost and prompts. Below it are the agents running now (with how full each one's context is), a section per provider with its totals and plan limits, a table by agent, and one agent's session: its running session, else its most recent one. It follows the focused agent; with several agents, a picker next to the heading shows another's.

• Context — how many tokens the conversation occupies right now: the last request's input plus its output (thinking included), which stays in the conversation. That is what the agent compacts on, so a turn that thinks for 70K tokens can take a context showing 116K to 189K and set off a compaction; the compaction history says so ("turn added 72.4k output").
• Cache — whether Anthropic's prompt cache is still warm (5-minute or 1-hour lifetime) and how long it has left (Claude Code).
• Re-cache on resume — an estimate of the tokens written to cache on the first message after resuming, once the cache has expired.
• Compactions — each time the agent summarised the conversation to free space, with before/after sizes, newest first, ten to a page (Rows per page changes that, and is remembered). Filter by trigger (auto or manual) or by date and time, and click a column's header to sort by it (again for the other way, a third time for newest first). Click a compaction, or press Enter on it, to read it in the Sessions tab, at its divider with the summary the agent continued from. Clicking the context in an agent's footer brings you here.

Tables. Hive's longer tables work the same way: the compactions, archived cards, keyboard shortcuts, Performance's and Compare's tables, Storage and the Overviews' tables by project and by agent. Click a column's header to sort by it (again for the other way, a third time for the table's own order); Hive remembers each table's sort and rows per page. A table with many rows has filters under its headers and pages under it.

• API-equivalent cost — what the session would have cost at API prices. On a subscription you are not charged this; it is a measure of how heavy the session is. Claude Code calculates it itself; for Codex, Hive estimates it from a price table (shown with ≈). Hive ships the published prices as starting values, and you can change, add and remove them in each provider's settings page (API prices) if they change or you have different rates. For a model Hive has no price for, the cost shows as unknown ($? in the agent's footer, Unknown on the Overview; a total that includes such sessions shows what is known with + ?); hover it to see which model, and add its price under API prices to see the estimate.

Long conversations

A conversation's transcript keeps everything that happened in it, and compacting doesn't make it smaller: it only shortens what the agent has in its context. A very long one (100 MB and more) slows down the CLI and Hive, and can make typing in the terminals stutter. The size shows in each agent's footer, next to the context, and beside each session in the Sessions tab (the Assistant's conversations too), and turns amber past Settings → Sessions → Warn when a transcript is over (20 MB; projects can set their own). Hive also tells you once when a conversation passes it.

To start afresh without losing the thread, click the size (or choose Hand Over to… in the agent's menu) and pick the agent itself, in a new conversation: the agent writes a handover, Hive ends its conversation (it stays in the Sessions tab) and starts a new one that reads the handover and carries on. The Assistant sees each agent's transcript size too, and can suggest it. For new work that doesn't need the thread, ask the Assistant to give the agent the task in a new conversation: the same, without the handover (see Card loops).

Usage cache. Hive remembers each transcript's token counts, also across restarts, so the Overview and session lists open without reading every transcript again. A transcript is read again only if it changed while Hive was closed, such as a session you continued outside Hive. Settings → Sessions → Usage cache size sets how many it keeps (5,000), and Clear the usage cache starts afresh.

Workspace Overview

The Workspace Overview (in the activity bar, or Ctrl+Shift+O) adds up the whole workspace: every project and the Hive Assistant. It opens on the last 7 days (or Today, 30 days, All time) and shows:

• the task board at a glance: cards per column, stalled and blocked, each opening the board;
• tokens, API-equivalent cost, sessions and prompts for the period;
• for 7 and 30 days, a chart of tokens per day, stacked by project (the six busiest, the rest as Other); each day is a tile of its own, as in the Performance chart, so quiet days still show; hover a day for each project's share;
• every agent running now, in any project (click one to go to it);
• a table by project, with the Assistant as its own row: click a column to sort, or a row to open that project's Overview;
• each provider's totals and plan limits.

Hidden and removed projects aren't counted. It updates like the project Overview, and reads no more than it does: token counts come from the usage cache.

Plan usage

If you use a subscription (a Claude plan for Claude Code, a ChatGPT plan for Codex), the status bar shows how much of each plan's limits is used, one item per provider, for example 5h 34% · Week 12%: the rolling 5-hour allowance and the weekly one. Hover it to see when each resets; the Overview tab shows them with meters in each provider's section. The numbers are for your whole account (every session, not just Hive's) and come from the CLI while a session is running, so after a quiet spell they show when they were last updated. The status bar darkens at 80% and turns red at 95%, and Hive notifies you once when you pass 80% and 95% of each limit in each reset period.

Each agent's footer shows its model and effort, e.g. Opus 5.5 (default) · High: the model that actually runs, as the running session reports it, otherwise the model new sessions will use. An alias such as Opus shows as the model it stands for (Opus 5.5), with chosen as Opus in the tooltip; the model pickers list it as Opus (Opus 5.5). (default) means the model is inherited, not chosen for this agent or project. With no effort chosen, the effort is the model's own default once the CLI has said it (Medium (default)).

Performance metrics

Hive counts what its own parts cost, for each workspace: its Agent API's requests (how many, how long, how big), its tools' replies as the agents got them, what each session was given at launch (Hive's guidance, the Assistant's mode, the skills), and its skill service's work, alongside the providers' own reported token usage. Only totals are kept, never prompts, replies, tokens or paths, for 30 days, in the workspace's .hive/metrics folder (kept out of git). Hive doesn't guess token counts: what it measures is exact bytes and characters, and token usage is what the providers report.

It's on by default: Settings → Sessions → Record performance metrics turns it off (what was recorded stays), and Reset performance metrics clears the workspace's. Scripts can read them with the Agent API (GET /v1/metrics).

Performance view

Performance in the activity bar shows these metrics for the whole workspace; each project's Performance tab (next to Overview) shows only that project's. Pick the last 24 hours, 7 days or 30 days; in the activity bar view, the sidebar (or Scope) picks the whole workspace, its own work (the Assistant, scripts) or one project. Each filter sits with what it changes: Who (project agents, the Assistant, scripts) heads a box holding the cards, the chart and the tables, and Provider, inside it, heads the two parts recorded per provider, the guidance given at launch and the providers' usage (Hive doesn't record API requests or tool calls per provider). Provider always lists every provider with data in the range, so you can switch from one to another directly. Export (and Compare's Keep current view) saves the page's scope, range and Who, with every provider's rows, each naming its provider, so its totals match the cards whatever provider is picked. You see:

• how long Hive was recording in the range: metrics are only kept while the workspace is open in Hive with recording on, so time before that, while Hive was closed or recording was off, or before a reset is not recorded (no data, not zero), and so is history Hive removed to keep its metrics file small, which the page says;
• cards: Agent API requests (per hour recorded) and how many failed or were cancelled, their latency (p50 and p95), the data sent and received, the characters Hive's tools gave the models, and what each session got at launch;
• a chart of requests per hour (24 hours) or per day, failures in red and hours not recorded hatched; hover a bar for its tool calls and launches;
• tables of Hive's tools (sorted by the characters they cost a model's context), Agent API routes, the guidance given at launch in parts (Hive's core instructions, what it adds for the project, the Assistant's role and mode, the skills' catalog), and the providers' own usage for project agents and the Assistant apart: tokens, requests, context (each session's latest, not added up), compactions, safeguard stops (responses a CLI's safety classifier stopped; not detected for Copilot) and API-equivalent cost (≈ where Hive estimated it, unknown where a session reported nothing; not a bill), and, when there were any, the safeguard stops per agent and model. If a project's session history couldn't be read, the page says the totals are partial;
• for the whole workspace, the skill service's scans and cache, and Hive-wide event streams.

It refreshes every minute while you look at it (and Refresh at once); reading it doesn't add to the numbers. A note says when measurements were dropped because a limit was full, and What isn't measured lists what it can't see. Export saves what the page shows (its scope, range and filters) as a JSON file with its units, coverage and Hive's version; Shift+click Export to replace project names with project-1, project-2… and leave out the workspace's path, before sharing it.

Cost per card

Hive works out what each card cost from who held it when and what their sessions used then:

• What counts. A card's builder (its agent) while it is in Doing, and its reviewer from the start of each review to its verdict. Usage is each provider's own report: Hive's estimates (where a provider reports no cost, or you chose your own prices) are marked ≈, and what Hive can't know, such as an agent with no session Hive knows of or a model with no price, shows as Unknown or + ?, never as $0.
• On the card. The bottom of a card's panel says, for example, cost: ≈ $1.84 · 2 rounds. Hover it for the builder's and the reviewer's parts and their tokens (input, output, cache writes and reads, requests).
• In Performance. A Cards table lists the cards worked on in the range, with their cost, the builder's and reviewer's parts, their review rounds and when they were last held. Sort by any column (unknown costs go last); click a row to open the card. In a project's Performance tab, only that project's cards.
• On a lane. In the Progress panel, hover a lane's top line (the pair and its count) for what the lane cost since it started, split into on cards and overhead: what its builder and reviewer used while holding no card, such as merging, watching for a verdict and compacting. It also says the cost per finished card.

Time an agent spends between cards, such as reading a card it was just woken for before taking it, is overhead, not the card's. While an agent holds several cards at once, what it uses then is shared between them equally. A reported charge is split only between the requests it covered, so a card's cost never changes because of work done later; where a card took only some of a charge's requests, its share is marked ≈. Copilot reports its tokens only when a session ends: until then a Copilot card's tokens show as unknown, and then Hive spreads them over that session's requests, marked ≈ (its cost comes from Copilot's own charges). Cards worked on before Hive kept this have it worked out from their history, by the agents' names.

Comparing before and after

Compare (at the top of the Performance page) puts a baseline next to a run, to see whether a change made Hive's traffic and guidance smaller while the work still got done:

• Keep current view saves what the page shows now (its scope, range and filters). Keep one before a change and another after it, then pick them as Baseline and Run. They are compared per hour Hive was recording, with what makes either partial noted. Real use isn't a controlled workload, so a difference can be the work that was done.
• Import… reads a Performance export or a scenario benchmark: the benchmark.json that Hive's development scenarios write (tests/scenarios in Hive's source). A benchmark compares scenario by scenario, correctness first: smaller, still correct only if every check that passed still passes and still runs, and no more calls, failures or retries were made. A smaller result that lost a check is smaller but failing, not an improvement. The table shows the checks passed ✓, failed ✗ and skipped – on each side; click a scenario for every measure, its samples and spread, and which checks changed. Something that wasn't measured shows as unknown, never as zero, and a scenario that wasn't fully measured isn't judged.
• If the two measured different things (other scenarios, provider, model or filters, or a fake against a real model), the page says Not comparable and why.
• The scope is the page's: the whole workspace, Workspace's own work or one project each keep their own list. A project's Performance tab compares only that project's own kept views and exports; given a workspace export, it asks before using that project's part, and an export that holds other projects' data is refused. Scenario benchmarks are compared with the whole workspace selected.
• While comparing, the range and filters of Now are hidden: each file keeps the ones it was made with (shown above the table). They only shape what Keep current view saves.
• A fake provider's token counts are simulated, so they're never compared; a model trial's are, when both report them.
• Up to 20 are kept in the workspace's .hive/metrics/benchmarks folder (this machine's); when it's full, the oldest unpinned one goes. Pin one to keep it. If the folder's list is damaged, Hive rebuilds it from the files it finds (keeping the old list aside) and says so: nothing kept is deleted for it. Files Hive can't account for go to the folder's quarantine subfolder instead of being deleted. A removal that can't finish (a file in use) is retried later, and the comparison doesn't come back to the list.

Progress panel

Long runs, such as test suites and builds, can report their progress to Hive, and the Progress panel shows them: which agent is running what, how far along it is and about how long is left. It sits on the right, beside the Hive Assistant's panel. Show or fold it with Ctrl+Alt+P (Toggle Progress Panel); each workspace remembers whether it's open, and dragging its left edge makes it wider.

• Folded, it is a narrow Progress strip down the right edge with a small bar for each run, so you can see something is going without giving it room. It has bars for the newest six; more runs show as +N under them (red when one of those failed, amber when one stopped reporting), and hovering it lists them. It never opens by itself; click the strip to open it.
• Each run shows the agent and its project, what is running ("e2e: 12 suites"), a bar, the step ("4 of 12: carddialog"), how long it has taken and, once Hive has an estimate, about how long is left. A run that doesn't report steps shows a moving bar and the time. Long titles end in "…" (hover for the whole command). Click the agent's name to show that agent: its pane flashes and its terminal takes the keyboard, also when it was already on screen (from the keyboard, Tab to the name and press Enter or Space). If you press a key or click somewhere else before the terminal appears, the keyboard stays where you put it.
• Details: click anywhere else on a run, or on one under Recent (or the chevron at the end of its row, which points down while the details are closed and up while they're open), to see everything Hive has for it: the command (with Copy command), the agent, project and provider, when it started and ended (in your date and time format), how long it took against what was expected, its steps, its state and why, the exit code, a log or run record when the command named one, and a failure's summary. Copy details copies all of it as text, a line per field, ready to paste to the Assistant. Open log opens the log in its app and Show in folder shows it in Explorer, wherever it is; if the log has gone, Hive says so. Show the agent is there too; for a script's run, or one whose agent has since been removed, it says why there's no agent to show. Escape closes the details.
• Filter by project: when the runs come from more than one project, a dropdown at the top shows All projects, or one project's runs (running and under Recent alike), or Assistant and scripts for runs that aren't a project's. Choose a project with several agents and a second dropdown narrows it to one agent. The merges and lanes on top follow it too: one project's merge, or the merge its agent holds or waits for. Each workspace remembers its choice, and the folded strip shows only those runs too, with a filter mark and how many there are in all.
• When a run ends: a passed one shows ✓ and the time it took for a few seconds, then fades into Recent. A failed one shows ✗ and stays until you've seen it (the panel open while you use Hive), then a few seconds more, and then goes to Recent too, marked red; the strip's and the taskbar's red clear as soon as you've seen it. A run that stops reporting for longer than expected says Stopped reporting (one whose agent stops says so), and goes the same way. Dismiss (✕) moves a failed or stopped-reporting one to Recent at once. A run that was interrupted (Ctrl+C) says Stopped, and one whose command was ended before it could say how it went (an agent stopping a preview server it ran with hive-progress) says Ended without a report: neither is a failure, so they show muted, and fade into Recent like a passed run.
• Waiting runs: a run that is queued, such as a test run waiting for a test slot while other heavy runs finish, says what it waits for and how long it has waited, with a still, hatched bar; it shows no time left until it starts, and the wait doesn't count against its usual time. A run that takes longer than its estimate says finishing, then longer than expected, never "0 s left".
• Recent shows the last 10 runs that ended. Below them, Show all n lists every run Hive keeps, the last 200 in each workspace, in a box of the same height that scrolls, so the rest of the panel stays where it is; Show fewer folds it back. Each workspace remembers which you chose. The filter applies to all of them, and n counts the runs it shows. Recent is kept when the workspace closes and when Hive restarts; runs still going at that moment aren't (their commands can't report to the new Hive), and turning the Progress panel off in Settings forgets it.
• The taskbar: while runs are going, Hive's taskbar button fills with their combined progress (a moving bar for runs without steps), and turns red when one fails, until you look at the panel. So you can keep an eye on a long run from another app or with Hive minimised.
• The Assistant can see an agent's progress too, so you can ask it how long until an agent's tests finish.

Runs come from what agents run: a tool or script reports through the Agent API (/v1/progress, see the Agent API reference), as the agent that started it. Settings → General → Progress panel turns it all off; agents can still report, and Hive ignores it.

Merges and lanes

When agents work in pairs, a builder and a reviewer taking cards in turn (the card-loop skill), the Progress panel shows how they are getting on, around the runs:

• At the top, the merge going on. While an agent is merging (it holds a project's merge slot), a card in the merge colour, teal, says who is merging which cards (B1 is merging #484), which branch goes where (hive/b1 → main), the step its checks are on (the agent's running progress, such as Full test set · 113 of 146), how long it has had the slot and has left, and who is waiting. Release frees a holder that is stuck, after a question. The chevron folds the card to one line; each workspace remembers it. The card goes when the merge is done, and a line under it parts it from the runs.

• At the bottom, the lanes. Each lane is a row: the pair (B1 / R1), what the lane is about, the card being worked and how many of its cards are finished (2/8), then a bar with a segment for each card, in the order they are worked. Each segment shows where its card is, by colour and pattern, so it reads without colour too:

  • To do: an empty segment.
  • Doing: blue stripes, moving.
  • In review: an amber outline.
  • Passed (reviewed, waiting to be merged): green, with a light edge.
  • Done (merged): a dimmer green.
  • Blocked, or On Hold waiting for you: red cross-hatching.
  • A failed review underlines the segment in red until the card goes back for its next round.

  Hover a segment for the card, where it is and its round (#405 Built-in loop wakes · Review, round 2), and what its marks mean: a red underline the review that failed and the round it waits for, with the reviewer's one-line gist (#650: review failed (round 4): waiting for round 5), red hatching why the card is blocked or On Hold. Click it to open the card. When a lane has more cards than fit, its finished ones fold into one ✓ n segment at the start. A paused lane (a card waiting for you, and nothing else being worked), a merged one and an abandoned one (an agent of it removed) say so. A merged or abandoned lane is greyed and still, and shows its cards as they were when it stopped (a lane that stopped before Hive kept that shows dashed outlines: not recorded), so a card another lane has taken on never shows as worked in two lanes. Running lanes come first, newest first, then paused ones; merged and abandoned lanes go to the bottom in the order they stopped, so the one that stopped last is always last. To put the running lanes in your own order, drag one up or down by its row: a line shows where it will go, and near the top or bottom of the list it scrolls. With the keyboard, Tab to a lane and press Alt+Up or Alt+Down; a lane's right-click menu has Move Up, Move Down and Usual Order, which goes back to newest first. Each workspace remembers your order, after a restart too. A lane started later comes in on top, above the ones you moved, and a lane that stops leaves your order for the bottom. The lanes sit at the bottom of the panel and grow upward; up to four show, then they scroll. To see more, drag the line above Lanes up (down for fewer): it moves a whole lane at a time, up to all your lanes, and stops where the runs above still have room. In a smaller window it shows the whole lanes that fit, and goes back to your choice when there is room. Double-click the line to go back to four. With the keyboard, Tab to the line and press Up or Down. Each workspace remembers how many you chose, after a restart too. Click Lanes to fold them down to that bar (each workspace remembers it); opening them again keeps the height you chose. The project filter applies to lanes too.

With no lanes and no merge going on, the panel is just the runs, as before.

Show progress for any command

Any command can show in the panel by running it with hive-progress in front, for example hive-progress -- npm test. Agents do this by themselves for tests, builds and other commands they expect to take more than about 30 seconds, in the background too, so you see them without asking. To have them do it only when you ask, turn off Settings → General → Agents show long commands in the Progress panel (agents started or restarted afterwards follow it; with the Progress panel off, they don't use it either). The panel shows the command under the agent's name with the time it has taken and, from the second time, about how long is left (from how long the same command took before). The command's output and result are unchanged, and outside Hive it simply runs the command.

A command shows real steps when it prints lines like ##hive-progress step=4 total=12 name=carddialog; any project's test runner can print them (see the Agent API reference). A total printed after a slow start still counts: the bar moves without steps until then, and shows them from then on. hive-progress is on the path of every session Hive starts, in Claude Code's and Codex's shells. A command that reports its own progress, such as Hive's own test runners, still shows as one row when an agent wraps it.

Stopping a hive-progress command (Ctrl+C where it gets one) gives it 5 seconds to end by itself, then ends it with everything it started, such as the server under an npm or .cmd command. Hive checks when each of those processes started, so a process that only looks like the command's (an older one whose own parent had the same process number before it ended) is left running. If Windows won't list the processes, only the command itself is ended.

Task board

The Task Board (in the activity bar, or Ctrl+Shift+J) is the workspace's list of work, as cards in six columns: On Hold, Todo, Doing, Review, Passed and Done. You, the Hive Assistant and the agents all use it, so it's where you can see at a glance what is planned, what is being worked on and what is waiting for you.

• Cards. Each has a number (#12), a title, a description (Markdown: what to do and how to tell it's done), a project, and optionally the agent working on it. Add labels, mark it blocked with a reason (it shows in red; a long one shows its first three lines on the card, and all of it when you hover it or open the card), list the cards it depends on and related ones, and comment. Its history shows who changed what and when: you, the Assistant, or an agent. New Card (or Ctrl+Alt+T) adds one. An open card can be moved out of the way, as any dialog can: drag it by its header (Escape while dragging puts it back; see Moving dialogs).
• Decisions. What you decide about a card (scope, wording, a default, "option B") goes in its Decisions, pinned above the comments, not in a comment where it gets buried. Add one at the bottom of the list (Add Decision, or Ctrl+Enter); change or remove one with its pencil and bin. Each says who wrote it down: you, or the Assistant or an agent you told (it is still your decision; only you change or remove one), and new since start when it came after work on the card began. Agents read a card's decisions when they start and again before they move it to Review, and follow them where the description says otherwise; reviewers fail work that ignores one. Recording one while an agent works on or reviews the card doesn't interrupt it: its next reply from a Hive tool says the card has a new decision, and it checks at its next step; a reviewer reads the card again at each round. An agent waiting for your answer (it asked you something and its turn ended) hears of it too, so you don't have to paste your answer into its pane (agents take a card, moving it to Doing, before they ask you about it, so a question about a card in Todo counts too): once nothing is in the way (it isn't working, showing a question or permission prompt, or watching cards, and you aren't typing in its terminal), Hive rings its doorbell, and it reads the line in its inbox ("[Hive] #392 has 2 new decisions from the user: read them (hive_read_task) and carry on from where you asked."). Decisions recorded together come in one line, about 15 seconds after the last; each is told once, and the card's history says whom Hive told. A card with decisions shows how many on its tile (hover for them) and on the agent's card chip. An open card can be moved out of the way, as any dialog can: drag it by its header (Escape while dragging puts it back; see Moving dialogs).
• The columns. On Hold is for work you've parked: nobody picks it up until you move it to Todo, and only you and the Assistant put cards there (an agent that tries is told to ask you). Todo is ready to start, Doing is being worked on and Review is waiting for its review. A card that passes its review goes to Passed: reviewed, but not merged yet. Done means merged: the agent that built it moves it there once its branch is merged, or you do. A blocked card stays where it is, marked in red, in any column. Cards On Hold or in Passed are never called stalled.
• Fold what you don't need. The « in a column's header collapses it sideways to a narrow strip (its » opens it again) with its name and how many cards it has; the other columns widen to fill the board, and a click on the strip (or Enter) opens it again. Drop a card on a strip and it goes to the top of that column, even while a search hides some of its cards. Each card has an arrow too, which folds it to one line: its number, its title, its agent's dot and any blocked or stalled marker; a folded card still opens with a click and drags like any other. A column's ⋯ (or right-click its header) has Collapse All Cards and Expand All Cards. Hive remembers which columns and cards you folded, for each workspace, after a restart too; a new card starts open.
• Moving cards. Drag a card to another column, or within one to reorder it, or right-click it for Move to. In a long column, hold the card near the top or bottom of the column and it scrolls until you can drop the card where you want, even at the very top or bottom. Moving a card into Doing from another column (dragging it, Move to → Doing, or changing Column in the card dialog and saving) asks who works on it: Nobody yet (it goes to Doing with no agent, also taking it from the agent it had), Assign an agent (any agent of its project, busy ones too; nothing is sent to it and nothing starts), or Assign and start, which starts the card as Start… does. The card's agent is the default. Cancel leaves the card where it was, with its agent; in the card dialog your other changes stay unsaved until you choose. Reordering within Doing doesn't ask. Ask the Assistant to move a card to Doing and it asks the same, unless you've said ("have Claude start #12", "assign #12 to Claude without starting it"). A column's order is its priority, top first. Agents and the Assistant can put cards in order too: ask "put the bugs at the top of Todo" or "prioritise Todo" and the board changes as you watch; each card they move says so in its history. The order of Done stays yours. A Doing card shows what its agent is doing right now (working, waiting for you, finished…); a green edge means its agent has finished and the card is waiting for you to look. Nothing moves by itself: agents move their cards to Review when they're done.
• What each agent is working on. An agent with a card in Doing shows it as a small chip: #4 (+1 when it has more, an eye when it is reviewing one) on its tab in the agent strip, in its pane header and in the Assistant's workspace list, so it takes little room; hover it (or the tab) for each card's number and title. The Overviews' running lists show the title too. Click the chip to open the card. Hover the project in the sidebar to see each agent's card. The Sessions tab shows which cards a session worked on.
• Colours. Each column has its own colour (On Hold grey, Todo slate blue, Doing blue, Review purple, Passed teal, Done green) on its heading and as a light tint on its cards, so a card's colour shows where it is. Change them in Settings → Board → Column colours, or turn them off with Colour columns.
• Each agent works on its project's cards. An agent sees and changes only its own project's cards: another project's are for that project's agents, the Assistant and you. A card it adds is its project's, and a card linked to another project's shows that card's number only. The Assistant and your board see everything. Moving a card to another project takes it from its agent (its history says whose it was), so give it to one of the new project's agents afterwards; the card dialog does that for you when you change both. Ask an agent to "check the latest comment on #65" and it reads just that comment, not the whole card.
• Review, Passed, then Done. An agent you give a card to in its conversation ("task #59 please") moves it to Doing when it starts, also when the card is back from Review, Passed or Done with more to do; when that work is done it goes to Review, even if it was in Done before. Agents move a card to Review when they finish its work; a reviewer moves it to Passed when it passes. Done means merged: an agent moves its cards there after merging its work, or when you ask ("merged, move #65 to done"); the Assistant too. Every move is in the card's history with who made it, and you can move a card back out of Done at any time, or ask an agent to. Putting Done in order, archiving and deleting stay yours. Archive a card when you no longer need to see it; deleting sends it to the Recycle Bin. Archived (n) in the board's toolbar shows the archived cards as a table, the most recently archived first: sort by any heading, filter by number, title, agent, project, label or the column a card was archived from, and choose how many rows a page shows. The board's search narrows it too. Click a row to open the card. Unarchive brings a card back to the end of the column it came from; tick several (or the box in the heading, for every card the filters show) and Unarchive Selected brings them all back. Archive a whole column, or the whole board. A column's ⋯ has Archive All in Done (23)… (every column, with its count), and the ⋯ beside New Card has Archive All Cards…, which counts the cards per column before you confirm. Cards an agent is on (working on in Doing, reviewing, or waiting on) are left where they are and listed; tick Also archive cards agents are working on to take them too (their agents lose the card). While a search or the sidebar's project hides some cards, it reads Archive the 5 Shown (of 23)… and archives only the cards you can see. Afterwards Archived 23 cards offers Undo for a few seconds, which puts them back in their columns, in their order; later, pick the batch in Archived → Batch and Unarchive this batch does the same (a card whose neighbours have gone goes to the top of its column). A card an agent picks up while you confirm stays on the board, and the toast says so; a card Hive can't bring back (its file open in another program, say) stays archived with its batch, so you can try again.A card in Doing that nobody is working on (no agent has it, or its agent was removed or isn't running) shows as stalled, in amber, and the board's sidebar lists these under Stalled; start it again or move it back. An agent that moves a card into Doing takes it, so its card doesn't show as stalled: also one another agent had in Todo, Review, Passed or Done (the history says so), but not one already in Doing with someone else. When you remove an agent that still has open cards, Hive asks whether to move them back (Doing ones to Todo, with nobody) or leave them. The Assistant points out stalled cards when it looks at the board and suggests who could take them, but asks before changing anything. Cards in Done are archived for you after 14 days there; change that, or turn it off with 0, in Settings → Board → Archive Done cards after.
• An agent reviews a card. Ask an agent to review one ("review #87"): the card stays in Review with the agent that did the work, and shows Reviewing: Codex while it does (in amber if the reviewer has stopped or been removed). The reviewer's tab shows the card with an eye. Its verdict goes on the card as a comment. A card that passes goes to Passed; one that fails stays in Review for its fixes. One agent reviews a card at a time, and the review ends by itself if the reviewer stops or the card is moved. If the review finds things to fix, ask an agent to fix them: that is work on the card, which moves it to Doing.
• Start. Start… on a card gives it to an agent of its project, with the card as its prompt, and moves it to Doing. If you've changed the card, the button reads Save and Start…: your changes are saved first, so the agent gets the card as you see it. Choose an agent that is stopped (it starts a new conversation on the card) or idle (it gets the card as its next message), a new agent, or a new agent in its own worktree. The agent gets the card and Hive's work-on-card skill, which tells it to keep the card up to date and move it to Review when it's done. You can start a card in Review or Done again for more work: it moves to Doing, the agent is told it's back for more work and gets the card's latest comment (the feedback it came back with), and it goes to Review when that's done. Asked to have an agent act on review feedback, the Assistant does the same, with a note saying what to do.
• Nothing is lost by closing. Closing a card with unsaved changes, a half-written comment or decision, or a change to a decision asks Keep Editing or Discard. Save keeps everything you've typed in the card: it records the decision you're writing and posts the comment you're writing too, each once. While a box has text, its Add Decision or Comment button is highlighted and says so (Save adds it too); use the button, or Ctrl+Enter in the box, to add just that one and keep the card open.
• One project. The sidebar filters the board by project and lists the cards waiting for review; the badge on the activity bar counts them. Each project also has a Tasks tab with its own cards.
• With the Assistant. Ask it to plan work as cards, start them on agents and follow them: "split the login rework into cards for web and start the first two". Agents can add cards for follow-up work they find instead of doing it unasked.

The cards are kept in .hive/tasks, one file each, so a workspace you commit shares its board.

Card loops

Two agents can take a list of cards in turn, one building and one reviewing, without you passing each card between them. Tell one agent "work through #111 to #117 as the builder" and another "review #111 to #117 as they come in". Both use Hive's card-loop skill. The builder does a card and moves it to Review. The reviewer reviews it and passes it, or sends it back with findings; the builder fixes them and moves it to Review again. When a card passes, the builder starts the next one. The builder says which checks it ran, on exactly which code; the reviewer checks that record rather than running everything again, and runs the tests the change affects and its own probes.

A card sent back with findings stays in Review. The builder moves it to Doing while it fixes them, then back to Review; if it moves it to Review without it leaving, the card is returned for review all the same (Returned for review, round 2 in its history) and the reviewer is woken. You can return such a card yourself: right-click it → Move to → Review (next round).

• Waiting costs nothing. While one agent waits for the other, it isn't running: it ends its turn and Hive wakes it with a short line when the card changes ("[Hive] New in your inbox: 1 card event (#112) (m7). Call hive_inbox to read it."), and the agent reads what changed in its inbox ("#112 is in Review; latest comment by Codex…"). The agent shows a blue ring in the sidebar and Waiting for #112 → Review in its pane header.
• Hive wakes them itself, too. When a card arrives in Review, Hive wakes its reviewer, and when the review gives its verdict, Hive wakes the card's builder, even if that agent didn't set a wait (in its inbox: "#112 (B1's card) is in Review. You review this card in its loop: carry on with it…"). Only for cards with a reviewer (the reviewer of its lane, or the agent that last reviewed it), so a card nobody reviews never wakes anyone; only while the agent is idle (never typed over its work or your typing); never for the agent's own move; and not when the agent's own wait already tells it, so it gets one line, not two. The card's history says whom Hive woke ("Woke R1 (hive) to review it (a loop wake)"). To drive reviews by hand, turn it off in the project's Settings → Card loops → Wake reviewers and builders.
• A loop that stops waiting shows. If an agent in a card loop ends its turn without waiting (it said it was watching but isn't), or Hive's wake line sits in its prompt without being sent, nothing would wake it again. Hive puts its lines into Claude Code (agents and the Assistant) as a paste, so a line that arrives while Claude Code is busy for a moment is still sent at its Enter (a long one shows as [Pasted text #1] in the prompt until then). Hive presses Enter again when a wake line isn't taken; if it still isn't, the agent's pane says A line Hive typed wasn't taken and you're told once (click its terminal and press Enter: Hive types nothing more into it until then), and if the agent still sits idle with no wait, its card shows as stalled ("Stalled: Codex isn't watching #333: its turn ended with no card watch") and you're told once. Show the agent and ask it to carry on. An agent that ended its turn while its background tasks run (a long test run) isn't flagged when its CLI wakes it as they end (Claude Code does; Codex doesn't). A card that has waited in Review for 15 minutes since it arrived or came back, while its reviewer is waiting for it, without its review starting, shows as stalled too ("R1 is watching #333 but hasn't started reviewing it: in Review for 40 min"), on the board and in its lane's row in the Progress panel: show the reviewer and ask it to review the card. So does a card whose reviewer started its review and then went back to waiting on it for 15 minutes without a verdict or a question blocking the card ("R1 started reviewing #333 but has given no verdict, and has only been watching it for 20 min"): read its latest comment, which may ask you something, then show the reviewer and ask it to finish its review.
• A question for you blocks its card. When the builder or the reviewer needs your decision (a scope question, a finding the builder disputes, the last round failing), or the builder's merge at the lane's end needs your OK (its CLI refused a commit, say), it blocks the card with its question and notifies you, so the card shows as blocked on the board and the Assistant's lane watch picks it up. Answer it (to the Assistant, or as a decision on the card): Hive tells the agent, which clears the block and carries on.
• The Assistant can still reach a waiting or busy agent. It can't give a new task to an agent that is waiting, working or busy with a test run, but it can leave it a message (to pass on your answer, or add a card to its lane). An agent waiting on cards gets it at once and keeps waiting afterwards; a busy one hears of it at its next step, or before its turn ends. Until it has read it, its pane header shows ✉ 1 unread: hover it to read it, click it to cancel it.
• Messages are kept, and you can see where they got to. Each message has an id (m4) and is saved in the project, so it survives the agent stopping and Hive restarting. Hive types only a short line into an idle agent ("[Hive] New in your inbox: 1 message (m4). Call hive_inbox to read it."), never the message itself: the agent reads it from its inbox (hive_inbox), which is when it counts as received, and acks it when it has acted on it. Until the agent has read it you can still cancel it. Agents read their inbox with Hive's tools, so with Settings → Agent API or its built-in hive server off they have none: nothing the Assistant or Hive leaves them reaches them, and the sender is told why ("B1 has no inbox: turn on the Agent API"). A card you Start yourself still goes in, typed as your own input. One not acked within 30 minutes shows as ✉ 1 overdue in its pane. The Assistant sees each one's state and times in the agent's activity. A message still waiting when the Assistant that left it stops (or Hive restarts) is refused, not sent later, and the Assistant's activity list says so.
• Everything Hive tells an agent is kept the same way: a card watch's wake, a loop's handoff, your decisions, a mode change, a lock's go-ahead, a task. Each is saved, so a restart can't lose it, and each reaches the agent the same way: Hive types the short line, and the agent reads what it says in its inbox. None counts as delivered just because Hive typed it: a card watch ends once the agent has read its wake. An agent that let the line pass and went idle again without reading it hears it once more. One Hive was typing when it stopped, or that the agent's session lost before reading it, is offered once more after the restart, saying it may repeat ("m12 again: Hive restarted while offering it, so it may repeat").
• A busy agent hears of a message between its steps. A message for an agent that is working doesn't wait for its turn to end, and isn't typed over its work: at its next tool call Hive adds a short notice to what its CLI tells it ("[Hive] New in your inbox: 1 message (m4). Call hive_inbox now to read it, then carry on."), and if its turn would end with the message unread, Hive asks it to read it first. The agent reads the message from its inbox, labelled with who sent it, and acks it. Hive's notices only ever say how many items there are and their ids, never what they say, so text in a card or a message that claims to be from you ("the user says…") reaches the agent as a quote, not as your instruction. Agents act on what the Assistant relays of your decisions, and ask you before deleting work or doing anything outside their project, whoever asks. This works the same in Claude Code, Codex and GitHub Copilot. An agent that has ended its turn while a background command of its own runs (a sleep, a timer) counts as idle for this: its messages and card events reach it within seconds, not when the command ends.
• A message about a round goes stale, not late. When the Assistant relays something about a card's current round (a finding to fix, a change to the round), it ties the message to that card. If the card moves on before the agent reads it (it passes, leaves Doing and Review, or another review fails), Hive drops the message as stale instead of delivering it late, so an agent never reopens a passed card for an old finding. The agent's activity shows why ("stale: #699 passed review"), and so does the Assistant's activity list.
• Cancel in the pane header ends the wait (also Cancel Card Watch in the agent's ⋯ menu). Typing to the agent doesn't, and Hive doesn't wake it while you're typing there. A waiting agent takes no other work: the Assistant won't prompt it and Start… can't choose it.
• A card taken out of a loop. If you give a card another agent, or another agent reviews it, the agent that was waiting on it is told once ("#354 was reassigned to B4 (your watch on it ended)") and moves on to its next card, instead of waiting for a card that won't come back to it. A blocked card (waiting for your decision, say) stays in its loop, paused: its reviewer keeps waiting for it, and once you've answered and it's back in Review, it is reviewed as usual. On a card in Review, recording your answer, or clearing its block, doesn't wake the loop by itself (an agent working on the card, or waiting for your answer, hears of it anyway), so when the Assistant does it for you it also leaves the card's builder a message saying what you decided (and its reviewer, when it changes what they check). A wait on several cards keeps the others. The card's history says whose wait ended. Agents still on the card, and the Assistant, keep their waits.
• How long it waits. With no change for six hours, Hive wakes the agent, which tells you. Say "wait: 2h" for another wait, up to a day.
• Your defaults for loops. Settings → Workspace → Card loop rounds and Card loop wait set the rounds and the wait for every loop in the workspace that doesn't say otherwise (10 and 6 hours to start with), and a project can have its own in its Settings → Card loops. What you say when you start a loop ("rounds: 3, wait: 1h") always wins. Agents read them when they register the loop, so a change applies to loops started afterwards.
• Rounds. A round is one build and its review: a card that passes its first review passed in round 1, and each fix with its review is another round. When the tenth round's review fails, the agents stop and ask you what to do, with a line per round. Say "rounds: 15" to allow more, or "rounds: 3" for fewer. A finding that comes back because a fix missed part of it doesn't stop them sooner: the reviewer marks it recurring and it is another round. A finding the builder disputes does: they stop and ask you.
• Passed, then Done. The reviewer moves a card that passes to Passed. Once the builder has merged its branch (when you ask it to, or have said it may), it moves its Passed cards to Done, which means merged.
• Clear wake lines. The line names the reviewer when a review passed or failed ("#112 is in Review: Codex (hive) failed it"). An agent waiting on another agent's card (one its own card depends on) is told whose card it is, and that Passed isn't merged: "#111 (Claude's card) is in Passed: Codex (hive) passed it (Passed isn't merged)". Passed means the review passed; the work is merged when it reaches Done.
• Nothing waits for what has already happened. A wait for a card to reach a column it is already in ends at once: a builder that starts waiting for "→ Passed" after its card has passed carries on straight away. A reviewer waiting for a failed card to come back asks for its next round explicitly, so it keeps waiting while the card is still in Review.
• Cards reviewed together. When two watched cards change at about the same moment (one passed, the other failed), the line names both. A change that lands just after an agent was woken still reaches it: its next wait counts what others changed since its last wake.
• Closing Hive or stopping an agent keeps its wait: resume the agent and it is woken if its card changed meanwhile. Hive asks first, as it does for a working agent, and says what it waits for. Quit when agents finish waits for a waiting agent only while the other agent is working on its card.
• While it waits you can still Compact it (it is woken once that's done). Merge… waits until it has finished, or until you cancel its wait.
• Hive knows its loops. Each loop is kept as a lane: its builder and reviewer, its cards in order, its rounds and its wait. The builder registers it as it starts and the reviewer joins it; you don't set anything up. Hive follows the board from there: the lane is on the card being worked, paused while it waits for your answer (its next card is blocked and no other is being worked; a builder that moves on to another card meanwhile keeps it running), and ended once its cards are all Done. A lane whose builder or reviewer you remove is abandoned. Ask the Assistant "which lanes are running?", or read them through the Agent API. One agent working on a card on its own has no lane, and a loop works the same if a lane can't be registered.
• Reports start with the gist. An agent sending a card to Review starts its comment with one line saying what is ready, and a reviewer starts its verdict with one line ("Round 1: FAILED: 2 findings: …"), the details below. Agents and the Assistant read just those lines when the gist is enough, so long reports cost less to follow.
• The Assistant watches whole lanes. Running several lanes, the Assistant waits on all of them in one go and is woken only when something needs it: a review fails, a card is blocked (a question for you) or stalled, a lane's cards have all passed so its merge is due (and again if that merge then stalls: its builder idle for 10 minutes without taking its turn to merge), or a lane ends. A card simply moving on, or passing, doesn't wake it, and a lane started later, or a card added to one, is followed too. Its status says Waiting on all running lanes. The same watch follows cards in no lane that it keeps an eye on, such as a release card (Waiting on all running lanes and #720): a comment, a move, a verdict or a block on one wakes it too. And when any agent starts waiting for you (a permission prompt or a question in its pane), the Assistant is woken once, told which agent, its card and what it asks, so it can tell you; it never answers for you.
• Each lane in a new conversation. When the Assistant starts an agent on its next set of cards (a new lane), it gives the agent a new conversation in the same step: the old one ends and stays in the Sessions tab, and the new one starts on the task, with no handover. Within a lane, the agent keeps its conversation. Every request re-reads the whole conversation, so short ones cost much less. The Assistant doesn't do it while the agent is busy, waiting for you or watching a card, or just after you typed in it.

Hive Assistant

Each workspace has a Hive Assistant, its overseer, in a panel on the right. Show or hide it with Ctrl+Alt+I; hidden, it folds into a narrow Hive Assistant strip down the right edge, and clicking the strip opens it. Each workspace remembers whether it's open, and dragging its left edge makes it wider (double-click the edge for the default width). Hiding the panel doesn't stop the Assistant.

On the left instead. If Windows notifications or other apps cover the right of the screen, put the panel on the left: View → Move Assistant Panel to the Left (also in the command palette and the panel's ⋯ menu), or Settings → Assistant → Panel side. There it sits between the project list and your work, folds into its strip on that side and widens from its right edge. The choice is the same in every workspace and window, and Hive keeps it when it restarts.

Ask it anything about the workspace: what the agents are doing, what a project is, what changed, what things cost, or for a plan or a review. It reads any project's files and uses Hive's own tools to see projects, agents, usage, shared notes and handovers. It doesn't edit project files itself: the agents do the work. What else it may do, from only advising to running agents and creating projects, is up to you (see What the Assistant may do below).

The panel. At the top: its mode (click to switch), Compact and Stop while it runs; when it doesn't, Resume (|▷) to go back to its last conversation and New conversation, or Start if there is nothing to resume (in ⋯ when the panel is narrow, apart from Resume), and ⋯ (New Conversation while it runs or Resume when it doesn't, Resume a Conversation…, All Conversations…, Assistant Settings…, Manage Modes…). Under it, one line says what the Assistant is doing, after its own icon (in the status's colour, as agents' dots are, filled while it runs something, with an agent's status dot on its corner): Status: Working, Idle, Waiting for you (in the attention colour, when it asks you something), Waiting for your approval (when one of its actions needs your answer on a card under the line, such as stopping a busy agent), Not running, or the cards it is watching and until when ("Waiting for #12 #13 → Review (watch until 22:22)"), each card the same chip as elsewhere in Hive, in its column's colour: click one to open the card; or the agents it is watching ("Waiting for B6 to finish (watch until 22:22)"). Hover the line when a narrow panel cuts it short. Under it, once the Assistant has changed something, Done by the Assistant: its last 3 changes, newest first (hover one for when it was and, if it wasn't done, why). Show all lists every one in the same space, scrolling, so the terminal keeps its size; click the section's title to fold it away and give the terminal the room (remembered for the workspace). Then the workspace at a glance: agents waiting for you (or in trouble) first, then your active projects, each with its agents listed under it, and clicking one takes you there. The arrow before a project's name folds it to one line (click it, or Enter or Space): its name, the dot of its agent that most needs you and how many of its agents are running. Each project stays as you left it, for this workspace. Each agent shows the card it's on (#4, click to open it) and what it's doing, on a faint backing in its status's colour: a soft wash while it works, a light hatch while it waits on cards or for you, nothing while it's idle or stopped. It shows how far its tests or build have got ("e2e: 12 suites 4/12"), the background tasks it waits on, or the cards it's watching. In a narrow panel that line ends in "…"; hover the agent for its status, every card with its title, its progress and its worktree's branch. Inactive projects fold into one row at the end; click it to show them. Drag the line under it to give it more or less room. Then the Assistant's terminal, and a footer with its model and effort, permission mode, context and cost, as agents have. While it isn't running, the panel offers Start Assistant, Resume and its past conversations. While the panel is hidden, the strip shows the Assistant's icon and status dot. The same icon (a hive cell with a crown) marks the Assistant wherever it's listed: its runs in the Progress panel, the inbox and the Workspace Overview.

Waiting on agents. Ask the Assistant to tell you when an agent is done (a build, a test run, a release step, a push and its CI) and it doesn't keep checking on it: it starts an agent watch and stops, and Hive wakes it with one line when the agent finishes, needs you, or stops ("[Hive] B6 (hive) finished: "The installer is built…""), and it tells you. Meanwhile its status line says Waiting for B6 to finish. An agent just given a task counts as busy until its CLI takes it, so a watch started straight after doesn't answer at once that it is idle before the work has begun: a task typed into it, or one it was started with (a card's Start, a new agent's prompt, a task in a new conversation), which its CLI takes only once it is ready. Hive waits for that at most 30 seconds (after typing it, or after the agent became ready). A question or sign-in its CLI shows as it starts still ends the wait, as needing you. As with a card watch, Hive doesn't wake it while you're typing to it, and after two hours with nothing done it is woken to say so (it checks on the agent, and tells you if it seems stuck). Agents can watch another agent the same way.

When you answer an agent yourself. If you reply to an agent by typing in its pane (picking an option it asked about, say), the Assistant doesn't otherwise know. When it is watching that agent, or a card the agent has or reviews, Hive tells it with the first line of what you sent ("User replied to B1 on #399: "C, the hive cell"", or by the name you set in Settings → General → Your name: "Darren replied to B1…"), so it doesn't ask you again and can record a decision on the card. Only the Assistant of the same workspace is told, and only the first line. Lines Hive types into the agent itself don't count. Turn it off with Settings → Assistant → Tell the Assistant when I reply to an agent.

It doesn't use one of a project's agent slots, and it runs in the workspace folder. Closing the workspace or the window, or quitting, stops it like any agent (the dialogs call it "Assistant"), and its conversations can be resumed.

What the Assistant may do

Settings → Assistant → Control decides, for every workspace:

• Look and advise: it reads and suggests; you act. It can still tell you which card loops (lanes) are running.
• Control agents: when you ask it, it also adds agents, changes their settings, starts and stops them, gives idle ones tasks, hands one agent's work over to another, and adds, changes and starts cards on the task board. Ask "add two agents to web: one to fix the login tests, one to update the docs", or "ask Codex to review hive, then hand its findings over to Claude to fix", and it does.
• Control agents and create projects (the default): also new projects.

It never removes agents, discards worktrees, archives or deletes cards, or removes projects, and never edits project files itself: the agents do the work. It won't type into an agent that is working, asking you something, or that you have just typed in: for 15 seconds after your last key, unless that key was Enter (Settings → Assistant → Pause after you type and Enter ends the pause). Before it stops an agent in the middle of something, or moves a card to Done, a card at the top of its panel asks you (Stop or Don't stop, Move it or Leave it). It makes at most 30 changes for each message you send (moving or labelling a set of cards in one step is one change, however many cards it has, so it never stops part-way through them), and everything it does is listed under Done by the Assistant in its panel. Your view never moves: an agent it adds on the project you're looking at shows a dot on its page's button, and another project opens on the new agent's page the next time you go to it.

When an agent's CLI asks whether to trust a new folder before it starts, the agent shows as waiting for you: answer in its terminal.

The Assistant and Hive's settings

Hive has a lot of settings. Ask the Assistant what one does ("what does Warn when a transcript is over do?") or how to make Hive behave differently ("the chime is driving me mad"), and it finds the setting, explains it and says where it is. It reads the same descriptions Settings shows. When it notices something a setting would help with, such as a transcript growing very large or several agents editing the same files, it suggests that setting in a line, and changes nothing unless you agree.

To let it make the change for you, turn on Settings → Assistant → Control → Change settings (off by default; a running Assistant takes it after a restart). With it on, the Assistant changes a setting when you ask it to or agree to its suggestion, in Settings or in a project's Project Settings. Each change shows under Done by the Assistant with the old and new value and a Revert button that puts the old value back. Some settings stay yours whatever you allow: its own Control and the other Settings → Assistant permissions, permission modes, the Agent API, and what Hive runs (CLI paths, extra arguments, a project's setup command). For those it tells you where to change them. An agent's own model, effort or mode is part of running agents (Control agents), not of this switch.

The Assistant view

The Hive Assistant button in the activity bar (the robot) opens everything else about it. At the top, Used so far: its conversations, prompts, tokens and API-equivalent cost, for Today, 7 days, 30 days or All time. These aren't counted in any project's Overview. Below that:

• Modes lists its modes (below).
• All Conversations shows every conversation you've had with it, in the same tree as a project's Sessions tab (by provider, with any sessions a conversation started under it). Search them, read any in full, export, rename, archive, delete or resume one, or archive or delete a whole branch. Show on the running conversation opens the panel.
• All Attachments shows the screenshots and files you've pasted or dropped into its conversations, grouped by conversation, newest first, like a project's Attachments tab. Click one to view it, or right-click it to copy or reveal it. Click a conversation's name to read it. The bin next to it moves all of that conversation's attachments to the Recycle Bin (none if another program has one open). Attachments of a conversation that is running can't be deleted until it stops.

The panel's ⋯ menu opens the same view with All Conversations… or Manage Modes…; the command palette has Show Assistant Conversations, Show Assistant Modes and Show Assistant Attachments.

Modes

A mode is how the Assistant works: what it puts first, its habits, and the shape of what it hands back. It is written as instructions in a Markdown file in the workspace's .hive/personas folder. Hive comes with four:

• 🧭 Coordinator (the default): runs the work across your agents. It checks the board and the agents before acting, reports in short status tables, starts agents on settled cards, follows the lanes until they end, checks what agents report, and asks you only for real decisions. With a team (three or more agents, builder and reviewer pairs, or agents in worktrees) it plans lanes by the files they touch, briefs each builder and reviewer in full and watches every lane to its end; with one or two agents it stays light, and at most suggests more structure in a line. Either way you can still use card loops, reviews and everything else.
• 🗺️ Planner: shapes work before anyone starts it. It leads with the open design questions (a recommendation each), compares options, splits the work into lanes by the files it touches, and writes complete cards.
• 🔍 QA triager: turns a report (what you did, what you saw) into a card. It reproduces the problem or reads the code to find the likely cause, says what it checked, and files the card with the evidence and a proposed fix in the right lane.
• 📦 Release manager: takes a release through the project's checklist (release notes, licences, the packaged build), and changes the version, tags or publishes only when you ask.

A mode never changes what the Assistant may do: that is Settings → Assistant → Control, whatever a mode says, and how it runs agents and cards comes from Hive's own skills. When a request clearly fits another mode, the Assistant may suggest switching in a line; it never switches by itself.

Switching mode (the mode menu in the panel's header) takes effect at once and keeps the conversation: Hive tells the running Assistant the new mode and its habits in a short line ([Hive] Mode: Planner …), or tells it as soon as it has finished what it is doing. Its next conversation starts in that mode, and if you switch while it isn't running, Hive tells it the mode the same way when you resume its conversation (once). Restart in This Mode… (in the same menu) resumes the same conversation with the mode's full instructions; it caches the whole conversation again, so it costs more than switching.

The Modes section of the Assistant view lists them. Click one to read or edit it, + to write your own, and the bin (on hover, or at the top of an open one) to delete one. Hive's own come back with Restore or Revert to Default, and Hive keeps them up to date in each workspace as it does its skills: one you've edited stays as you wrote it. Use in This Workspace makes one the Assistant's. A mode of your own can have a summary: in its header (its habits in a few lines), which is what Hive tells the Assistant when you switch to it; without one, Hive uses the first lines of its instructions.

From personas to modes. Up to 0.3, Hive shipped character personas (Overseer, Planner, Reviewer, Orchestrator). The modes replace them: a workspace's unedited copies go, and an Assistant that used one moves to the closest mode (Overseer and Orchestrator → Coordinator, Reviewer → QA triager), which Hive says once. Personas you wrote or edited stay as they are.

Assistant settings

Settings → Assistant sets the defaults for every workspace:

• The provider (Claude Code or Codex, whatever your agents use).
• The default mode (Coordinator unless you choose another).
• Tell the Assistant when I reply to an agent (on): whether its watches hear the first line of what you send an agent from its pane (above).
• Highlight Compact over: the context size at which the Assistant's Compact button and the context in its footer turn orange, as an agent's do past Settings → Sessions → Suggest compacting above. It's 500,000 tokens by default, higher than your agents' 200,000, since the Assistant usually works with a bigger context; Never turns it off.
• For each provider: its model, effort, permission mode, extra arguments and, for Claude Code, Use 200K context (instead of 1M).

It uses the same model and effort as your agents (each provider's defaults in Settings), since a lighter model or low effort makes it careless: it may say it will check on an agent later and never do. Its mode, like your agents', approves safe actions itself and only asks about risky ones: Auto for Claude Code and Approve for me for Codex. Claude Code says which models it runs in Auto, for your version and account (currently not Haiku), and the settings warn you when you pick a model without it in Auto, for the Assistant or an agent: the session then runs in Manual instead (asking before edits and commands), and Hive shows that mode. Assistant Settings in the panel changes any of them for one workspace. Changing its provider restarts it, after asking; a new mode is told to it at once. Its provider is for new conversations: an earlier conversation always resumes in the provider it ran in, so you can go back to a Claude Code conversation after switching the Assistant to Codex, and the other way round.

Skills

Skills are instructions an agent loads when they're relevant. There are no switches: every skill an agent can see is always available to it. Hive shows where each one comes from:

The Skills view (the sparkle in the activity bar) lists the workspace's Hive skills. + creates one from a starter SKILL.md; Add Skill from File adds a .md (it becomes the skill's SKILL.md) or a .zip (unpacked as the skill's folder: use a zip for a skill with scripts or other files). Select a skill to read it; Edit changes it, and the bin deletes it (to the Recycle Bin). A warning over the list, and over a Hive skill while you edit it, reminds you that editing these skills may change how agents behave in Hive: they're instructions every agent (or the Assistant) follows.

A project's Skills tab lists everything its agents get: the Hive skills first (those for the Hive Assistant alone aren't listed; a note under them says how many there are), then one provider's local skills, your user skills and plugin skills, folded under its name: click it to open them. Pick the provider from the dropdown above them: it starts on the project's default provider. Hive remembers, for each project, the provider you last picked and which groups you left open or folded. Hive skills are shared by every project, so their Edit in workspace button takes you to the Skills view to edit them there. Local skills belong to the project: add (with + or from a .md or .zip), edit and delete them right there. When both Claude Code and Codex are on, adding a local skill offers to add it for the other provider too, since each reads its own folder. Copy to workspace turns a local or user skill into a Hive skill: the project agents in every project get it, unless its header names another audience (the notification says who).

Skills that come with Hive. Hive gives every workspace its own skills for working with Hive:

• for agents: work-on-card (carry a card from Doing to Review; tests it writes wait for what they expect to see, never for a length of time, so they pass on a slower or busier machine too), review-agent-work (review another agent's work without changing it, marking the card; a new test that sleeps and then checks fails the review; it checks the builder's record of the tests it ran rather than running them all again), merge-ready (get a branch ready to review and merge) and use-hive-api (scripts that call Hive's Agent API);
• for the Hive Assistant: coordinate-agents (plan work as cards, brief and start agents, follow them) and run-lanes (run a team's card loops: plan lanes, brief builders and reviewers, watch them to the end);
• for both: handover (wrap up for a later session), pick-up (carry on from a handover, checking it against the current state), split-work (plan how several agents can share a task) and workspace-note (record a decision or convention in the shared notes).

They're ordinary Hive skills: edit or delete them as you like. Hive keeps them up to date: when a new version of Hive improves one, a copy you haven't changed is updated when the workspace next opens, and a skill new in that version is added. If you edit, delete or replace one while Hive is updating it, your version stays and the update waits for the next time (if Hive was interrupted mid-update, anything of yours it had set aside is kept beside the skill as <name>-conflict-<date>). A copy you've edited is left as you wrote it: its page offers Revert to default (with Update available when Hive has a newer version than the one you edited). A skill you've deleted stays deleted: it's listed greyed out, with Restore. Revert and Restore send your copy to the Recycle Bin.

Who gets a skill. Each Hive skill's page shows who gets it: Project agents, Assistant or Agents + Assistant (in the list, the last two are marked). Your own Hive skills go to the project agents. If a skill's header can't be read, or its audience is misspelt, nobody gets it until you fix it: it's marked Not given, with the reason on hover. To write one for the Assistant, add audience: assistant (or all, for both) under metadata: in its SKILL.md's header:

yaml
---
name: weekly-report
description: Summarise the week's cards and agents for the user. Use when asked for a weekly report.
metadata:
  audience: assistant
---

When a session starts, Hive copies the Hive skills into the agent's own launch folder in the project's .hive and points Claude Code at it (Claude Code shows them as hive:<name>), so a running Claude Code agent keeps the version it started with. Codex only reads skills from the folder it works in (.agents/skills), so for Codex agents Hive copies them there as hive-<name> folders (and keeps them out of git); those copies aren't listed as local skills. Codex agents sharing a folder share those copies, so after one starts with a changed skill, the others use the new version too. Either way, a restarted session has the current skills.

MCP servers

MCP servers give agents extra tools. Each server is a JSON file in Workspace/.hive/mcp:

json
{
  "description": "GitHub issues and pull requests",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
}

Reference secrets with environment variables (${NAME}), never literal values — Hive warns when a definition looks like it contains one. Sessions get the environment Hive was started with, so after setting a variable (for example in Windows' Edit environment variables for your account), quit Hive completely, including from the tray, and open it again.

A server can be a program Hive starts (command, args, env, as above) or one reached over HTTP ("type": "http", "url" and optional "headers"), the same fields as in Claude Code's .mcp.json. To keep a server's own code with the workspace, put it in a folder next to its definition, for example .hive/mcp/notes/server.js, and refer to it as ${HIVE_MCP_DIR}, which Hive replaces with the path of the .hive/mcp folder: "args": ["${HIVE_MCP_DIR}/notes/server.js"]. Keep build output and node_modules out of git there.

A server you add or change is used by sessions started afterwards; restart a running session to give it the change.

Turning servers on where they're needed

A server in the workspace is available to every project, and runs only in the projects where it is on, so a big server you need in one project doesn't fill every other project's agents' context with its tools:

• In a project: its MCP tab lists every workspace server with a switch. Turn on the ones that project's agents need.
• In all projects: the switch beside a server in the MCP view (All projects in the server's own view) turns it on everywhere. A project can still turn it off in its MCP tab, and a project's own choice stays when you turn all projects on or off.

Each server in the MCP view says where it is on ("On in Amberlight", "On in all projects", "Not on in any project"). Turning a server on shows what it runs and asks first. Sessions of every provider use only the servers on in their project.

Servers you had turned on before this change stay on where they were: nothing changes until you change it.

If a project has its own .mcp.json (or, for Codex, .codex/config.toml servers), Hive tells you which of its servers aren't in the workspace and offers to copy them there; until then they stay disabled. Copy to workspace shows what each runs, then copies it and turns it on in that project straight away (other projects can turn it on in their MCP tab).

Giving a server to some agents only

By default every agent in a project gets all the servers on in its project. To keep a server's tools away from agents that don't need it (each server's tools take up room in an agent's context), open the agent's settings (right-click its tab → Agent Settings…) and under MCP servers choose Only these, then untick the servers it shouldn't have. For example, a release-testing agent can have a sandbox server that the builders don't. Choosing Only these starts with every server ticked, so nothing changes until you untick one; All of the project's puts it back.

• Hive's own hive server is always given, whatever you choose.
• An agent with Only these doesn't get a server enabled later: tick it in its settings. One with All gets it.
• A running agent takes the change when it restarts.
• Templates keep the choice, so an agent loaded from a template gets the same servers, where they're on.
• The agent's tooltip shows its choice, and once any agent has one, the project's MCP tab says under each server which agents get it.

Adding a server from a file

Add MCP Server from File (the file icon in the MCP view's header) adds a server someone gave you, as Add Skill from File does for skills:

• a .json definition, in the format above: it becomes .hive/mcp/<name>.json;
• a .zip of a server's folder: its code is unpacked to .hive/mcp/<name>/ and its definition becomes .hive/mcp/<name>.json. The definition is a file named hive-mcp.json (or hive-mcp.example.json) at the top of the zip, or inside one folder at its top. It refers to the server's code through ${HIVE_MCP_DIR}, for example "args": ["${HIVE_MCP_DIR}/notes/server.js"] for a zip of a notes folder holding hive-mcp.json and server.js. Added under another name, Hive changes those references to the new folder.

Before adding it, Hive shows the name it will have (the file's or the folder's, which you can change) and what it runs: the command and its arguments, or the address it connects to, and the names of its environment variables and headers (a ${NAME} reference shown as itself, never a value). A name already in use asks whether to Replace that server (the old one goes to the Recycle Bin) or choose another name. Turn on for says where it runs: the project selected in Hive (the default), All projects, or None yet (turn it on later in a project's MCP tab). Replacing a server turns the new one on only where you choose, even where the old one was on. Turning a server on later shows what it runs again and asks first. A server's view shows what it runs above its definition, and deleting a server added from a .zip also moves its folder to the Recycle Bin.

Nothing in the file runs while it's added. Hive refuses a zip with files that would land outside the server's folder (.., a drive or a leading /), names Windows can't hold, links, more than 5,000 files or more than 200 MB unpacked, and a definition without a command or url.

The built-in hive server

Every session also gets Hive's own MCP server, which lets agents list projects, read and write shared notes, write handovers, read and update the task board, and notify you. Try: "Write a handover for the next session using the hive tools." A new session is told about these tools and about the project's latest handover, so "read the handover" is enough to pick up where the last session stopped. See the Agent API reference.

Shared notes and handovers

The Shared Notes view edits the markdown files in .hive/shared. Use it for team conventions, instructions every agent should follow, and handovers — notes a session writes before it ends so the next session (or another project) can continue. Handovers go in shared/handovers, named by date and project (2026-09-29-api-auth-refactor.md), with the project on a **Project:** line at the top. When project names overlap, such as hive and hive-website, that line decides whose handover it is.

Several agents can update the same note without losing each other's changes. An agent rewriting a note says which version it read, and if someone changed the note meanwhile, its write is refused, so it reads the note again and merges its change in. Notes that many agents add to, such as status logs, get one appended entry each, dated and signed. Saving a note in the Shared Notes view that an agent changed since you opened it asks before overwriting it.

Memory

A project's Memory tab shows what each provider its agents use reads about it, grouped by provider:

• Claude Code: CLAUDE.md (project instructions read at the start of every session, usually committed), CLAUDE.local.md (your personal project instructions, not committed), the User CLAUDE.md (for all your projects) and Auto memory (facts Claude Code chose to remember about this project).
• Codex: AGENTS.md (project instructions) and the User AGENTS.md (for all your projects).

All of them can be edited here.

One set of instructions for both. When a project has Claude Code and Codex agents, each reads its own file. Share one AGENTS.md… at the top of the list makes AGENTS.md the shared file: CLAUDE.md gets an @AGENTS.md line, which makes Claude Code read it too. Anything else in CLAUDE.md stays and applies to Claude Code only. If there's no AGENTS.md yet, what's in CLAUDE.md moves into it, so nothing is lost.

Files

The Files tab is a file browser for the project folder.

• Create: the New File and New Folder buttons (or right-click a folder) add an entry inside the selected folder; type the name in place. A name like docs/notes.md creates the folders in between.
• Rename with F2, delete with Del. Deleted files go to the Recycle Bin, so they can be restored.
• Cut, copy and paste with Ctrl+X, Ctrl+C and Ctrl+V, or from the right-click menu, which also has Duplicate, Copy Path and Copy Relative Path. Pasting into another project always copies. A paste, a rename or a new file selects what it made once it's done; if you click another row before then (in a big folder or on a slow disk), your row stays selected, so the next key acts on it.
• Drag and drop: drag entries onto a folder to move them (hold Ctrl to copy). Drag files in from Explorer to copy them into the project. Drag files onto the Session tab to paste their paths into the running session.
• Open elsewhere: the buttons above the editor (and the right-click menu) open a file in its default app or reveal it in File Explorer.
• Find: the box at the top searches the whole project by name or path (git-ignored files are left out).
• Ctrl+click and Shift+click select several entries; the arrow keys move around the tree.

Names are coloured by git status like in VS Code (modified, new), folders containing changes get a dot, and git-ignored files and the .hive folder are dimmed. .git is hidden. The tree updates by itself when files change on disk.

Viewing and editing files

Select a file and it opens on the right, ready to edit, with syntax highlighting for code, SQL, XML, JSON, YAML and many more. Ctrl+S (or Save) saves it. Some file types also get a nicer view, and the buttons above the file switch between them:

When the file's pane is narrow (or the labels are long in your language), these buttons and Save show only their icons, with their names in tooltips, and the file's size and age are left out; narrower still, the buttons move to a second row under the file's name. Save is always in view.

Files with unsaved changes get a ● in the tree. The edits are kept while you look at other files or tabs, and follow a file you rename or move in the Files tab. Deleting a file with unsaved changes warns you first. When you quit, Hive lists the files with unsaved changes and saves them or discards them, as you choose; reloading the window or switching workspace offers to save them first. Unsaved changes are not kept if Hive crashes, so save often. If a file changes on disk while you have unsaved edits, for example because the agent edited it, Hive tells you and lets you Reload it or Overwrite with mine. A file without edits simply updates. Binary files and files over 5 MB aren't opened; use Open in Default App for those.

Attachments

You can attach any file to an agent's or the Assistant's prompt: paste a screenshot with Ctrl+V, or drag files from Explorer (or from the Files or Attachments tab) onto its terminal. Each file reaches the agent as its path in the prompt:

• A file from outside the agent's folder (its project or worktree; for the Assistant, the workspace) is copied into the session's attachments folder, .hive/attachments, and the copy's path is pasted. So is every image, wherever it comes from, so the Attachments tab keeps what you showed the agent.
• A file inside the agent's folder goes as it is, by its path, so the agent works on the real file. So does a folder.
• Files over 20 MB are asked about first: an agent may not manage a file that large (its CLI can refuse it, or reading it can fill much of its context).
• Hive never runs what you attach: it only copies it and pastes its path.

While you write the prompt, a chip for each attachment shows over the top right of the terminal, with the kind of file. The agent's CLI reads some kinds itself and the rest by path: the agent opens them with its own tools (a zip it might unpack, a PDF it might convert). Hover a chip for its path and which. × dismisses a chip (the path stays in the prompt); sending the prompt clears them.

The Attachments tab shows everything pasted or dropped into the project's sessions, grouped by session (newest first), with archived sessions at the bottom. Each session's heading says how many attachments it has and the days they were added ("71 attachments · Oct 9 – today"), and when a session spans days, a thin line marks where each day starts. Images show as thumbnails, other files by their type's icon (Markdown, JSON, PDF, zip, code, text) and name; every tile shows its size at the bottom left and its time at the bottom right. When there's more than one kind, the filters above (All, Images, PDFs, Text, Other) show just one kind. Click one to view it large and use ← / → to move between them: images, PDFs, Markdown, CSV tables and text are previewed as in the Files tab, and other files say there's no preview. From the viewer or the right-click menu you can Insert into Session, Copy Path, Reveal it, Copy Image (images), Open it in its program (images and PDFs only, never anything that could run), or Delete it (to the Recycle Bin). Click a session's name to read its transcript, or its bin to move all of its attachments to the Recycle Bin at once. A running session's attachments can't be deleted until it stops: Delete is greyed out (in the viewer too; hover it to see why). You can also drag one onto the Session tab.

This tab was called Images, and the folder .hive/images, before attachments could be any file. Hive moves the old folder's files into .hive/attachments the first time it needs them, and links to the old paths (in a transcript, or printed in a terminal) still open the moved files in Hive. An agent given an old path in an earlier conversation won't find it there any more: give it the file again.

Git view

A project's Git tab (Alt+6) has three sections: Changes, where it opens, History and Branches & remotes. The status bar shows the selected project's git in one item, such as main · origin · ↑2 ↓0: its branch, the remote its branch tracks, and how many commits are to push (↑) and to pull (↓). Click it for Branches & remotes. It says no upstream for a branch that tracks no remote branch yet, and detached at abc1234 or rebasing when git is in that state.

Everything here is yours: agents have no tool for any of it, and only the project folder changes here. Agents' worktrees are shown, read-only: their work comes into the project folder through Merge.

Changes

Changes lists files changed in the project's git working tree and shows each one as a side-by-side diff against the last commit — a quick way to review what the agent did.

Its picker chooses whose changes you see, in this order: Unused worktrees (worktrees no agent works in now, and each of them), the worktrees in use by agents, and the project folder last (where agents without a worktree, and you, make changes). A project with worktrees opens on Unused worktrees; one without opens on its folder. A sentence at the top of each page says what it shows. Listing unused worktrees asks git about each of them, which can take a few seconds: the first time, the page shows a spinner while Hive looks; after that, the last list shows at once while Hive checks it again. Refresh (↻) looks again.

Hive checks your projects' git status in the background (this tab, branch status, the Files tab's dimmed entries) without writing to the repository's index, so your own git add or git commit, or an agent's, never fails with "index.lock: File exists" because of it. Hive's own git actions, such as Merge, still update it as git does. If git is busy when the Files tab lists a folder, ignored entries keep their dimming and the folder is listed again a moment later.

History

History lists the project folder's last 20 commits, newest first, with their branches and tags, and the repository's tags below them. Create tag… tags the commit the folder has checked out: give it a name, and a message for an annotated tag, and choose a remote to push it to if you like.

Branches & remotes

• Branch: the branch the project folder is on (or its detached HEAD, and a merge or rebase git has in progress, which you finish in a terminal), the branch it tracks, and ↑ / ↓. These counts are as of the last fetch, whose time is shown: Hive never fetches by itself. Fetch fetches every remote. Pull fetches the branch it tracks and brings yours up to it when that needs no merge; when both have new commits, it says so and changes nothing (merge or rebase in a terminal, or ask an agent). Push pushes to the branch it tracks, or, for a branch that tracks none, to the remote you choose, which it then tracks. A push is never forced: when the remote has commits yours hasn't, it says to pull first. New branch… makes a branch at the folder's commit and switches to it.
• Branches: each local branch, with what it tracks and ↑ / ↓, its last commit, and Switch. Uncommitted changes come along when they don't clash with the other branch; when they do, git refuses and nothing changes. A branch checked out in an agent's worktree can't be switched to (a branch is in one folder at a time). Remote branches lists those you have no local branch for: Switch makes one that tracks it.
• Switching branch or pulling waits for your agents. It moves the ground under an agent working in the project folder and under a merge into its branch, so while an agent there is working, asking you something or waiting on its background tasks, or the project's merge slot is held or waited for, Switch, New branch…'s switch and Pull are greyed out, and hovering one says why ("B1 is working in the project folder: switch branches once it has finished"). An agent whose session is idle in the folder finds the new branch on its next turn: the confirmation says so.
• Remotes: each with its URL (a password or token in a URL shows as •••, in git's error messages too; to change such a URL, type it whole), Add remote… and ✎ to change a URL.
• Worktrees: the repository's other worktrees, whose agent works in each, and Changes to review it. Read-only.
• Commit identity: the name and email commits are made with, agents' too: this repository's own setting, your global one, and the one git uses. It warns when commits would fail (no name or email), and when a repository with a GitHub remote commits with a personal address, which anyone can read on GitHub; GitHub's no-reply address (…@users.noreply.github.com, in GitHub's email settings) keeps it private. Set for this repository… sets this repository's own (git config --local); leave both empty to use your global one.

A project inside another repository (say, a workspace you keep in git) shows that repository here, read-only: Hive changes only a project's own repository.

Fetch, pull and push use your git's own sign-in (Git Credential Manager may open its window); they never wait on a prompt in a terminal you can't see, and give up after five minutes.

Without git

A project that isn't a git repository keeps working in its project folder, without worktrees, merging or a Git view: its Git tab says so, with Initialise repository… to make it one. Without git itself, the tab says so, with the fix (see Git).

Initialise repository

Initialise repository… on the Git tab of a project without git makes it a repository in one click, ready for agents' worktrees. Its dialog:

• offers a starter .gitignore: none, Minimal (OS files and logs), or one for Node, Python, .NET or Godot projects, each with the minimal lines too. If the project already has a .gitignore, it is kept and none is offered;
• asks for your name and email when git has none (no global identity, counting files your git config includes), and saves them to this repository's config only, never your global one. Otherwise it says who the commits are made as. If your git config has conditional includes (includeIf), which may set an identity for the new repository, the fields are optional: what you enter is used only where they set none. If the new repository turns out to have no identity and you entered none, Hive makes the repository and stops before the first commit: the dialog stays open as Make the first commit, asking for what's missing. On GitHub, its no-reply address keeps your email private.

Initialise then runs git init on a branch called main, adds the project's .hive to the repository's .git/info/exclude before anything is staged (so it is never committed: see What Hive keeps in a project), writes the .gitignore you chose, and commits everything in the folder as Initial commit (an empty commit if there's nothing yet). The Git tab and the project's worktrees work at once: add an agent in a new worktree, or a remote under Branches & remotes to push it. There is no undo: if a step fails, the message says what was done and where it stopped (say, a .gitignore rule that brings .hive back stops it before anything is staged, with nothing committed).

• A project inside another repository (a workspace you keep in git) shows that repository's Branches & remotes read-only, with Initialise its own repository…: a repository inside another is usually a mistake, so the dialog names the repository around it and asks you to confirm.
• A repository with no commits yet (one that stopped short, or one made with git init by hand) says so on Branches & remotes, with Make first commit…: the same dialog, which keeps .hive out of git and makes the first commit on the branch it has.
• A folder another version control system keeps (Mercurial, Subversion, Jujutsu, Bazaar, Fossil), in it or in a folder above, isn't initialised, even a Jujutsu repository that has git beside it: the dialog says which.

Project settings

Each project can override the global defaults in its Settings tab, which has the same categories and search as Settings. In a narrow window (or with the side panels open), Settings and Project Settings make room: a setting's control moves under its description, the list of categories narrows, and when even that doesn't fit, the categories become a row across the top that scrolls sideways.

Number settings, here and in Settings, save when you press Enter or click away. An empty box inherits the global value here; in Settings it just puts the saved value back. A number out of range, or text that isn't a number, isn't saved: the range shows under the box. Settings that can be turned off have a Never (or No pause) checkbox beside the number; untick it to get your last number back.

Changes apply to new sessions. If you change something while a session is running, Hive shows Restart session, which restarts it with the new settings and continues the same conversation. The permission mode is the exception: it can be switched in a running session (below).

Permission modes

Bypass permissions only appears after you tick Settings → Claude Code → Enable the Bypass permissions option. Projects using it show a red warning. Use it only for disposable work.

Codex has its own presets:

When you switch a running Codex agent's preset, the badge says Switching to … until Codex confirms it; if Codex doesn't, the badge goes back and Hive tells you. If Codex is busy at that moment, Hive waits until it's free; if Codex kept /permissions in its input instead of running it, Hive presses Enter again (the same goes for Set up, below). If Codex stays busy for 30 seconds, asks you something meanwhile, or its session stops, Hive types nothing more and tells you the preset wasn't switched. Hive chooses the preset by the name Codex shows in its /permissions menu, whatever order a Codex version lists them in. If a Codex version doesn't show that name (renamed or dropped), Hive closes the menu without choosing another preset and says it couldn't find it: switch in the agent's terminal with /permissions instead, and update Hive when a new version is out.

In Approve for me, Codex's reviewer decides on risky actions itself: while it does, the agent stays Working… with a small shield beside its status (hover it to see what's being checked), and Hive doesn't ask for you. Hive tells you an agent needs you only when Codex actually puts a question or an approval to you, and once for each, even when a new session is slow to start on a busy computer.

Codex's Windows sandbox

On Windows, Codex runs commands in a sandbox, which it sets up once. Help → Agent Setup… → Codex → Set up opens Codex and, once it has finished loading and is idle (on a busy computer this can take a little while), brings up its setup, which offers two choices. With either, Codex agents in Ask for approval or Approve for me edit files in their own folder (the project, or the agent's worktree) and run commands there without asking, and ask before going online or writing anywhere else. Hive's own features (status, file locks, handovers, shared notes) work the same with both.

• Set up default sandbox (recommended): commands run under two local Windows accounts that Codex creates for them (CodexSandboxOffline and CodexSandboxOnline), with a firewall rule that keeps them offline unless you allow it. It isolates commands best. Windows asks for Administrator permission once.
• Use non-admin sandbox: needs no Administrator permission. Commands run under your own account with restricted rights. It protects your files and blocks internet access in most cases, but Codex warns it carries more risk if the agent is tricked by instructions hidden in a file or web page it reads (prompt injection).

If Set up can't find what it needs in Codex (a Codex version that names its /permissions presets differently), Hive shows a warning saying what it couldn't find and leaves Codex's terminal open: choose Ask for approval in its /permissions menu yourself to bring up the sandbox setup, or update Hive.

A stray .codex folder. Codex treats a .codex folder in a project as its own (for the project's Codex config). If an agent leaves scratch files or logs in one, Codex's sandbox can fail to protect it, and then every Codex agent's commands in that project fail with "setup refresh had errors". Hive warns when a .codex folder in a folder an agent works in holds something that isn't Codex's configuration (its config.toml, custom agents in agents, rules, and files they name): move those files out, and leave Codex's configuration where it is.

Once Codex has set the sandbox up, Hive closes it and Agent Setup says so. With the non-admin sandbox, Agent Setup shows Upgrade to switch to the default one later. Codex agents that are running keep their sandbox until they restart. Full access doesn't use the sandbox at all.

Full access is like Bypass: it only appears after you tick Settings → Codex → Enable the Full access option, and projects using it show a red warning. Codex's Plan mode is separate from the preset: choose Plan in the mode menu (or press Shift+Tab in the terminal), and the badge shows "· Plan". In Codex's sandbox the .git folder is read-only, so Codex asks before committing.

GitHub Copilot's modes:

Autopilot only appears after you tick Settings → GitHub Copilot → Enable the Autopilot option, and projects using it show a red warning. Allow all needs no opt-in: it is Copilot's mode for working with few interruptions, and its description says what it approves. In every mode, Copilot agents use Hive's own hive tools without asking.

Switching mode while an agent runs. The mode badge in each agent's footer shows the mode its session is really in. Click it, or press Ctrl+Alt+M, and choose another: Hive switches it straight away, without a restart, the same way pressing Shift+Tab in the terminal does (which Hive also notices). Don't ask and Bypass permissions can't be reached that way, so choosing them restarts the session in that mode and carries on the same conversation. For Codex, Hive picks the preset from Codex's /permissions menu. The switch applies to that session only; the settings decide what new sessions start in. When you change the setting while agents are running, Hive offers to Switch Now. This works with NO_COLOR set too (Claude Code then shows its footer without colours): Hive reads the mode as it appears on the terminal's screen and leaves your NO_COLOR preference as it is.

Agent API

Hive has a local API that agents, scripts and other apps use to talk to it: it listens on your computer only (127.0.0.1), and every call needs a token. Settings → Agent API turns it on or off, sets its port and shows its access token, which can do anything you can. Agents get tokens of their own automatically. See the Agent API reference.

Viewer tokens

An app that only shows what Hive is doing, such as Apiary (the office view), should get a viewer token rather than the access token: it can read everything in your workspaces (projects, agents, the board, lanes, merge slots, the Progress panel) and follow what happens as it happens, but it can't change anything. Every attempt to change something is refused.

To make one, open Settings → Agent API → Viewer tokens, type a name for the app (say Apiary) and click Make viewer token. The new token shows in its row: copy it and paste it into the app once. Revoke cuts that app off at once (it is refused from its next call, and stops receiving events), without touching anything else that uses the API. Hive keeps viewer tokens in its own folder (%APPDATA%\Hive\agent-api-viewers.json), never in a project.

The app finds a running Hive by itself: while the Agent API is on, Hive keeps its address (never a token) in %APPDATA%\Hive\agent-api-discovery.json, and removes it when the API is turned off or Hive quits.

The developer console

The developer console shows what each coding agent's CLI sends Hive (its hooks, status line, transcript records, the terminal signs Hive reacts to, its launch and exit) next to what Hive made of each: the status it set, the details it read. It also shows Hive's own work in the workspace: Agent API calls, the merge slot, watches waking agents and Progress runs. It's for power users and for developing Hive, so it is hidden until you turn on Settings → Advanced → Show developer features. Then open it from Help → Developer Console or with Ctrl+Alt+J.

• It opens in a window of its own, like a browser's developer tools, so you can put it on a second screen. Hive remembers its size and position, and opened on a smaller display it fits that display. Each Hive window has its own console, on that window's workspace. It closes with that window, or when the window opens another workspace or closes this one; open it again for the new workspace.
• Pick a source at the top: Hive or the Hive Assistant, or one of a project's agents. Hive starts capturing that source when you pick it and stops when you pick another or close the console. An agent you pick before it starts shows its launch too.
• Each row is one event: its time, its type, its name and a one-line summary. Click a row to see the event as it came in (Raw) beside What Hive made of it. Large payloads start folded: click a node to open it.
• Filter by event type (click a type to hide or show it) or by provider, and search (Ctrl+F) the events' names, summaries and payloads. Pause stops the list moving while you read (Hive goes on capturing, and the indicator counts what came); Resume fills it in. Clear empties the list, including anything that came while paused.
• What it shows is redacted: no prompt or reply text, commands, tokens or sign-in details. Hive keeps the newest 500 events of each source in memory only, and nothing once the console closes.
• To see the text while you debug, turn on Settings → Advanced → Developer console: show prompt, reply and command text (off by default). While it's on, the console shows the prompts, replies, commands and tools' arguments of what comes from then on, under an Unredacted banner (what came before stays redacted), and Record starts with its text box ticked. Tokens, API keys and sign-in details stay masked whatever it says, in the text too, wherever it is in an event: a key or token, an option such as --api-key or --password and its value, a password written out, cookies, and a sign-in or device code (ABCD-EFGH, or one in a sign-in link). Hive errs towards masking: after a credential's name (--token, token=, password:, Authorization:, a JSON key such as "password":) it hides everything to the end of that text, the options after it too, and now and then something that only looks like a code is masked too. It changes only what you see in the console: agents reading it with hive_console still get it redacted, and a recording with text is still never attached to Copy Diagnostics. Turn it off and the banner goes, and the console shows its events redacted again. Copy Diagnostics lists it among the Advanced settings you changed (by its name, hive.console.showText).
• Record (the red dot) writes the source's events from then on to a file, until you click Stop recording, pick another source or close the console. Recordings are redacted like the console; tick Include prompt and reply text in this recording to keep the text in that one recording (tokens and sign-ins are still masked; the box starts unticked each time, or ticked while the console shows text). Each file starts with the versions of Hive and of your coding agents' CLIs (and the versions this Hive was tested with). The bar at the bottom names the file; Show in folder opens Hive's console-recordings folder. If the file can't be written (a full disk, say), the bar says Recording failed and why, and keeps what was written.
• Help → Copy Diagnostics… offers to attach the newest recording to a bug report: tick it to add its newest events, with folders and names taken out as from the log. A recording that includes text is never attached.

Agents reading the developer console

Hive's developer console shows what each coding agent's CLI sends Hive (its hooks, status line, transcript records, the terminal signs Hive reacts to) next to what Hive made of each: the status it set, the details it read. Settings → Agent API → Let agents read the developer console gives agents and the Hive Assistant a read-only tool for it (hive_console), so they can see what their CLI does while they build and debug. It is off unless you turn it on, and running sessions get the tool when they next start.

• Each agent reads only its own sessions. The Assistant reads its workspace's agents, its own session, and Hive's own events there (Agent API calls, merge slots, watches waking agents, Progress runs).
• Hive captures only while you have the developer console open on an agent: an agent reading starts nothing, and is told when nothing is captured. Hive keeps the newest 500 events of each, in memory only, and nothing once the console stops watching it.
• What it captures is redacted: no prompt or reply text, commands, tokens or sign-in details. Names of tools and files, session ids and the numbers (usage, plan limits, costs) stay. That holds while your console shows text too: Developer console: show prompt, reply and command text changes only what you see.

Advanced settings

Settings → Advanced lists details Hive relies on that a coding agent's CLI update can break, and timeouts and limits for power users: the question each CLI asks before trusting a folder, the text that means it's ready, the messages that mean its sign-in was refused, the fields it sends plan limits in, what its screen shows while it works or once a turn is done, how its footer shows each permission mode (Claude Code's and Copilot's), the labels of Codex's /permissions menu, how Hive tells a safety classifier stopped an agent's response (Claude Code's note and question), the timeouts Hive gives its hooks and the hive tools, how long a stopped Copilot gets to exit by itself, the longest an agent's wait lasts, how many lanes the Progress panel shows, and whether the developer console shows prompt, reply and command text (see The developer console). Hive's defaults work with the CLI versions it was tested with; change one only when something stops working after a CLI update, or Hive's notes say to.

• The list is grouped (Hive, Claude Code, Codex, GitHub Copilot). Filter it, or tick Modified only; Settings' own search and Modified only find them too. Show developer features is first: it is in advanced.json too, as hive.showDeveloperFeatures.
• Each value shows its name (as advanced.json has it) and what it is for. Change it in its box: a changed one is marked, with its default beside it and Reset to put it back. A value Hive can't use (a regular expression that doesn't compile, a number out of range) is refused; the box says why.
• A value for a CLI also says when it no longer finds what that CLI was recorded showing ("It doesn't find what Claude Code 2.1.296 showed"): fine when the CLI changed, which is usually why you changed it.
• A value for a CLI (what Hive reads from it, or a timeout Hive gives it) records the CLI version it was made for, also when you edit advanced.json by hand. After that CLI updates, the value is flagged (Made for Claude Code 2.1.296; 2.1.300 is installed now): check it still works, then click Keep for 2.1.300, or Reset it if the new version no longer needs it.
• Some values a workspace can set for itself (This workspace), such as the lanes the Progress panel shows and Agents per project (see More than twelve agents); empty uses the list's.
• Settings → Advanced → Reset all settings puts these back to their defaults too (a workspace's own values stay).
• Hive keeps them in advanced.json in its profile folder (%APPDATA%\Hive): Open advanced.json opens it in your editor. Hive reads it again whenever it changes. A value in it that Hive can't use is listed as not valid, and Hive uses the default meanwhile; if the file itself can't be read (a missing comma), Hive keeps what it read before and says so, and the list can't change values until the file is fixed.
• Timeouts and hook settings apply to sessions started afterwards (restart a running agent); the patterns, and Copilot's exit grace, apply at once.
• Help → Copy Diagnostics lists which values you changed (their names, not what you changed them to).
• The Hive Assistant can explain them and, if you let it change settings, change them when you ask.

Updating Hive

Hive keeps itself up to date from its GitHub releases. By default it checks shortly after starting and every six hours, downloads a new version in the background, and installs it the next time you quit Hive — it never restarts on its own, so your agents are never interrupted.

• While a new version downloads, the status bar shows the progress; when it's ready it says Restart to update to X.Y.Z. Click it to see what's new.
• Restart and Update (in that dialog, the notification or the tray menu) closes Hive, installs the update and opens Hive again. If agents are working, Hive asks first, and you can let them finish. Stopped sessions can be resumed as usual.
• Skip This Version stops Hive offering that version; the next one is offered as normal.
• Hive is now Hive Desktop (0.5.0). The update renames the Start menu and desktop shortcuts and the entry in Installed apps to Hive Desktop. Nothing else moves: Hive stays installed in %LOCALAPPDATA%\Programs\Hive as Hive.exe, and your settings and conversations stay in %APPDATA%\Hive. A taskbar pin keeps working.
• Help → Check for Updates… checks straight away and tells you the result.
• Settings → Updates turns automatic checks and downloads off, chooses whether updates install automatically when Hive quits or only when you choose Restart and Update, and can include pre-release (beta) versions.

Updates are checked against their published checksum before they install.

Notifications

When an agent finishes (for one waiting on background tasks, once they have ended) or needs input, Hive plays a chime and tells you: with a banner in Hive while you're using it, and with a Windows notification when Hive is in the background. Click either to jump to the project. Configure them in Settings → Notifications; each project can override the chime.

Agents that finish together don't flood you: they chime once, and get one notice (3 agents finished in hive: Claude, Codex, Agent 3, or across projects hive (2), web (1)), shown a few seconds after the last of them. If you turn notifications off meanwhile, it isn't shown. An agent asking for your input is always told at once, on its own.

Banners in Hive

Windows notifications always appear at the bottom right of the screen, over the Assistant's panel where you type, so while any Hive window is focused Hive shows its own banner in that window instead:

• Where: at the top centre, or wherever Banner position puts it (any corner, or the middle of the top or bottom edge). Several stack, the newest nearest the edge.
• How long: a banner for an agent that finished goes after 6 seconds (it stays while the pointer is on it). One for an agent waiting for you stays until you click it, dismiss it (×), or answer the agent, wherever you answer it. Banners for an agent waiting for you stay until handled can make them close like the others.
• Click a banner to go to its project, in whichever window has it. From the keyboard, Tab to its text and press Enter (or Space) to go there, or Tab on to × to dismiss it; a banner stays while it has the focus, as it does under the pointer.
• Show banners for: All workspaces (the default: the window you're in shows notices from every Hive window, and clicking one brings up that window), This workspace, or This project (the project the window shows). A notice it leaves out shows nothing at all, but it still counts in its own window's Agents that need you list and taskbar button.
• While Hive is focused: Show in Hive (the default), Show nothing, or Windows notification (a Windows notification even while you use Hive, as before).

With no Hive window focused, you get Windows notifications as always. Plan usage warnings show in Hive as before, and as a Windows notification only when Hive is in the background. The chime, the taskbar count and the taskbar flash work the same either way.

Hive's own messages (warnings, what an action did) are kept in the Notifications panel: the bell at the bottom of the activity bar, or Ctrl+Alt+U. While some are unread the bell shows a dot and turns orange; opening the panel marks them read.

When a sign-in expires

All of Claude Code's agents share one sign-in, and so do all of Codex's. When it expires (or Codex's API key is refused), the CLI stops each agent's next turn. Hive then shows those agents as Needs sign-in, with a violet dot, in the agent row, the pane header, the Overview and the Assistant's lists. Hover one to see what the CLI said and how to sign in. You're told once for that CLI, however many of its agents stopped ("3 agents need you to sign in to Claude Code"), and Help → Agent Setup shows it signed out.

To sign in again:

• Claude Code: type /login in one of its agents' terminals, or use Help → Agent Setup → Claude Code → Sign in. The agent you signed in from carries on by itself.
• Codex: Help → Agent Setup → Codex → Sign in, or codex login in a terminal.

Hive notices the sign-in when an agent of that CLI works again, when Agent Setup's Sign in finishes, or at its next check (every minute while agents wait). The agents that are still stopped then read Stopped while signed out, and Resume All Agents in the project header counts them: it types a short "carry on" into each, so a card loop picks up where it stopped. Agents that already carried on aren't prompted again. A Codex agent you prompt again right after signing in shows working: Hive reads Codex's refusal from its session after the fact, and that late read can't turn it back to Needs sign-in.

When a safety classifier stops an agent

A CLI's safety classifier can stop an agent's response part way (Claude Code's model safeguards, Codex's cyber checks), carry on with another model, or ask you what to do. Hive spots it in the agent's session and tells you, so a false positive doesn't go unnoticed and an agent doesn't carry on with a weaker model without your knowing:

• A shield beside the agent's status in its pane says it happened. Hover it for when, on which model, how many times this session, and the names of the agent's last few tool calls before it (only their names: never what they did, nor what was stopped), so you can tell a false positive from an agent drifting into risky work. It also says what you can do: in Claude Code, /feedback reports a false positive, /model switches back, and /config sets whether it switches models by itself when a message is flagged.
• When the CLI asks you about it (Claude Code asks whether to switch to another model), the agent is Needs input, and the notification and its pane say why: a safety classifier stopped a response, with its last tool calls. Once you answer, the agent shows Idle after a safeguard stop: give it a nudge, and the Hive Assistant can prompt it again.
• When its model changes after one (Claude Code switching by itself, or Codex rerouting a request), Hive tells you, the shield is highlighted with the model it runs on now, and the agent is in Agents that need you until you look at its pane. Hive also notes it on the card the agent is working on, and the Assistant sees it in the agent's activity.
• Performance counts the stops per agent and model (below), including one you only saw as Claude Code's question (it doesn't always record those itself). Each stop counts once, however close together two are.

Hive reads this from Claude Code's and Codex's session records. GitHub Copilot's sessions don't record it, so for Copilot agents it isn't detected.

Agents that need you

With agents working in several projects, the status bar tells you who is waiting on you: 2 need you. Click it for the list, oldest first, with how long each has been waiting:

• Needs input: an agent waiting for your answer, such as a permission. It stays in the list until you answer it.
• Asks: an agent that asked you a question but carries on working meanwhile (Codex can). Its pane says has a question for you, and it stays in the list until you answer the question in its terminal.
• Needs sign-in: an agent its CLI stopped because the sign-in has expired. It stays in the list until you sign in again (below).
• After a safeguard stop: an agent whose model changed after its CLI's safety classifier stopped a response (see When a safety classifier stops an agent). It leaves the list once its pane is on screen.
• Finished: an agent that finished while you weren't looking at it: in another project, on another page of agents, on another tab, or while Hive was in the background. It leaves the list once its pane is on screen.

Click a row to go to that agent (the Assistant's opens its panel). The Projects icon in the activity bar shows the same number, and each project in the sidebar shows how many of its agents need you.

With Hive behind other windows, its taskbar button shows the count too: a red badge over the icon, and the number before the window's title (in Alt+Tab and when you hover the button). When an agent comes to ask you something while Hive is in the background, the button flashes until you switch to it. Turn either off in Settings → Notifications (turning the flash off also stops one that has started).

Below them, To review lists worktree agents that have stopped or finished with work not merged yet, with a summary such as 3 files, +120 −40 · 2 commits, and buttons for Changes and Merge…. They don't add to the count; one leaves the list once its work is merged or it starts working again. When nothing needs you but there is work to review, the status bar says 1 to review.

Sleep and shutdown

Agents work while you're away from the keyboard, so Hive keeps Windows from sleeping while any agent is working or waiting on background tasks, and lets it sleep again as soon as none is. The screen can still turn off and lock. The status bar says Keeping the PC awake: 2 agents working while it does. Settings → General → Keep the PC awake while agents work chooses When plugged in (the default: on a laptop's battery, it may sleep), Always, on battery too or Never.

When Windows shuts down, restarts or signs you out, Hive backs up the agents' transcripts first, in the moment Windows gives it, without holding up the shutdown. After the PC wakes from sleep, Hive reads each agent's state and plan usage again.

The system tray

Closing the (last) window keeps Hive running in the tray so sessions continue. The tray icon shows a red dot when an agent needs you. Its menu lists the agents that need you and those with work to review, from every window (click one to go to it), then your active projects, grouped by workspace when several windows are open. Quit from the tray menu or File → Exit.

Quitting

Quitting stops every running session, in every window. Nothing is lost: each conversation is kept and you can resume it next time. So Hive only asks first when an agent is in the middle of something (working, waiting for your answer, or waiting on background tasks it started). Otherwise it just closes and a notification tells you which sessions to resume.

When it asks, you see a table of the agents: each one's project, what it's doing, its card, and what stopping it would interrupt. You can choose:

• Quit now: stop everything straight away.
• Quit when agents finish: Hive hides and quits by itself once no agent is working or waiting on background tasks. Until then the tray menu has Quit Now and Cancel Pending Quit, and opening the window shows a banner with the same choices.
• Cancel: keep working.

If files have unsaved changes (in the Files tab, or a shared note, skill, instruction or memory file, or MCP server you're editing), Hive always asks, lists them at the top, and saves them (Save and quit) or discards them, as you choose. A file that changed on disk since you opened it isn't overwritten: Hive stays open so you can decide.

Tick Don't ask again to stop the question about sessions, or change it any time in Settings → General → Confirm before quitting (When an agent is working, Whenever sessions are running, or Never).

Keyboard shortcuts

In the terminal, Ctrl+C copies when text is selected (otherwise it interrupts the agent) and Ctrl+V pastes. Right-click copies or pastes text. GitHub Copilot selects text with the mouse itself: drag over what you want, then press Ctrl+C, and Copilot copies it ("copied to clipboard"). Hold Shift while you drag to make Hive's own selection instead, in any agent's pane. An agent's CLI can only put text on the clipboard just after you press a key or click in its pane, and can never read it. See Help → Keyboard Shortcuts for the full list.

Changing shortcuts. Settings → Keyboard Shortcuts lists every command: click a column's header to sort by it, or pick a Category or where it is Set to see only those. Click the pencil (or double-click a shortcut) and press the keys you want; press a second combination straight after for a chord such as Ctrl+K Ctrl+S. You can remove a shortcut, reset one, or reset them all. Hive warns when a shortcut is already used, and won't take keys you need for typing and editing (a key without Ctrl or Alt, Ctrl+C/V/X/A/Z/Y, Shift+Tab). A project can have its own shortcuts for project and session commands in Project Settings → Keyboard Shortcuts; they apply while that project is selected.

Open a file from the terminal. File paths an agent prints, like src/main/app.ts:42, are links: hover one to see it underlined, and Ctrl+click it to open the file in the project's Files tab with the cursor on that line. A worktree agent's paths open in its worktree, and a path into another project in the workspace opens in that project. Only files that exist are linked; a plain click still just selects text. Paths with spaces are linked too, most reliably when they're in quotes ("docs/my notes.md").

Open a card from the terminal. Card numbers an agent or the Assistant prints, like #12 in "#12 is back in Review", are links to the cards on the task board: hover one to see it underlined, with the card's title and column, and Ctrl+click it to open the card. Archived cards open too. Only numbers of cards on this workspace's board are linked, so an issue number from elsewhere, a colour like #fff or a # in a web address isn't.

Terminals out of sight. While an agent's terminal isn't shown (Settings is open, or you're on another tab, project or page), it keeps its size: the agent goes on drawing for the width you last saw. When you come back, the terminal fits its pane again once the window has settled, and the agent redraws only if the pane's size changed meanwhile. If you were following the output at the bottom, you're still at the bottom; if you had scrolled up to read, you're still on the same line.

Screenshots and files. With a screenshot on the clipboard (for example from Win+Shift+S), press Ctrl+V in a session: Hive saves the image in the session's .hive/attachments folder and pastes its path, and Claude Code attaches it as [Image #1]. You can also drag files from Explorer onto the terminal: any kind of file, its path pasted, copied into .hive/attachments first when it comes from outside the agent's folder or is an image. They're kept per session, so you can always see what was sent (see Attachments).

Troubleshooting

• "… was damaged and has been restored" — one of Hive's settings or record files couldn't be read (for example after a hand edit). Hive went back to its last good copy (.bak) and kept the damaged file next to it as .corrupt-<date>.
• "Claude Code is required" / "Codex is required" — install the CLI from Help → Agent Setup…, or set its path in the provider's settings page. Having the VS Code extension isn't enough; Hive needs the standalone CLI.
• "… is turned off" — turn the provider on in Settings → Providers.
• "Git isn't installed (or isn't on Hive's PATH)", or Git in red in the status bar — install Git for Windows 2.38 or later, or add the folder holding git.exe to your PATH, then Check again in Agent Setup: see Git.
• Agents show Needs sign-in — their CLI's sign-in has expired: see When a sign-in expires.
• Codex asks before every command — its Windows sandbox isn't set up: Help → Agent Setup… → Codex → Set up.
• An agent couldn't start — when its CLI quits before it has started (a setting it refuses, a broken install), the bar under its terminal turns red with Couldn't start: and what the CLI said, a hint where Hive recognises the problem, Retry and Agent Settings… (or Agent Setup…). Its tab and header turn red, the attention inbox lists it, and if its pane isn't on screen a notification says so. Fix the setting, then Retry; the terminal above keeps everything the CLI printed.
• Status dots don't change — status comes from the CLI's hooks. A Codex agent shows Ready once its prompt appears, and reports its session with your first message. A Claude Code agent shown Working… at an empty prompt is idle again a minute after its turn, when Claude Code says it is waiting for input; while Claude Code compacts by itself between turns, the agent shows Compacting the conversation… and then Ready. An agent whose turn ended without Hive hearing of it is finished again once its CLI's records or its screen show the end; failing that it shows Silent n min · state unknown, with Mark idle. Each hook Hive receives is logged in hooks.log in the logs folder. Restart the session; if it persists, check Help → Open Logs Folder.
• Agent API port in use — change the port in Settings → Agent API.
• Hive doesn't open, or says "Hive can't start" — Hive's windows run sandboxed. If the folder Hive is installed in has a permission entry for a Windows app package but none for ALL APPLICATION PACKAGES, Windows won't let them read it, and Hive can't open. The installer and updates add that entry, and Hive adds it at start when it can. When it can't (a folder you don't own), Hive shows the command to run, with Copy Command: run it in PowerShell (as an administrator if needed), then start Hive again. For the usual install folder, in PowerShell: icacls "$env:LOCALAPPDATA\Programs\Hive" /grant '*S-1-15-2-1:(OI)(CI)(RX)'.
• "Hive's window stopped and was reloaded" — the window's page crashed (memory, a graphics driver, a bug). Your agents run outside it, so they kept going: Hive reloaded the window, which reconnects to their terminals as View → Reload does. Unsaved edits in the Files tab are lost, and the note says how many. If it crashes again within a minute, Hive asks instead: Reload, Open Logs or Quit Hive. If the window stops responding, after a few seconds Hive offers Wait or Reload, and the question goes away if the window recovers.
• "This tab ran into a problem" — something in that view failed, for example on an unusual file. Your sessions keep running. Click Try Again or switch to another tab; if it keeps happening, Open Logs has the details for a bug report.
• Reporting a bug — Help → Copy Diagnostics… shows a summary for a bug report: Hive's and Windows' versions, your coding agents, counts of projects and agents, the settings that change how Hive behaves and the last 50 lines of its log. Your folders, workspace, project and agent names (also those of workspaces you opened before), card titles, what you asked agents to do, and anything that looks like a key or token are taken out, and the dialog shows exactly what will be copied. Click Copy and paste it into the report.
• Where is my data? — app settings in %APPDATA%\Hive (the folder kept the name Hive when the app became Hive Desktop), workspace data in Workspace/.hive, project data in Project/.hive.
• How many sessions can run? — as many as your machine can handle, across any number of projects. Each is a CLI process; Hive only draws the terminals you can see with the graphics card, so dozens of background sessions don't slow the window down.

Licence

Hive is open source under the MIT License. It includes open-source libraries (xterm.js, Monaco, React and others) under their own permissive licences, listed with their full texts in Third-Party Notices; both are in the Docs view and linked from Help → About Hive Desktop. Electron's and Chromium's licences are in the folder Hive is installed in (LICENSES.chromium.html). Hive Desktop is independently developed and isn't affiliated with, endorsed or sponsored by Anthropic, OpenAI or GitHub. Claude and Claude Code are products of Anthropic; Codex and ChatGPT of OpenAI; GitHub Copilot and the Copilot CLI of GitHub. Each CLI is installed separately under its maker's terms. The provider badges beside their names are Hive's own, not the providers' logos.