Hive configuration reference

Every config.toml option with its type and default: general, terminal, daemon, notifications, integrations, worktrees, theme, keys, agents and layouts.

Hive reads ~/.config/hive/config.toml (or the file named by $HIVE_CONFIG) when hive starts. Every key is optional and a missing file means all defaults. Unknown keys are an error, so typos don't pass silently. After editing, run hive doctor to validate the file, then restart hive; running agents are not affected.

Integrations are the exception: Ctrl+Space I switches them on and off at once and writes enabled for you, keeping your comments. examples/config.toml is a complete, commented file to start from.

`[general]`

Defaults for new sessions and the look of the interface.

Key	Type	Default	Meaning
`default_agent`	string	`"claude"`	Agent hive new starts when you don't name one.
`theme`	string	`"hive-dark"`	hive-dark, hive-light, ansi (your terminal's 16 colours) or mono (no colour).

`[branding]`

Hive's own chrome.

Key	Type	Default	Meaning
`show_header`	bool	`true`	Show the tab bar row above the panes.
`show_tagline`	bool	`true`	Show the tagline on the start screen.

`[terminal]`

How agents' terminals behave.

Key	Type	Default	Meaning
`scrollback_lines`	integer	`10000`	Lines of history the daemon keeps per session.
`mouse_support`	bool	`true`	Clickable sidebar and tabs, wheel scrolling, and mouse input for agents that use it. Hold Shift to select text natively.

`[daemon]`

The background daemon, hived.

Key	Type	Default	Meaning
`auto_start`	bool	`true`	hive starts the daemon when it isn't running. Off: run hive daemon start yourself.
`kill_timeout_secs`	integer	`3`	Seconds between asking a session to quit and forcing it.

`[notifications]`

How Hive gets your attention when an agent you aren't viewing needs input or finishes.

Key	Type	Default	Meaning
`bell`	bool	`true`	Ring the terminal bell.

`[integrations.*]`

Optional tools, all off by default. Turn them on with Ctrl+Space I, which saves enabled here, or edit the file. Details and examples are on the integrations page. See integrations.

Key	Type	Default	Meaning
`integrations.obsidian.enabled`	bool	`false`	Ctrl+Space N opens the workspace's Obsidian vault.
`integrations.obsidian.agent`	string	`""`	Agent that opens the vault; empty uses $VISUAL, then $EDITOR, then vi.
`integrations.obsidian.open_in`	"tab" \| "split"	`"tab"`	Where the notes pane opens.
`integrations.obsidian.journal`	bool	`false`	Append a line to today's daily note when an agent finishes.
`integrations.obsidian.journal_dir`	string	`""`	Folder of daily notes inside the vault; empty is the vault root.
`integrations.review.enabled`	bool	`false`	Ctrl+Space G reviews changes in the session's directory.
`integrations.review.command`	string array	`[]`	Program to run; empty picks lazygit, else tig status, else git diff.
`integrations.review.open_in`	"tab" \| "split"	`"split"`	Where it opens.
`integrations.github.enabled`	bool	`false`	Ctrl+Space H shows pull request checks for the branch.
`integrations.github.command`	string array	`[]`	Empty runs ["gh", "pr", "checks", "--watch"].
`integrations.github.open_in`	"tab" \| "split"	`"split"`	Where it opens.
`integrations.tasks.enabled`	bool	`false`	Ctrl+Space T picks a just, package.json, make or cargo task to run.
`integrations.tasks.open_in`	"tab" \| "split"	`"split"`	Where the task runs.
`integrations.desktop_notify.enabled`	bool	`false`	A desktop notification when an agent you aren't viewing needs input or finishes.
`integrations.desktop_notify.command`	string array	`["notify-send", "--app-name=Hive"]`	Program to run; the title and body are appended as two arguments.
`integrations.git_status.enabled`	bool	`false`	Changed files and commits ahead/behind under each repository space.
`integrations.usage.enabled`	bool	`false`	Ctrl+Space U shows token usage and cost.
`integrations.usage.command`	string array	`[]`	Empty runs ["ccusage", "blocks", "--live"].
`integrations.usage.open_in`	"tab" \| "split"	`"split"`	Where it opens.

`[worktrees]`

Git worktrees Hive creates for agents.

Key	Type	Default	Meaning
`dir`	path	`$XDG_DATA_HOME/hive/worktrees`	Where new worktrees go (on most Linux systems ~/.local/share/hive/worktrees).

`[theme]`

Colour depth, glyphs and colour overrides on top of [general] theme.

Key	Type	Default	Meaning
`colors`	string	`"auto"`	auto, truecolor, 256, 16 or none. Auto reads NO_COLOR, COLORTERM and TERM.
`glyphs`	string	`"auto"`	auto, unicode or ascii. Auto picks ascii on the Linux console or without a UTF-8 locale.
`accent`	#rrggbb	`theme's`	Accent colour. Also: accent_dim, surface, text, muted, success, warning, error.

`[keys]`

The leader key and bindings. Command names are on the keys page. See keys.

Key	Type	Default	Meaning
`leader`	key	`"ctrl+space"`	Pressed before every Hive command. Needs Ctrl, Alt or an F-key. Pressing it twice sends it to the agent.
`jump_modifier`	string	`"alt"`	Modifier for 1-9 to jump to agents without the leader: "alt", "ctrl+alt", or "" for off.
`bind`	table	`defaults`	command = key or [keys], pressed after the leader. Replaces that command's defaults; [] unbinds it.
`global`	table	`Alt+arrows`	command = key, active without the leader even while typing. Needs Ctrl or Alt; [] frees a key for the agent.

`[agents.<name>]`

Add an agent or override a built-in. Commands run directly, never through a shell.

Key	Type	Default	Meaning
`agents.<name>.command`	string	`required`	Program to run, by name on PATH or as an absolute path.
`agents.<name>.args`	string array	`[]`	Arguments, passed as they are.
`agents.<name>.env`	table	`{}`	Extra environment variables. Never written to disk by Hive.

`[layouts.<name>]`

Panes opened together in a new tab with Ctrl+Space L. The first pane fills the tab; each next one splits the one before it.

Key	Type	Default	Meaning
`layouts.<name>.spaces`	string array	`[]`	Spaces where Ctrl+Space L opens this layout without asking.
`layouts.<name>.panes`	array of tables	`required`	The panes, in order. Each takes the keys below.
`panes[].agent`	string	`"shell"`	Agent to start.
`panes[].run`	string array	`[]`	A command to run instead of an agent, e.g. ["npm", "run", "dev"].
`panes[].split`	"right" \| "down"	`"right"`	Where it goes relative to the previous pane.
`panes[].label`	string	`""`	Session label; empty uses the agent's or command's name.

Examples

Your own agent, and a variant of a built-in

[agents.aider]
command = "aider"
args = ["--dark-mode"]
env = { AIDER_AUTO_COMMITS = "false" }

[agents.claude-opus]       # shows up as its own agent
command = "claude"
args = ["--model", "opus"]

Agents start with the environment of the hive command that launched them, plus env. Hive recognises a custom agent's status when its command is a known agent (here, Claude Code); otherwise see report-agent.

A layout for a web project

[layouts.web]
spaces = ["web"]           # opens without asking in the "web" space
panes = [
  { agent = "claude" },
  { run = ["npm", "run", "dev"], split = "right", label = "server" },
  { split = "down" },      # a terminal below the server
]

A layout with no panes or an unknown agent stops hive from starting, with the reason.

Light terminal, no mouse, quiet

[general]
theme = "hive-light"

[terminal]
mouse_support = false

[notifications]
bell = false