Settings reference
Every Settings card and control, what it does, its default, and the config key behind it.
Where: Top bar→Settings
Settings is the gear icon at the right end of the top bar. It opens one scrolling window of cards in two columns. Type in Search settings at the top to filter the rows in place; the count beside it says how many match, or nothing matches.
The header also shows your version number, Check for updates, and, when a new version is downloaded, Restart & update. See Install and update.
Settings are saved to ~/.griddler/config.json as you change them. The Key column below names each
control's entry in that file.
Left column
Appearance
| Control | What it does | Default | Key |
|---|---|---|---|
| Theme + 🎨 Picker | Colors the terminals and the whole window. See Themes and fonts. | Tokyo Night | theme |
| Terminal font | Font for new panes. | Default (Menlo / Consolas / DejaVu Sans Mono) | termFontFamily |
| Terminal font size | 8–24, for new panes. | 12 | termFontSize |
| Terminal renderer | Auto — GPU when available, GPU (WebGL), or DOM (compatibility). Applies to open panes. | Auto | termRenderer |
| Topbar mascot | Roaming — walks, dances and sits, Sitting — drag him where you want him, or Hidden. | Roaming | dancerMode |
| Desktop pet | Archimedes, or your character, on your desktop with your new mail. See Desktop pet. His right-click menu sets petLook (owl or me), petSize (pixels) and petMotion (full = Animate); dragging him sets petSpot. | Off | desktopPet |
| Hide the menu bar | Hides the menu bar; Alt shows it. Windows and Linux. | Off | hideMenuBar |
Today
| Control | What it does | Default | Key |
|---|---|---|---|
| Today panel | Adds the 📅 Today button to the top bar. Takes effect right away. | Off | dayPanel |
| Opens itself at | The hour Today opens on its own each day, or never. | 8 am | dayOpenAt |
| Calls in Meetings | recorded only, all calls, or off. | recorded only | dayCalls |
What the panel shows is on Today.
Panes & startup
| Control | What it does | Default | Key |
|---|---|---|---|
| Default agent | The agent the launcher opens on. | Claude | paneDefaults.agent |
| Claude | Default model and effort for new Claude Code panes. | default / default | paneDefaults.claude |
| Codex | Default model and effort for new Codex panes. Hidden when Codex is hidden. | default / default | paneDefaults.codex |
| Bypass permissions by default (dangerous) | New panes start without asking before each command or edit. Also sets the launcher's permission box for sessions on a Griddler Agent. See the launcher. | Off | paneDefaults.bypass |
| Relaunch every session at startup | On: every tab's panes start when Griddler opens. Off: background tabs wait as one-click placeholders. | Off | restoreAllTabs |
| Clipboard & keys | Modern or Classic. Classic sends a raw Ctrl+C, has no copy-on-select, and Shift+Enter submits. See Copy and paste. | Modern | termClipboard |
claude-mail
An older mail setup. If you're signed in, mail needs none of this; leave the card blank.
| Control | What it does | Default | Key |
|---|---|---|---|
| KB folder + Browse… | The folder of your knowledge archive checkout that holds the old mail tools. | Your workspace's archive | mailDir |
| Find it | Looks for the mail tools in the usual places. | ||
| Validate | Checks the folder and says Connected. or what's missing. | ||
| Notify me of new claude-mail | Shows once the old setup is found. Turns checking for mail through it on or off. |
Right column
Account
| Control | What it does | Default | Key |
|---|---|---|---|
| Status | Signed in as your email, or Signed out. | ||
| Admin | Open admin portal ↗. Admins only; see Admin portal. | ||
| Alias | Your name in the Tavern, up to 24 characters. Blank uses your handle. | Blank | alias |
| Set up… | Opens the Welcome page again. See First run. | ||
| Add a line of work… | Adds ready-made tabs for your work. See First run. | ||
| Sign in / Sign out | Your River Logic account. See Griddler Social. | ||
| Auto-refresh usage gauges | Keeps the usage strip current in the background. See Accounts and usage. | On | usageAutoRefresh |
Notifications
Desktop notifications, one checkbox per kind. Mute all turns every kind off; Turn all back on reverses it.
| Control | Key |
|---|---|
| New claude-mail | notifications.mail |
| Pane waiting on you | notifications.attention |
| New task in Triage | notifications.triage |
| Tagged on a work item | notifications.mention |
| New story chapter | notifications.stories |
| Standup draft ready | notifications.standup |
| Agent failed to start | notifications.launchFail |
| Co-op invite | notifications.coop |
| Watch-my-work request | notifications.peek |
| Today panel at its hour | notifications.day |
| …and show new triage work top-right | triageModal |
All are on by default. …and show new triage work top-right adds a corner toast to the triage notification.
Play & music
⚔ Play opens (combatMode) and ☠ Death tax — a lost first battle can claim a real bug (asks first)
(deathTax, on by default) are covered on Battles and raids.
YouTube Music controls (ytMusic) and the player you pick in the panel (musicProvider) are covered on
the game.
Posting voice
Voice, Learn mine, and your own voice text. Covered on Standup, posts and stories.
Support
| Control | What it does |
|---|---|
| What's going wrong? | A note that travels with the Trace. |
| Submit Griddler Trace | Runs the Doctor's checks, then sends a Trace and shows a Trace ID to quote to support. |
| Copy instead | Builds the same Trace and copies it to the clipboard. Nothing is sent. |
What a Trace holds is on Troubleshooting.
Keys with no control
No UI for these. Edit ~/.griddler/config.json to change them.
| Key | What it does | Default |
|---|---|---|
workspaceRoot | Your knowledge workspace folder. The Welcome page sets it. | Found automatically |
cloneRoot | The folder Create suggests making RLI.KW in. | Blank: C:\RLI.KW on Windows, ~/RLI.KW elsewhere |
standupMaxSessions | How many recent sessions one standup draft reads. | 40 |
protocolAsks | dock shows peek, co-op, and raid requests as cards in the mail dock; modal shows them as dialogs. | dock |
guildhall.delivery | How messages from the hall and other panes reach a pane: attention lights it, auto types them in, off stops them. | attention |
coopBudget | Pauses a co-op campaign after this many incoming messages. 0 never pauses. | 0 |
deathTaxEmail | The Azure DevOps email the game uses for commit boxes and the death tax, when it isn't your River Logic account. | Your River Logic account, then your global git email |
openaiKey | An OpenAI API key, so 🎨 Generate Character can paint while you're signed out. Griddler encrypts it the first time it reads it. | Blank |
agentReposDir | The folder a Griddler Agent on this machine's Docker Desktop mounts, so its sessions can work in your checkouts. | The folder most of your repositories share |
agentImage | Where a deployed agent's image comes from: pull downloads the published one, build builds it from a Griddler source checkout. | pull in an installed Griddler |
agents | Written by Griddler: each agent you deployed from here and the machine it runs on, so Re-sync and Remove don't ask again. Don't edit it. | Blank |
azureOpenAI | The same through Azure OpenAI: { "endpoint": …, "apiKey": …, "deployment": … }. Used before openaiKey. | Blank |
docsUrl | Where the top bar's open-book button and every ? and docs link go. | Blank: the team server's /docs, https://griddler.eode.app/docs |