Skip to content
Kelpie

Settings

Kelpie runs on its defaults, and all of this is optional. To change a setting, open the board’s experiments menu and choose Settings: every key below is there with its description and default, and a change applies as you make it. Behind that page is one JSON file, ~/.config/kelpie/config.json, which you can also edit by hand; terminalCommand and machines are set only there. 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
  "shortcutHints": false,             // a badge with its key on each control
  "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
  "showOtherSessions": false,         // show running sessions kelpie did not start
  "rowRepo": true,                    // a row shows its repo
  "rowTime": true,                    // ... how long ago it changed
  "rowDetail": true,                  // ... the status line under its title
  "rowPrs": true,                     // ... its open pull requests
  "rowTickets": true,                 // ... the ticket it mentions
  "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": ""                         // a theme file in this folder by name, or a path to one
}

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, or a value of the wrong type, is named on the board as a setup problem rather than silently replaced by the default.

  • 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.
  • showOtherSessions is off by default, so the board leaves off any running session kelpie did not start: one typed into a terminal, or one another tool runs. Kelpie’s own are its chats, features, reviews and their workers. Closed sessions and background jobs are always shown. Set it to true to see every session on the machine.
  • rowRepo, rowTime, rowDetail, rowPrs and rowTickets turn parts of a row off, for briefer rows. The title and anything asking for you always show.
  • machines is written by kelpie machine add: see Machines.
  • theme: see Themes.
  • --port and --cwd on the command line win over the file.