Configuration Reference

Overview

Jean stores all configuration in a preferences file. This reference documents every available setting.

Configuration File Location

macOS: ~/Library/Application Support/io.coollabs.jean/preferences.json Linux: ~/.config/jean/preferences.json Windows: %APPDATA%\jean\preferences.json

AppPreferences Schema

Complete TypeScript interface from src/types/preferences.ts:

export interface AppPreferences {
  // Appearance
  theme: string                              // 'system' | 'light' | 'dark'
  ui_font_size: number                       // 12-24 (default: 16)
  chat_font_size: number                     // 12-24 (default: 16)
  ui_font: UIFont                            // 'inter' | 'geist' | 'roboto' | 'lato' | 'system'
  chat_font: ChatFont                        // 'jetbrains-mono' | 'fira-code' | 'source-code-pro' | 'inter' | 'geist' | 'roboto' | 'lato'
  syntax_theme_dark: SyntaxTheme             // Dark mode syntax highlighting theme
  syntax_theme_light: SyntaxTheme            // Light mode syntax highlighting theme
  zoom_level: number                         // 50-200 (default: 90)
  canvas_layout: CanvasLayout                // 'grid' | 'list'
  show_keybinding_hints: boolean             // Show keyboard shortcut hints at bottom (default: true)

  // AI Models & Backends
  selected_model: ClaudeModel                // 'opus' | 'opus-4.5' | 'sonnet' | 'sonnet-4.5' | 'haiku'
  thinking_level: ThinkingLevel              // 'off' | 'think' | 'megathink' | 'ultrathink'
  default_effort_level: EffortLevel          // 'low' | 'medium' | 'high' | 'max' (Opus 4.6 adaptive thinking)
  default_backend: CliBackend                // 'claude' | 'codex' | 'opencode'
  selected_codex_model: CodexModel           // 'gpt-5.3-codex' | 'gpt-5.2-codex' | 'gpt-5.1-codex-max' | 'gpt-5.2' | 'gpt-5.1-codex-mini'
  selected_opencode_model: string            // OpenCode model (provider/model format)
  default_codex_reasoning_effort: CodexReasoningEffort  // 'low' | 'medium' | 'high' | 'xhigh'
  codex_multi_agent_enabled: boolean         // Enable Codex multi-agent collaboration (default: false)
  codex_max_agent_threads: number            // 1-8 (default: 3)

  // Developer Tools
  terminal: TerminalApp                      // 'terminal' | 'warp' | 'ghostty' | 'iterm2' | 'windows-terminal' | 'powershell' | 'cmd'
  editor: EditorApp                          // 'zed' | 'vscode' | 'cursor' | 'xcode'
  open_in: OpenInDefault                     // 'editor' | 'terminal' | 'finder' | 'github'
  file_edit_mode: FileEditMode               // 'inline' | 'external'

  // Session Management
  auto_session_naming: boolean               // Auto-generate session names (default: true)
  session_naming_model: ClaudeModel          // Model for session naming (default: 'haiku')
  session_recap_enabled: boolean             // Show session recap when returning (default: false)
  restore_last_session: boolean              // Restore last session when switching projects (default: false)
  close_original_on_clear_context: boolean   // Close original when using Clear Context (default: true)
  confirm_session_close: boolean             // Show confirmation before closing (default: true)

  // Worktree & Git
  auto_branch_naming: boolean                // Auto-generate branch names (default: true)
  branch_naming_model: ClaudeModel           // Model for branch naming (default: 'haiku')
  auto_pull_base_branch: boolean             // Auto-pull base before creating worktree (default: true)
  auto_archive_on_pr_merged: boolean         // Auto-archive when PR merged (default: true)
  git_poll_interval: number                  // Git status poll interval in seconds, 10-600 (default: 60)
  remote_poll_interval: number               // Remote API poll interval in seconds, 30-600 (default: 60)

  // Archive & Cleanup
  archive_retention_days: number             // Days to keep archived items, 0 = never (default: 7)
  removal_behavior: RemovalBehavior          // 'archive' | 'delete' (default: 'delete')

  // Magic Prompts
  magic_prompts: MagicPrompts                // Customizable AI prompts (null = use defaults)
  magic_prompt_models: MagicPromptModels     // Per-prompt model overrides
  magic_prompt_providers: MagicPromptProviders  // Per-prompt provider overrides
  magic_prompt_backends: MagicPromptBackends    // Per-prompt backend overrides
  parallel_execution_prompt_enabled: boolean    // Add parallel execution system prompt (default: false)

  // MCP Servers
  default_enabled_mcp_servers: string[]      // MCP server names enabled by default (default: [])
  known_mcp_servers: string[]                // All MCP server names ever seen (default: [])

  // Integrations
  chrome_enabled: boolean                    // Enable Chrome extension integration (default: true)
  linear_api_key: string | null              // Global Linear API key (default: null)

  // Remote Access
  http_server_enabled: boolean               // Enable HTTP server (default: false)
  http_server_port: number                   // Server port (default: 3456)
  http_server_token: string | null           // Auth token (auto-generated)
  http_server_auto_start: boolean            // Auto-start on launch (default: false)
  http_server_localhost_only: boolean        // Bind to localhost only (default: true)
  http_server_token_required: boolean        // Require token (default: true)

  // Advanced
  ai_language: string                        // Preferred language for AI responses (default: '')
  allow_web_tools_in_plan_mode: boolean      // Allow WebFetch/WebSearch in plan mode (default: true)
  debug_mode_enabled: boolean                // Show debug panel (default: false)
  default_provider: string | null            // Default CLI profile name (null = Anthropic)
  custom_cli_profiles: CustomCliProfile[]    // Custom CLI settings profiles (default: [])

  // Notifications
  waiting_sound: NotificationSound           // 'none' | 'ding' | 'chime' | 'pop' | 'choochoo' (default: 'none')
  review_sound: NotificationSound            // Sound when review finishes (default: 'none')

  // Keyboard Shortcuts
  keybindings: KeybindingsMap                // User-configurable keyboard shortcuts

  // Onboarding
  has_seen_feature_tour: boolean             // Whether user completed feature tour (default: false)
  has_seen_jean_config_wizard: boolean       // Whether user completed jean.json wizard (default: false)

  // Plan Mode Overrides
  build_model: string | null                 // Model for plan approval (build), null = session model
  yolo_model: string | null                  // Model for yolo approval, null = session model
  build_backend: string | null               // Backend for build mode, null = session backend
  yolo_backend: string | null                // Backend for yolo mode, null = session backend
  build_thinking_level: string | null        // Thinking level for build, null = session level
  yolo_thinking_level: string | null         // Thinking level for yolo, null = session level
}

Type Definitions

Appearance Types

type UIFont = 'inter' | 'geist' | 'roboto' | 'lato' | 'system'
type ChatFont = 'jetbrains-mono' | 'fira-code' | 'source-code-pro' | 'inter' | 'geist' | 'roboto' | 'lato'

type SyntaxTheme =
  | 'vitesse-black' | 'vitesse-dark' | 'vitesse-light'
  | 'github-dark' | 'github-light' | 'github-dark-dimmed'
  | 'dracula' | 'dracula-soft'
  | 'nord'
  | 'catppuccin-mocha' | 'catppuccin-macchiato' | 'catppuccin-frappe' | 'catppuccin-latte'
  | 'one-dark-pro' | 'one-light'
  | 'tokyo-night'
  | 'rose-pine' | 'rose-pine-moon' | 'rose-pine-dawn'

type CanvasLayout = 'grid' | 'list'
type FontSize = number  // 12-24

Model Types

type ClaudeModel = 'opus' | 'opus-4.5' | 'sonnet' | 'sonnet-4.5' | 'haiku'

type CodexModel =
  | 'gpt-5.3-codex'
  | 'gpt-5.2-codex'
  | 'gpt-5.1-codex-max'
  | 'gpt-5.2'
  | 'gpt-5.1-codex-mini'

type OpenCodeModel = `opencode/${string}`  // e.g., 'opencode/gpt-5.3-codex'

type ThinkingLevel = 'off' | 'think' | 'megathink' | 'ultrathink'
type EffortLevel = 'low' | 'medium' | 'high' | 'max'
type CodexReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh'

Backend Types

type CliBackend = 'claude' | 'codex' | 'opencode'

interface CustomCliProfile {
  name: string                    // Display name
  settings_json: string           // JSON string matching Claude CLI format
  file_path?: string              // Path to settings file on disk
  supports_thinking?: boolean     // Whether provider supports thinking/effort
}

Tool Types

type TerminalApp =
  | 'terminal' | 'warp' | 'ghostty' | 'iterm2'           // macOS/Linux
  | 'windows-terminal' | 'powershell' | 'cmd'           // Windows

type EditorApp = 'zed' | 'vscode' | 'cursor' | 'xcode'
type OpenInDefault = 'editor' | 'terminal' | 'finder' | 'github'
type FileEditMode = 'inline' | 'external'

Magic Prompt Types

interface MagicPrompts {
  investigate_issue: string | null
  investigate_pr: string | null
  pr_content: string | null
  commit_message: string | null
  code_review: string | null
  context_summary: string | null
  resolve_conflicts: string | null
  investigate_workflow_run: string | null
  release_notes: string | null
  session_naming: string | null
  parallel_execution: string | null
  global_system_prompt: string | null
  session_recap: string | null
  investigate_security_alert: string | null
  investigate_advisory: string | null
  investigate_linear_issue: string | null
}

interface MagicPromptModels {
  investigate_issue_model: MagicPromptModel
  investigate_pr_model: MagicPromptModel
  // ... (same keys with _model suffix)
}

interface MagicPromptProviders {
  investigate_issue_provider: string | null
  investigate_pr_provider: string | null
  // ... (same keys with _provider suffix)
}

interface MagicPromptBackends {
  investigate_issue_backend: string | null
  investigate_pr_backend: string | null
  // ... (same keys with _backend suffix)
}

Other Types

type RemovalBehavior = 'archive' | 'delete'
type NotificationSound = 'none' | 'ding' | 'chime' | 'pop' | 'choochoo'

type KeybindingsMap = Record<string, string>  // action -> shortcut

Default Values

export const defaultPreferences: AppPreferences = {
  theme: 'system',
  selected_model: 'opus',
  thinking_level: 'ultrathink',
  default_effort_level: 'high',
  terminal: 'terminal',
  editor: 'zed',
  open_in: 'editor',
  auto_branch_naming: true,
  branch_naming_model: 'haiku',
  auto_session_naming: true,
  session_naming_model: 'haiku',
  ui_font_size: 16,
  chat_font_size: 16,
  ui_font: 'geist',
  chat_font: 'geist',
  git_poll_interval: 60,
  remote_poll_interval: 60,
  keybindings: DEFAULT_KEYBINDINGS,
  archive_retention_days: 7,
  syntax_theme_dark: 'vitesse-black',
  syntax_theme_light: 'github-light',
  session_recap_enabled: false,
  parallel_execution_prompt_enabled: false,
  magic_prompts: DEFAULT_MAGIC_PROMPTS,
  magic_prompt_models: DEFAULT_MAGIC_PROMPT_MODELS,
  magic_prompt_providers: DEFAULT_MAGIC_PROMPT_PROVIDERS,
  magic_prompt_backends: DEFAULT_MAGIC_PROMPT_BACKENDS,
  file_edit_mode: 'external',
  ai_language: '',
  allow_web_tools_in_plan_mode: true,
  waiting_sound: 'none',
  review_sound: 'none',
  http_server_enabled: false,
  http_server_port: 3456,
  http_server_token: null,
  http_server_auto_start: false,
  http_server_localhost_only: true,
  http_server_token_required: true,
  removal_behavior: 'delete',
  auto_pull_base_branch: true,
  auto_archive_on_pr_merged: true,
  show_keybinding_hints: true,
  debug_mode_enabled: false,
  default_enabled_mcp_servers: [],
  known_mcp_servers: [],
  has_seen_feature_tour: false,
  has_seen_jean_config_wizard: false,
  chrome_enabled: true,
  zoom_level: 90,
  custom_cli_profiles: [],
  default_provider: null,
  canvas_layout: 'list',
  confirm_session_close: true,
  default_backend: 'claude',
  selected_codex_model: 'gpt-5.3-codex',
  selected_opencode_model: 'opencode/gpt-5.3-codex',
  default_codex_reasoning_effort: 'high',
  codex_multi_agent_enabled: false,
  codex_max_agent_threads: 3,
  restore_last_session: false,
  close_original_on_clear_context: true,
  build_model: null,
  yolo_model: null,
  build_backend: null,
  yolo_backend: null,
  build_thinking_level: null,
  yolo_thinking_level: null,
  linear_api_key: null,
}

Project Configuration

Per-project settings (stored in project database):

interface Project {
  id: string                           // UUID v4
  name: string                         // Display name
  path: string                         // Absolute path to repo
  default_branch: string               // Base branch name
  added_at: number                     // Unix timestamp
  order: number                        // Display order
  parent_id?: string                   // Parent folder ID
  is_folder?: boolean                  // True if folder
  avatar_path?: string                 // Custom avatar image path
  enabled_mcp_servers?: string[] | null   // Project MCP servers (null = inherit)
  known_mcp_servers?: string[]         // All servers ever seen
  custom_system_prompt?: string        // Project system prompt
  default_provider?: string | null     // Project default provider
  default_backend?: string | null      // Project default backend
  worktrees_dir?: string | null        // Custom worktrees location
  linear_api_key?: string | null       // Project Linear API key
  linear_team_id?: string | null       // Linear team ID filter
}

jean.json Schema

Per-project scripts configuration (committed to repo):

{
  "scripts": {
    "setup": "bun install && bun run build",
    "run": "bun run dev",
    "teardown": "rm -rf node_modules"
  }
}

interface JeanConfig {
  scripts?: {
    setup?: string       // Run after worktree creation
    run?: string         // Run when "Execute Run" is triggered
    teardown?: string    // Run before worktree deletion
  }
}

Environment Variables

Jean respects these environment variables:

# Claude CLI
ANTHROPIC_API_KEY          # API key
ANTHROPIC_BASE_URL         # Custom API endpoint
ANTHROPIC_AUTH_TOKEN       # Alternative auth token

# Codex CLI
OPENAI_API_KEY             # API key
CODEX_BASE_URL             # Custom API endpoint

# OpenCode
OPENCODE_API_KEY           # API key
OPENCODE_BASE_URL          # Custom API endpoint

# Jean
JEAN_LOG_LEVEL             # 'trace' | 'debug' | 'info' | 'warn' | 'error'
JEAN_CONFIG_DIR            # Custom config directory
JEAN_DATA_DIR              # Custom data directory

Configuration Precedence

Jean uses a layered configuration system:

Session-level - Chosen in UI (highest priority)
Project-level - Project settings
Global-level - Preferences
Default - Hardcoded defaults (lowest priority)

Example: Model selection

Session model > Project default_backend > Global default_backend > 'claude'

Manual Editing

Warning: Editing preferences.json directly can break Jean if invalid. Best practice:

Close Jean
Back up preferences.json
Edit carefully (validate JSON)
Restart Jean
If Jean fails to start, restore backup

Validation:

# Check JSON syntax
jq . preferences.json

# Pretty-print
jq . preferences.json > preferences.formatted.json

Resetting Configuration

Reset all preferences:

Close Jean
Delete preferences.json
Restart Jean (will recreate with defaults)

Reset specific preference:

Open Preferences UI
Find setting
Click “Reset to Default” (if available)
Or manually edit to default value

Reset keybindings:

Preferences > Keyboard Shortcuts
Click “Reset All to Defaults”

Migration

Jean automatically migrates old configs to new formats. Example: Keybinding migration (from src/services/preferences.ts):

const MIGRATED_KEYBINDINGS: Partial<Record<keyof KeybindingsMap, string>> = {
  toggle_left_sidebar: 'mod+1',        // Old default
  open_provider_dropdown: 'alt+p',     // Old default
}

// On load, if stored value matches old default, update to new default
if (stored.toggle_left_sidebar === 'mod+1') {
  stored.toggle_left_sidebar = 'mod+b'  // New default
}

Migrations happen silently on app load.

Get Started

Core Concepts

Features

Guides

Advanced

Reference

Configuration Reference

Overview

Configuration File Location

AppPreferences Schema

Type Definitions

Appearance Types

Model Types

Backend Types

Tool Types

Magic Prompt Types

Other Types

Default Values

Project Configuration

jean.json Schema

Environment Variables

Configuration Precedence

Manual Editing

Resetting Configuration

Migration

​Overview

​Configuration File Location

​AppPreferences Schema

​Type Definitions

​Appearance Types

​Model Types

​Backend Types

​Tool Types

​Magic Prompt Types

​Other Types

​Default Values

​Project Configuration

​jean.json Schema

​Environment Variables

​Configuration Precedence

​Manual Editing

​Resetting Configuration

​Migration

Overview

Configuration File Location

AppPreferences Schema

Type Definitions

Appearance Types

Model Types

Backend Types

Tool Types

Magic Prompt Types

Other Types

Default Values

Project Configuration

jean.json Schema

Environment Variables

Configuration Precedence

Manual Editing

Resetting Configuration

Migration