config.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/shkm/shellflow/main/schemas/config.schema.json",
  "title": "Shellflow Configuration",
  "description": "Configuration file for Shellflow - a Tauri desktop app for orchestrating git worktrees",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "description": "JSON Schema reference for editor validation"
    },
    "main": {
      "type": "object",
      "description": "Configuration for the main terminal pane",
      "properties": {
        "command": {
          "type": ["string", "null"],
          "description": "Command to run in the main terminal pane. If null or omitted, spawns your shell.",
          "default": null
        },
        "fontFamily": {
          "type": "string",
          "description": "Font family for the main terminal",
          "default": "Menlo, Monaco, 'Courier New', monospace"
        },
        "fontSize": {
          "type": "integer",
          "description": "Font size in points for the main terminal",
          "minimum": 6,
          "maximum": 72,
          "default": 13
        },
        "fontLigatures": {
          "type": "boolean",
          "description": "Enable font ligatures (disables WebGL rendering)",
          "default": false
        },
        "padding": {
          "type": "integer",
          "description": "Padding around the terminal content in pixels",
          "minimum": 0,
          "maximum": 64,
          "default": 8
        },
        "unfocusedOpacity": {
          "type": "number",
          "description": "Opacity (0.0 to 1.0) applied to the main area when drawer is focused. Defaults to panes.unfocusedOpacity if not specified.",
          "minimum": 0,
          "maximum": 1
        }
      },
      "additionalProperties": false
    },
    "drawer": {
      "type": "object",
      "description": "Configuration for drawer terminals. All properties are optional and inherit from 'main' if not specified.",
      "properties": {
        "fontFamily": {
          "type": "string",
          "description": "Font family for drawer terminals. Inherits from main if not specified."
        },
        "fontSize": {
          "type": "integer",
          "description": "Font size in points for drawer terminals. Inherits from main if not specified.",
          "minimum": 6,
          "maximum": 72
        },
        "fontLigatures": {
          "type": "boolean",
          "description": "Enable font ligatures (disables WebGL rendering). Inherits from main if not specified."
        },
        "padding": {
          "type": "integer",
          "description": "Padding around the terminal content in pixels. Inherits from main if not specified.",
          "minimum": 0,
          "maximum": 64
        },
        "unfocusedOpacity": {
          "type": "number",
          "description": "Opacity (0.0 to 1.0) applied to the drawer when open but not focused. Defaults to panes.unfocusedOpacity if not specified.",
          "minimum": 0,
          "maximum": 1
        }
      },
      "additionalProperties": false
    },
    "apps": {
      "type": "object",
      "description": "External applications to open directories with. If omitted, uses platform defaults.",
      "properties": {
        "terminal": {
          "$ref": "#/$defs/appConfig",
          "description": "Terminal app. Default: Terminal.app (macOS), xdg-terminal-exec (Linux), Windows Terminal (Windows)."
        },
        "editor": {
          "$ref": "#/$defs/appConfig",
          "description": "Editor app. Default: $VISUAL or $EDITOR, opened in a terminal window."
        },
        "fileManager": {
          "$ref": "#/$defs/appConfig",
          "description": "File manager app. Default: Finder (macOS), xdg-open (Linux), explorer (Windows)."
        }
      },
      "additionalProperties": false
    },
    "worktree": {
      "type": "object",
      "description": "Configuration for git worktree management",
      "properties": {
        "directory": {
          "type": "string",
          "description": "Directory where worktrees are created. Supports placeholder: {{ repo_directory }}",
          "default": "{{ repo_directory }}/.worktrees"
        },
        "baseBranch": {
          "description": "Branch to create new worktrees from",
          "default": "auto",
          "oneOf": [
            {
              "type": "string",
              "enum": ["auto", "current"],
              "description": "'auto' uses default branch (main/master), 'current' uses checked out branch"
            },
            {
              "type": "object",
              "description": "Use a specific named branch",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Branch name to create worktrees from"
                }
              },
              "required": ["name"],
              "additionalProperties": false
            }
          ]
        },
        "copy": {
          "type": "object",
          "description": "Configuration for copying files to new worktrees",
          "properties": {
            "gitIgnored": {
              "type": "boolean",
              "description": "Copy gitignored files from the project to new worktrees",
              "default": false
            },
            "except": {
              "type": "array",
              "description": "Glob patterns to exclude from copying",
              "items": {
                "type": "string"
              },
              "default": [".claude", ".worktrees"]
            }
          },
          "additionalProperties": false
        },
        "focusNewBranchNames": {
          "type": "boolean",
          "description": "Focus the branch name input when creating a new worktree, allowing immediate editing",
          "default": false
        },
        "merge": {
          "type": "object",
          "description": "Configuration for merge operations",
          "properties": {
            "strategy": {
              "type": "string",
              "enum": ["merge", "rebase"],
              "description": "Merge strategy to use",
              "default": "merge"
            },
            "deleteWorktree": {
              "type": "boolean",
              "description": "Delete the worktree after successful merge",
              "default": true
            },
            "deleteLocalBranch": {
              "type": "boolean",
              "description": "Delete the local branch after successful merge",
              "default": false
            },
            "deleteRemoteBranch": {
              "type": "boolean",
              "description": "Delete the remote branch after successful merge",
              "default": false
            }
          },
          "additionalProperties": false
        },
        "delete": {
          "type": "object",
          "description": "Configuration for worktree deletion",
          "properties": {
            "deleteBranchWithWorktree": {
              "type": "boolean",
              "description": "Delete the local branch when deleting a worktree",
              "default": true
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "navigation": {
      "type": "object",
      "description": "Reserved for future navigation settings",
      "properties": {},
      "additionalProperties": false
    },
    "indicators": {
      "type": "object",
      "description": "Configuration for activity indicators",
      "properties": {
        "activityTimeout": {
          "type": "integer",
          "description": "Time in ms after last activity before progress indicator turns off",
          "minimum": 0,
          "default": 250
        },
        "showIdleCheck": {
          "type": "boolean",
          "description": "Show checkmark when activity stops (idle state)",
          "default": true
        }
      },
      "additionalProperties": false
    },
    "scratch": {
      "type": "object",
      "description": "Configuration for scratch terminals (general-purpose terminals not tied to any project)",
      "properties": {
        "startOnLaunch": {
          "type": "boolean",
          "description": "Create a scratch terminal when the app launches",
          "default": true
        }
      },
      "additionalProperties": false
    },
    "panes": {
      "type": "object",
      "description": "Configuration for split panes",
      "properties": {
        "unfocusedOpacity": {
          "type": "number",
          "description": "Opacity (0.0 to 1.0) applied to unfocused split panes",
          "minimum": 0,
          "maximum": 1,
          "default": 0.7
        }
      },
      "additionalProperties": false
    },
    "actions": {
      "type": "object",
      "description": "Configuration for AI-assisted actions",
      "properties": {
        "command": {
          "type": "string",
          "description": "Command to run for AI-assisted actions (e.g., 'claude')",
          "default": "claude"
        },
        "mergeWorktreeWithConflicts": {
          "type": "string",
          "description": "Prompt template for resolving merge conflicts. Variables: {{ worktree_dir }}, {{ worktree_name }}, {{ branch }}, {{ target_branch }}, {{ conflicted_files }}"
        },
        "rebaseWorktreeWithConflicts": {
          "type": "string",
          "description": "Prompt template for resolving rebase conflicts. Variables: {{ worktree_dir }}, {{ worktree_name }}, {{ branch }}, {{ target_branch }}, {{ conflicted_files }}"
        }
      },
      "additionalProperties": false
    },
    "mappings": {
      "type": "object",
      "description": "Keyboard shortcut mappings (keys use namespaced action IDs)",
      "properties": {
        "app::quit": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to quit the application",
          "default": { "mac": "cmd+q", "other": "ctrl+q" }
        },
        "app::addProject": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to add a new project",
          "default": { "mac": "cmd+o", "other": "ctrl+o" }
        },
        "palette::projectSwitcher": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to open the project switcher",
          "default": { "mac": "cmd+shift+o", "other": "ctrl+shift+o" }
        },
        "worktree::new": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to create a new worktree",
          "default": { "mac": "cmd+n", "other": "ctrl+n" }
        },
        "scratch::new": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to create a new scratch terminal",
          "default": { "mac": "cmd+shift+n", "other": "ctrl+shift+n" }
        },
        "session::newTab": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to create a new tab",
          "default": { "mac": "cmd+t", "other": "ctrl+t" }
        },
        "session::closeTab": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to close the current tab or session",
          "default": { "mac": "cmd+w", "other": "ctrl+w" }
        },
        "drawer::toggle": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to toggle the drawer panel",
          "default": "ctrl+`"
        },
        "rightPanel::toggle": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to toggle the right panel",
          "default": { "mac": "cmd+b", "other": "ctrl+b" }
        },
        "drawer::expand": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to expand the drawer to full screen",
          "default": "shift+Escape"
        },
        "palette::toggle": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to open the command palette",
          "default": { "mac": "cmd+shift+p", "other": "ctrl+shift+p" }
        },
        "view::zoomIn": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to increase terminal font size in focused pane",
          "default": { "mac": "cmd+=", "other": "ctrl+=" }
        },
        "view::zoomOut": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to decrease terminal font size in focused pane",
          "default": { "mac": "cmd+-", "other": "ctrl+-" }
        },
        "view::zoomReset": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to reset terminal font size in focused pane to base size",
          "default": { "mac": "cmd+shift+0", "other": "ctrl+shift+0" }
        },
        "navigate::prev": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to switch to the previous session",
          "default": { "mac": "ctrl+cmd+k", "other": "ctrl+shift+k" }
        },
        "navigate::next": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to switch to the next session",
          "default": { "mac": "ctrl+cmd+j", "other": "ctrl+shift+j" }
        },
        "navigate::back": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to navigate back in history",
          "default": { "mac": "cmd+[", "other": "ctrl+[" }
        },
        "navigate::forward": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to navigate forward in history",
          "default": { "mac": "cmd+]", "other": "ctrl+]" }
        },
        "diff::nextFile": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to go to the next changed file in diff view",
          "default": { "mac": "cmd+j", "other": "ctrl+j" }
        },
        "diff::prevFile": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to go to the previous changed file in diff view",
          "default": { "mac": "cmd+k", "other": "ctrl+k" }
        },
        "focus::switch": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to switch focus between main pane and drawer",
          "default": "ctrl+\\"
        },
        "navigate::toEntity1": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to switch to session 1",
          "default": { "mac": "ctrl+cmd+1", "other": "ctrl+1" }
        },
        "navigate::toEntity2": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to switch to session 2",
          "default": { "mac": "ctrl+cmd+2", "other": "ctrl+2" }
        },
        "navigate::toEntity3": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to switch to session 3",
          "default": { "mac": "ctrl+cmd+3", "other": "ctrl+3" }
        },
        "navigate::toEntity4": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to switch to session 4",
          "default": { "mac": "ctrl+cmd+4", "other": "ctrl+4" }
        },
        "navigate::toEntity5": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to switch to session 5",
          "default": { "mac": "ctrl+cmd+5", "other": "ctrl+5" }
        },
        "navigate::toEntity6": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to switch to session 6",
          "default": { "mac": "ctrl+cmd+6", "other": "ctrl+6" }
        },
        "navigate::toEntity7": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to switch to session 7",
          "default": { "mac": "ctrl+cmd+7", "other": "ctrl+7" }
        },
        "navigate::toEntity8": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to switch to session 8",
          "default": { "mac": "ctrl+cmd+8", "other": "ctrl+8" }
        },
        "navigate::toEntity9": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to switch to session 9",
          "default": { "mac": "ctrl+cmd+9", "other": "ctrl+9" }
        },
        "worktree::renameBranch": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to rename the current branch",
          "default": "F2"
        },
        "task::run": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to open the task runner",
          "default": { "mac": "cmd+r", "other": "ctrl+shift+r" }
        },
        "task::switcher": {
          "$ref": "#/$defs/shortcut",
          "description": "Shortcut to open the task switcher",
          "default": { "mac": "cmd+;", "other": "ctrl+;" }
        }
      },
      "additionalProperties": false
    },
    "tasks": {
      "type": "array",
      "description": "Configurable tasks that can be run per-worktree",
      "items": {
        "$ref": "#/$defs/task"
      },
      "default": []
    },
    "theme": {
      "description": "Theme configuration. Can be a single theme name (ignores system preference) or an object with light/dark themes (switches based on system preference).",
      "oneOf": [
        {
          "type": "string",
          "description": "Single theme name (ignores system preference)",
          "examples": ["Catppuccin Mocha", "Dracula", "One Dark Pro"]
        },
        {
          "type": "object",
          "description": "Different themes for light and dark mode (switches based on system preference)",
          "properties": {
            "light": {
              "type": "string",
              "description": "Theme to use when system is in light mode"
            },
            "dark": {
              "type": "string",
              "description": "Theme to use when system is in dark mode"
            }
          },
          "required": ["light", "dark"],
          "additionalProperties": false
        }
      ],
      "default": { "light": "Catppuccin Latte", "dark": "Catppuccin Mocha" }
    },
    "themeBorderStyle": {
      "type": "string",
      "enum": ["theme", "subtle", "visible"],
      "description": "How to handle borders when adapting themes. 'theme' uses exactly what the theme specifies (including transparent). 'subtle' adds subtle borders only where none exist. 'visible' always ensures visible borders.",
      "default": "subtle"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "appTarget": {
      "type": "string",
      "enum": ["external", "drawer", "tab", "terminal"],
      "description": "Where to open the app: 'external' (run command directly), 'drawer' (shellflow drawer), 'tab' (new main area tab), 'terminal' (inside a new terminal window)"
    },
    "appConfigFull": {
      "type": "object",
      "description": "Full app configuration with optional command and target",
      "properties": {
        "command": {
          "type": "string",
          "description": "Command to use. Supports {{ path }} template for path placement. If template is omitted, path is appended. Examples: 'nvim', 'code -g {{ path }}', 'nvim +100 {{ path }}'."
        },
        "target": {
          "$ref": "#/$defs/appTarget",
          "description": "Where to open the app",
          "default": "external"
        }
      },
      "additionalProperties": false
    },
    "appConfig": {
      "oneOf": [
        {
          "type": "string",
          "description": "Simple string format: command with optional {{ path }} template. If template is omitted, path is appended."
        },
        {
          "$ref": "#/$defs/appConfigFull"
        }
      ],
      "description": "App configuration: either a simple command string or full object with command and target. Supports {{ path }} template."
    },
    "shortcutString": {
      "type": "string",
      "description": "A keyboard shortcut string. Format: 'mod+key' where mod is ctrl, cmd, alt, shift. 'cmd' = Cmd on macOS, Ctrl on other platforms.",
      "pattern": "^((ctrl|cmd|alt|shift)\\+)*(\\S+)$",
      "examples": ["ctrl+`", "cmd+c", "cmd+shift+p", "ctrl+shift+c"]
    },
    "platformShortcut": {
      "type": "object",
      "description": "Platform-specific shortcut mapping",
      "properties": {
        "mac": {
          "type": "string",
          "description": "Shortcut to use on macOS"
        },
        "other": {
          "type": "string",
          "description": "Shortcut to use on non-macOS platforms (Linux, Windows)"
        }
      },
      "additionalProperties": false
    },
    "shortcutEntry": {
      "oneOf": [
        { "$ref": "#/$defs/shortcutString" },
        { "$ref": "#/$defs/platformShortcut" }
      ],
      "description": "A shortcut entry: either a universal string or platform-specific object"
    },
    "shortcut": {
      "oneOf": [
        { "$ref": "#/$defs/shortcutString" },
        { "$ref": "#/$defs/platformShortcut" },
        {
          "type": "array",
          "items": { "$ref": "#/$defs/shortcutEntry" },
          "description": "An array of shortcut entries (strings and/or platform objects)"
        }
      ],
      "description": "A shortcut configuration: string, platform object, or array of both"
    },
    "task": {
      "type": "object",
      "description": "A configurable task that can be run in a worktree",
      "properties": {
        "name": {
          "type": "string",
          "description": "Display name for the task (must be unique)"
        },
        "command": {
          "type": "string",
          "description": "Shell command to run. Supports minijinja: {{ branch }}, {{ branch | hash_port }}, {{ branch | sanitize }}, {{ branch | shell_escape }}"
        },
        "kind": {
          "type": "string",
          "enum": ["command", "daemon"],
          "description": "Task kind: 'command' runs to completion, 'daemon' stays running until stopped",
          "default": "command"
        },
        "silent": {
          "type": "boolean",
          "description": "If true, task runs without showing output in drawer",
          "default": false
        },
        "shell": {
          "type": "string",
          "description": "Override shell to run command with (e.g., '/bin/bash', 'fish')"
        },
        "env": {
          "type": "object",
          "description": "Environment variables to set when running the task. Values support minijinja: {{ branch }}, {{ branch | hash_port }}, {{ branch | sanitize }}, {{ branch | shell_escape }}",
          "additionalProperties": {
            "type": "string",
            "description": "Environment variable value (supports templates)"
          },
          "examples": [
            { "PORT": "3000" },
            { "PORT": "{{ branch | hash_port }}", "NODE_ENV": "development" }
          ]
        },
        "urls": {
          "type": "object",
          "description": "Named URL templates to display when task is running. Key is the link label, value is the URL template. Supports minijinja: {{ branch }}, {{ branch | hash_port }}, {{ branch | sanitize }}, {{ branch | shell_escape }}",
          "additionalProperties": {
            "type": "string",
            "description": "URL template"
          },
          "examples": [
            { "Dev": "http://localhost:3000" },
            { "Dev": "http://localhost:{{ branch | hash_port }}", "API": "http://localhost:{{ branch | hash_port }}/api" }
          ]
        }
      },
      "required": ["name", "command"],
      "additionalProperties": false
    }
  }
}