# Settings reference

> Every page in Settings, and every setting in settings.json with its default and allowed values.

Source: https://hivemind.griiken.com/guide/settings/

This page lists the pages in **Settings** and every setting in the settings file. To change the
look step by step, see [Change how Hivemind looks](https://hivemind.griiken.com/guide/appearance/).

<AgentPrompt description="Paste this into your coding agent to read or change a Hivemind setting safely." page="settings">{`
Using the Hivemind settings reference, change the setting I describe.

1. Find its dotted path on the reference page, for example \`views.layers.groupBy\` or \`appearance.glass.blur\`, and its allowed values.
2. Show me the current value: \`hive config get <path>\`.
3. Set it: \`hive config set <path> '<JSON value>'\`. Text goes in double quotes inside single quotes (\`'"status"'\`). Numbers, \`true\` and \`false\` go as they are.
4. If it is refused, show me the message. Never edit the file by hand.

At the end, show the new value with \`hive config get <path>\` and the command that sets it back.
`}</AgentPrompt>

## Settings pages [#settings-pages]

Open Settings from the gear at the right end of the toolbar, or at the foot of the Layers panel.

| Group | Page | Holds |
|---|---|---|
| General | **Profile** | your name and colour, and this computer's ids |
| | **Appearance** | theme, wallpaper and effects ([Change how Hivemind looks](https://hivemind.griiken.com/guide/appearance/)) |
| | **Notifications** | alerts and sounds ([Know who is waiting](https://hivemind.griiken.com/guide/know-who-is-waiting/)) |
| | **Shortcuts** | keyboard shortcuts ([Keyboard shortcuts](https://hivemind.griiken.com/guide/keyboard-shortcuts/)) |
| Connect | **Connect** | your phone, other computers, other people ([Connect your devices](https://hivemind.griiken.com/guide/connect/)) |
| | **API access** | tokens for scripts and tools that drive agents ([Make an API token](https://hivemind.griiken.com/guide/api-tokens/)) |
| Plugins | **Plugins** | agents, views, widgets and tools: yours and the ones on HiveHub ([Plugins](https://hivemind.griiken.com/guide/plugins/)) |
| Advanced | **In a browser** | this app in a browser tab on this computer ([Open the app in a browser tab](https://hivemind.griiken.com/guide/browser-tab/)) |
| | **Servers** | the server your devices use to reach each other from other networks ([Set up your own network server](https://hivemind.griiken.com/guide/self-hosting/)) |
| | **About and updates** | the version, updates, and whether the app checks for them ([Update and roll back](https://hivemind.griiken.com/guide/update-and-roll-back/)) |

Each plugin also has its own page under **Plugins**, with **Settings**, **Read me** and **What it
can do**.

## The settings file [#the-settings-file]

Everything is one file you own. The app and the `hive` command both read and write it, and it is
checked each time. A value out of range is set to the nearest allowed one; an unknown value falls
back to its default. `hive config set` refuses a path that is not a setting, and lists the
settings there. It also refuses a `<view>` that is not a view's id, a `<kind>:<id>` that is not
a plugin's, and a key under either that is not one of its settings. A plugin's option ids are
checked only as ids there; `hive plugins set` checks them against the plugin's own settings.

A change writes only the settings it changes. Everything else in the file stays as it is, so a
newer version and this one can share the file:

- A key this version does not know stays, wherever it is: at the top of the file, in a section,
  or in a group such as `appearance.glass`.
- A value this version does not know, such as a newer accent's, mode's or wallpaper's id, reads
  as the default here and stays in the file until you set that setting here. A preset's id is
  kept as written: one this version does not know shows as Custom.
- Choosing a preset writes its colours, accent and mode, whatever they read as here. Importing a
  theme writes only the keys its file names.
- `v` is the file's format. A file from a newer version is read for the settings this version
  knows, and keeps its `v`; `hive config get` says so. A file without `v` is read as format 1.
  `v` is not a setting: the app keeps it.

| | Where |
|---|---|
| Every system | `~/.config/hivemind/settings.json` |
| With `XDG_CONFIG_HOME` set | `$XDG_CONFIG_HOME/hivemind/settings.json` |
| With `HIVE_SETTINGS` set | the file it names |

```bash
hive config path                              # where it is
hive config get appearance.glass.blur         # one value, as JSON
hive config set appearance.glass.blur 12      # a JSON value; the app reloads
hive config set views.layers.groupBy '"status"'
```

## appearance [#appearance]

| Path | Default | Allowed |
|---|---|---|
| `appearance.preset` | `signal` | `signal`, `clean`, `clean-light`, `ubuntu`, `dracula`, `nord`, `solarized-dark`, `one-dark`, `catppuccin-mocha`, `catppuccin-latte`, `tokyo-night`, `tokyo-night-day`, `gruvbox-dark`, `gruvbox-light`, `rose-pine`, `rose-pine-dawn`, `github-dark`, `github-light`, `solarized-light`, `monokai` (`hive theme list` shows them; set with `hive theme use`), or `theme` while a theme from a package is applied |
| `appearance.mode` | from the preset | `dark`, `light`. Set it with a preset: a light mode needs a light palette, such as `clean-light`'s |
| `appearance.accent` | from the preset | `graphite`, `indigo`, `volt`, `ember`, `ice`, `pulse`, `rose`, `emerald`, `amber`, `violet`. A colour of your own goes in `appearanceExtra.accent`, which wins over it |
| `appearance.radius` | `12` | 0 to 24 (px): **Corners** |
| `appearance.uiFont` | the system's own interface font | a CSS font list: **Interface font** (System, Geist, a theme's, or your own) |
| `appearance.monoFont` | `"JetBrains Mono", monospace` | a CSS font list: **Code font** |
| `appearance.glass.enabled` | `true` | **Glass panels** |
| `appearance.glass.opacity` | `0.72` | 0.30 to 0.95: **Panel opacity** |
| `appearance.glass.blur` | `18` | 8 to 24 (px): **Blur** |
| `appearance.glass.contentGlass` | `false` | **Frost tool content** |
| `appearance.glass.contentOpacity` | `0.25` | 0 to 0.9: **Content tint** |
| `appearance.glass.animate` | `true` | **Animate the background** |
| `appearance.wallpaper.kind` | `mono` | `none`, `aurora`, `ember`, `ice`, `mesh`, `sunset`, `forest`, `nebula`, `mono`, `shoal`, `koi`, `jellyfish`, `fireflies`, `image`, `video`, or a package's [live wallpaper](https://hivemind.griiken.com/guide/live-wallpapers/) by its id, `@owner/package/<folder>`. One that is not installed, or whose package is off, draws as the default does |
| `appearance.wallpaper.brightness` | `0.85` | 0.4 to 1.1: **Media brightness** |
| `appearance.wallpaper.colour` | `false` | **Colour**: a live scene (`shoal`, `koi`, `jellyfish`, `fireflies`, or a package's live wallpaper that has colours of its own) in its own colours, not the theme's |
| `appearance.pluginSurfaces` | `theme` | `theme`, `opaque`: **Tools in scene views** |
| `appearance.palette`, `appearance.terminal` | from the preset | CSS colours; set them with **Terminal colours** or a theme file |
| `appearance.overlayMedia` | none | set with **Add overlay** |

A view you installed is told your fonts. It draws a theme's fonts, the fonts it ships and the
fonts your computer has ([how](https://hivemind.griiken.com/guide/plugin-settings/#the-apps-colours)).

## appearanceExtra [#appearanceextra]

The parts of the look an older Hivemind does not know. They sit in their own key, so a write by an
older app or `hive` keeps them, and `appearance.accent` keeps a built-in id that older builds read.
Each part is set whole.

| Path | Default | Allowed |
|---|---|---|
| `appearanceExtra.accent` | none | `{ "brand", "accent", "working"? }` colours (`#rrggbb`, `rgb()` or `oklch()`): your own **Accent**. Picking a built-in accent or a preset, or `hive config set appearance.accent`, removes it |
| `appearanceExtra.fontFaces` | none | `{ "ui"?, "mono"? }`, the font files a theme brought. Set by applying a theme; one is read only while `appearance.uiFont` or `appearance.monoFont` names its family, so picking another font lets its file go |
| `appearanceExtra.theme` | none | the theme applied, its version, and your look before it. Set by **Apply** and `hive theme use`, cleared by **Revert to previous look**, `hive theme revert` or a preset |

```bash
hive config set appearanceExtra.accent '{"brand":"#c08552","accent":"#d9a273"}'
```

## views [#views]

| Path | Default | Allowed |
|---|---|---|
| `views.defaultView` | `canvas` | the id of a view you have |
| `views.layers.status` | `all` | `all`, `needs-you`, `unread`, `working`, `idle`, `exited` |
| `views.layers.activity` | `all` | `all`, `hour`, `today`, `week` |
| `views.layers.groupBy` | `group` | `machine`, `group`, `date`, `status`, `agent`, `none` |
| `views.layers.sortBy` | `canvas` | `canvas`, `activity`, `name` |
| `views.layers.recentsBy` | `agent` | `agent`, `project`, `date`, `none` |
| `views.layers.machines` | every one | `local`, or a machine's id |
| `views.layers.lines` | `all` | `all`, `needs-you`, `off`: which rows show a second line ([Know who is waiting](https://hivemind.griiken.com/guide/know-who-is-waiting/#read-what-each-row-says)) |
| `views.chrome.<view>.island` | the view's own | `top`, `bottom`, `hidden`, `off`: where the toolbar sits in that view |
| `views.toolbars.<view>` | the defaults | which toolbar buttons, in which order |

The `views.layers` values are what the Layers panel's **View** menu sets.

## agents [#agents]

| Path | Default | Means |
|---|---|---|
| `agents.defaultAgent` | the first installed | the agent `2` and **New agent** start |
| `agents.autoInstall` | `true` | add an agent from HiveHub when its program is found on this computer |
| `agents.declined` | none | agents you removed; never added by themselves again |
| `agents.whenAgentStartsAgent` | `stay` | when an agent or a program starts an agent: `stay` where you are, the new tile unread in Layers, or `go` to it. One you start is always shown |

## plugins [#plugins]

| Path | Means |
|---|---|
| `plugins.state.<kind>:<id>` | whether that plugin is on, and the values of its settings. Change them on its page, or with `hive plugins enable`, `disable`, `set` and `reset`. |

## notifications [#notifications]

Change them on **Settings → Notifications** ([Know who is waiting](https://hivemind.griiken.com/guide/know-who-is-waiting/)), or with
`hive notifications set` or `hive config set`. Both refuse a path not listed here and a value not of
its kind. Only the person changes them: an agent is refused.

| Path | Default | Means |
|---|---|---|
| `notifications.enabled` | `true` | every toast, popup and sound |
| `notifications.kinds.needs`, `.done`, `.error` | `true` | which changes notify you: needs you, finished, failed |
| `notifications.inApp` | `true` | toasts in the window, and what a screen reader says |
| `notifications.osPopups` | `true` | your system's popups, while no Hivemind window has the focus |
| `notifications.popupText` | `false` | a popup says what the agent waits on, or its terminal's last line |
| `notifications.sound` | `false` | play a sound |
| `notifications.sounds.needs` | `true` | a sound when an agent needs you |
| `notifications.sounds.done`, `.error` | `false` | a sound when an agent finishes, or fails |
| `notifications.volume` | `0.6` | 0 to 1 |
| `notifications.dnd.enabled` | `false` | Do Not Disturb: mutes finished and failed (toasts, popups, sounds, the spoken line), never needs you |
| `notifications.dnd.start`, `.end` | `22:00`, `07:00` | its times, as `HH:MM` in your local time |

## profile, network, browserApp, quit [#profile-network-browserapp-quit]

| Path | Default | Means |
|---|---|---|
| `profile.name` | none | the name others see beside your cursor, up to 64 characters |
| `profile.color` | none | your colour, as `#rrggbb` |
| `network.updateCheck` | `true` | ask now and then whether a newer release or newer agents are out |
| `browserApp.enabled` | `false` | serve the app to a browser tab on this computer |
| `browserApp.port` | `4483` | 1024 to 65535 |
| `browserApp.names` | none | other host names a browser may use, such as your Tailscale name |
| `quit.whenRunning` | `ask` | what quitting does while terminals or agents run here: `ask`, `keep-running` or `stop-everything` |

<LastValidated />