Configuration

Rabbitty reads a JSON file at ~/.config/rabbitty/settings.json (override the path with the RABBITTY_CONFIG environment variable). Every setting is optional; unknown keys are skipped, and any value with the wrong type falls back to its default — Rabbitty never refuses to start over a bad settings file. // comments are tolerated so you can annotate it.

Alongside it Rabbitty regenerates settings.schema.json on every launch, and the seeded file points at it with "$schema": "./settings.schema.json". Editors that understand JSON Schema (VS Code, Zed) then offer per-key completion, the allowed values for enum settings, hover docs, and a warning on a misspelled key. The same schema is published at /schema/settings.json.

{
  "$schema": "./settings.schema.json",
  "theme": "One Light",
  "font_family": "JetBrainsMono Nerd Font",
  "ui_font_family": "Inter",
  "font_size": 14
}

Settings

theme

string · default One Light

UI + terminal color theme. Any bundled theme, or the name of a Ghostty theme file. All chrome derives from the terminal palette.

Allowed: One Light, GitHub Light, Dark, Catppuccin Latte, Catppuccin Mocha

font_family

string · default Menlo

Terminal grid font. Any installed font; Nerd Font glyphs always fall back so shell/ls/powerline icons render.

ui_font_family

string · default .SystemUIFont

Interface font for the chrome (sidebar, command palette, quick switcher, tabs). The terminal grid uses font_family instead.

font_size

number · default 14

Terminal grid font size, in points. Adjustable at runtime with ⌘+ / ⌘− (which persists here).

max_columns

number · default 0

Widest the terminal grid may run, in columns. 0 (the default) always fills the pane. Set a count (e.g. 120) to cap an agent transcript's line length at a readable measure — full-width prose wraps at 180+ characters — with the grid centered between background gutters on a wider pane.

option_as_meta

boolean · default false

Treat the macOS Option key as Meta (Esc-prefix) instead of composing accented characters — useful for Emacs-style bindings.

Allowed: true, false

sound

boolean · default true

Play an in-app chime when an agent finishes or needs you while Rabbitty is the active app.

Allowed: true, false

status_source

string · default hook-then-scrape

How an agent's status is read: from its reported hooks, from on-screen scraping, or a combination.

Allowed: hook-then-scrape, scrape, hooks, scrape-then-hook

telemetry

boolean · default true

Send anonymous telemetry events (app launch, agent startups, state transitions) to improve Rabbitty. Respects user privacy; no sensitive code or PII is sent.

Allowed: true, false

preferred_ide

string · default Zed

Which editor the top-bar Open button and ⌘O open the current terminal's folder in. Auto-detected from your installed apps (Zed preferred); falls back to Finder if none is found. Set it to any detected editor's name to override.

worktree_dangerous

boolean · default false

Launch the agent carried into a new worktree with its permission-bypass flag (Claude Code's --dangerously-skip-permissions and each agent's equivalent), so it works unattended. Toggle from the command palette: worktree: toggle dangerous permissions.

Allowed: true, false

worktree_carry

string · default .env,.env.*,.envrc,!.env.example,!.env.sample

Fallback carry list for repos with no .worktreeinclude file: gitignored files copied into a new worktree so it can run immediately. Comma/newline globs, !pattern excludes (.gitignore syntax). A repo's committed .worktreeinclude overrides this entirely — write one from the command palette with worktree: configure carried files.

activity_log

boolean · default true

Dev builds only: record a complete local activity stream (actions, shell commands, focus, agent lifecycle) to the session dir for workflow mining. Never leaves your machine and never reaches product telemetry; compiled out of release builds. See docs/TELEMETRY.md.

Allowed: true, false

pull_requests

boolean · default true

Show the Pull Requests panel (⌘⇧R): your open PRs/MRs and ones awaiting your review, read from the gh and glab CLIs you've already configured. When off, the panel and its top-bar icon are hidden. Toggle from the command palette: Pull Requests: Enable / Disable.

Allowed: true, false

pr_providers

string · default github, gitlab

Which providers the Pull Requests panel reads from, comma-separated. Each is queried across every host its CLI is signed into (enterprise and cloud alike). Toggle a provider from the panel's chips or the command palette.

Allowed: github, gitlab

jira

boolean · default true

Show the Jira panel (⌘⇧J): your active-sprint issues and everything assigned to you, read from the jira CLI (ankitpokhrel/jira-cli) you've configured with jira init. When off, the panel and its top-bar icon are hidden. Each task has a button to hand it to the pane's agent to plan, and a copy-link button. Toggle from the command palette: Jira: Enable / Disable.

Allowed: true, false

phone_link

boolean · default false

Hold the phone link open while Rabbitty runs: your panes on your phone, with nothing to install on either end and no port opened on this Mac. Both ends dial out to rabbitty.app's relay and everything between them is sealed to a key the relay never sees. Pair a phone once by scanning a QR (⌘⇧P → 'Connect from your phone' → Pair a device); nothing that hasn't paired can read a byte. The card's button sets this for you.

Allowed: true, false

serve_port

number · default 8787

Port rab serve binds when you want the phone page on this Mac — for looking at it in a browser while you work on it. Bound to 127.0.0.1 only, and the app itself never opens it: the phone link needs no port at all. Named phone_page_port until the roads collapsed to one, when "the phone page" stopped meaning a thing you serve and started meaning the document your phone renders.

push_url

string · default ``

Webhook POSTed when an agent starts needing you, or finishes (an ntfy / Pushover URL). Off unless set. You don't poll a phone — you get pinged, then open the page. The body is deliberately thin: a count and the project name, never the worktree, the branch or what the agent asked. That text stays on your machine; the notification only tells you to go and read it.