Skip to content
Kelpie

Settings

Kelpie runs on its defaults, and all of this is optional. There is no settings screen: kelpie reads one JSON file, ~/.config/kelpie/config.json, and every key in it is optional. Write only the ones you want to change and the rest keep the values below. kelpie config prints the file it reads and the values in effect, creating it with defaults if it is missing.

~/.config/kelpie/config.json
{
  "port": 4321,                       // the board's port
  "ticketPrefixes": ["ENG", "ACL"],   // matched as <PREFIX>-<digits> and linked
  "ticketBaseUrl": "https://linear.app/your-workspace/issue/", // empty by default: no ticket links
  "terminal": "auto",                 // "auto" | "iterm" | "terminal" | "none"
  "terminalCommand": "",              // anything else: {cwd} and {command} are substituted
  "appWindow": true,                  // open as its app or its own window, not a tab. macOS
  "sound": true,                      // chime when a row changes
  "breaks": true,                     // count how long you have been at it
  "collapseClosed": true,             // Closed starts folded away
  "hideClosedAfterDays": 7,           // hides stale Closed rows, never Needs you
  "recentClosedSessions": 20,         // exited sessions kept resumable in Closed
  "quietAfterSeconds": 180,           // silence after which a row reads as quiet
  "chatPermissionMode": "auto",       // permission mode a chat session starts in
  "worktreeDir": "~/parallel",        // where features cut their worktrees
  "proxyPort": 443,                   // https port for feature domains
  "updateCheck": true,                // ask whether a newer kelpie is out
  "machines": [],                     // other computers' boards, over ssh
  "theme": ""                         // "catppuccin", "nord", or a path to your own
}

JSON allows no comments, so strip them if you paste this.

An open board applies a change to the file within a second and without a reload; port and machines wait for a restart. A file kelpie cannot parse is named on the board as a setup problem rather than silently replaced by the defaults.

  • terminal: "none" is the kill switch: no new-window button, and no scripting or activating your apps at all.
  • terminalCommand and machines hold commands kelpie runs, so treat the file like a script.
  • updateCheck is the only request kelpie makes to anything of ours: see What kelpie sends.
  • machines is written by kelpie machine add: see Machines.
  • theme: see Themes.
  • --port and --cwd on the command line win over the file.