Skip to main content

​
Overview

Jean is highly customizable to match your preferences and workflow. You can adjust appearance, behavior, AI prompts, and keyboard shortcuts. All settings are accessed via Preferences (Cmd+, on Mac, Ctrl+, on Windows/Linux).

​
Appearance

​
Themes

1

Open Preferences

Press Cmd+, and go to the Appearance tab.
2

Select Theme

Choose from:
  • System: Follows your OS theme (light/dark mode)
  • Light: Always light mode
  • Dark: Always dark mode
The UI updates immediately.
3

Customize Syntax Highlighting

Scroll down to Code Syntax Theme.Dark Mode Themes:
  • Vitesse Black (default)
  • Vitesse Dark
  • GitHub Dark
  • GitHub Dark Dimmed
  • Dracula
  • Dracula Soft
  • Nord
  • Catppuccin Mocha/Macchiato/Frappé
  • One Dark Pro
  • Tokyo Night
  • Rosé Pine/Moon
Light Mode Themes:
  • GitHub Light (default)
  • Vitesse Light
  • Catppuccin Latte
  • One Light
  • Rosé Pine Dawn
Choose separate themes for dark and light modes.

​
Fonts and Sizing

1

UI Font

In Appearance → UI Font, choose from:
  • Geist (default, modern sans-serif)
  • Inter (popular web font)
  • Roboto (Google’s font)
  • Lato (humanist sans-serif)
  • System Default (uses your OS font)
This affects sidebar, toolbar, buttons, and menus.
2

Chat Font

In Appearance → Chat Font, choose from:
  • Geist (default for readability)
  • JetBrains Mono (monospace with ligatures)
  • Fira Code (monospace with ligatures)
  • Source Code Pro (Adobe’s monospace)
  • Inter/Roboto/Lato (sans-serif options)
This affects chat messages, code blocks, and file diffs.
3

Font Sizes

Adjust UI Font Size and Chat Font Size independently:
  • Range: 12px - 24px
  • Default: 16px
Drag the slider or type a custom value.
4

Zoom Level

Adjust Zoom Level to scale the entire app:
  • Range: 50% - 200%
  • Default: 90%
Useful for high-DPI displays or vision accessibility.

​
Canvas Layout

1

Choose Layout Mode

In Appearance → Canvas Layout, choose:Grid (default): Cards displayed in a grid with larger previewsList: Compact rows for seeing more sessions at once
2

Toggle Keybinding Hints

Enable Show Keybinding Hints to display keyboard shortcuts at the bottom of canvas views.Disable for a cleaner UI once you’ve memorized the shortcuts.

​
AI Models and Providers

​
Default Model

1

Open General Settings

In Preferences → General tab, find AI Model.
2

Select Backend

Choose the CLI backend:
  • Claude: Anthropic’s Claude models
  • Codex: OpenAI’s GPT models optimized for coding
  • OpenCode: Custom model configurations
3

Select Model

Claude models:
  • Opus 4.6: Most capable, best for complex tasks
  • Opus 4.5: Previous generation
  • Sonnet 4.6: Balanced performance and speed (recommended)
  • Sonnet 4.5: Previous generation
  • Haiku: Fastest, best for simple tasks
Codex models:
  • GPT 5.3 Codex: Latest model
  • GPT 5.2 Codex: Previous generation
  • GPT 5.1 Codex Max: Maximum capability
  • GPT 5.2: Base model
  • GPT 5.1 Codex Mini: Lightweight and fast
OpenCode models: Fully customizable (provider/model format)
4

Thinking Level (Claude Only)

Choose extended thinking depth:
  • Off: No extended thinking (fastest)
  • Think (4K): Light reasoning (recommended)
  • Megathink (10K): Deep reasoning
  • Ultrathink (32K): Maximum reasoning (slowest, most thorough)
5

Effort Level (Opus 4.6 Only)

For Claude Opus 4.6 with adaptive thinking:
  • Low: Minimal thinking
  • Medium: Moderate thinking
  • High: Deep reasoning (recommended)
  • Max: No limits on thinking

​
Custom Providers

1

Add Custom Provider

In Preferences → Providers tab, click Add Provider.
2

Choose Preset or Custom

Presets:
  • OpenRouter: Route requests to multiple providers
  • MiniMax: Chinese AI provider
  • Z.ai: ZhiPu AI (GLM models)
  • Moonshot: Kimi AI
Custom: Define your own provider with JSON settings.
3

Configure Provider

For custom providers, edit the JSON settings:
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.example.com",
    "ANTHROPIC_AUTH_TOKEN": "your-api-key",
    "ANTHROPIC_MODEL": "custom-model-name"
  }
}
This maps to Claude CLI’s settings format.
4

Set as Default

In Preferences → General → Default Provider, select your custom provider.New sessions will use this provider by default.

​
Magic Prompts

Magic prompts are customizable templates used by AI-powered features.
1

Open Magic Prompts

In Preferences → Magic Prompts tab, you’ll see all available prompts:
  • Investigate Issue
  • Investigate PR
  • PR Content
  • Commit Message
  • Code Review
  • Context Summary
  • Resolve Conflicts
  • Investigate Workflow Run
  • Release Notes
  • Session Naming
  • Session Recap
  • Investigate Security Alert
  • Investigate Advisory
  • Investigate Linear Issue
  • Global System Prompt
  • Parallel Execution Prompt
2

Edit a Prompt

Click Edit next to any prompt to open the editor.You’ll see:
  • Current prompt: The active template
  • Default prompt: Jean’s built-in default
  • Variables: Available placeholders (e.g., {commits}, {diff})
3

Customize Prompt

Modify the prompt to match your workflow. Example:Default Commit Message Prompt:
<task>Generate a commit message for the following changes</task>

<staged_diff>
{diff}
</staged_diff>
Customized for Conventional Commits:
<task>Generate a commit message using Conventional Commits format</task>

<format>
<type>(<scope>): <description>

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, chore
</format>

<staged_diff>
{diff}
</staged_diff>

<recent_commits>
{recent_commits}
</recent_commits>
4

Override Model/Provider

Each magic prompt can use a different model/provider:Click Model Override and select:
  • None: Use default model
  • Haiku/Sonnet/Opus: Claude models
  • Codex models: GPT models
  • OpenCode models: Custom models
Click Provider Override to choose a specific provider (or None to use default).Click Backend Override to force a specific backend (Claude/Codex/OpenCode).
Use lightweight models (Haiku, GPT 5.1 Codex Mini) for simple prompts like commit messages and release notes. Use premium models (Opus, GPT 5.3 Codex) for investigation and code review.
5

Reset to Default

Click Reset to Default to restore Jean’s built-in prompt.

​
Global System Prompt

The Global System Prompt is appended to every chat session (like ~/.claude/CLAUDE.md). Default includes:
  • Plan mode preference for non-trivial tasks
  • Subagent strategy for parallel work
  • Self-improvement loop (learning from corrections)
  • Verification checklist before marking tasks complete
  • Autonomous bug fixing guidelines
  • Task management with .ai/todo.md and .ai/lessons.md
Customize this to:
  • Add team-specific coding standards
  • Enforce architectural patterns
  • Set testing requirements
  • Define code review criteria

​
Keyboard Shortcuts

1

Open Keybindings

In Preferences → Keybindings tab, you’ll see all shortcuts organized by category:
  • Navigation: Sidebar, preferences, menus, etc.
  • Git: Commit, diff, merge, etc.
  • Chat: Sessions, input, plans, etc.
2

Customize a Shortcut

Click on a shortcut to edit it. Press the desired key combination.Format:
  • Mod+Key: Mod is Cmd on Mac, Ctrl on Windows/Linux
  • Shift+Key, Alt+Key, Mod+Shift+Key, etc.
Examples:
  • mod+l: Focus chat input
  • mod+shift+c: Open commit modal
  • mod+alt+arrowright: Next session
3

Conflict Detection

If your shortcut conflicts with an existing one, Jean will warn you.Choose to:
  • Replace: Remove the conflict and assign your shortcut
  • Cancel: Keep the existing assignment
4

Reset Shortcuts

Click Reset All to Defaults to restore Jean’s built-in keybindings.
See Keyboard Shortcuts for a complete reference.

​
Behavior Settings

​
Git and Polling

1

Git Poll Interval

How often Jean checks git status (local operations like git status, git log).Options: 10s, 30s, 1m, 2m, 5m, 10m (default: 60s)Lower = more responsive, higher CPU usage
2

Remote Poll Interval

How often Jean checks remote APIs (GitHub PR status, CI checks, security alerts).Options: 30s, 1m, 2m, 5m, 10m (default: 60s)Lower = more responsive, higher API usage (may hit rate limits)
3

Auto-Pull Base Branch

When enabled, Jean pulls the latest changes from the default branch before creating a new worktree.Trade-off: Adds a few seconds to worktree creation but ensures you start from the latest code.
4

Auto-Archive on PR Merged

When enabled, Jean automatically archives worktrees when their PR is merged.Why useful: Keeps your sidebar clean and focused on active work.

​
Session Behavior

1

Session Removal Behavior

What happens when you close a session or worktree:Archive (default): Soft-delete; can be restored laterDelete: Permanent deletion; cannot be undone
2

Archive Retention Days

How long to keep archived items before permanent deletion:Options: Never (keep forever), 7, 14, 30, 60, 90 days (default: 7 days)
3

Confirm Session Close

When enabled, Jean shows a confirmation dialog before closing sessions/worktrees.Useful if: You accidentally press Cmd+W often.
4

Restore Last Session

When enabled, switching projects restores the last worktree and session you were viewing.Useful for: Quickly resuming work after switching projects.
5

Close Original on Clear Context

When enabled, clearing context (via Cmd+Shift+Y or Cmd+Shift+Enter) closes the original session.Why: Prevents clutter from abandoned sessions after clearing context.

​
Auto-Naming

1

Auto-Branch Naming

When enabled, Jean generates branch names from the first message in a session.Example: “Fix login timeout” → fix-login-timeoutModel used: Configurable (default: Haiku)
2

Auto-Session Naming

When enabled, Jean generates session names from the first message.Example: “Help me implement user authentication” → “User authentication setup”Model used: Configurable (default: Haiku)

​
Experimental Features

1

Session Recaps

When enabled, Jean generates AI summaries when you return to unfocused sessions.Helps you quickly remember what a session was about.
2

Parallel Execution Prompt

When enabled, Jean appends a system prompt encouraging Claude to use parallel subagents for faster execution.Trade-off: More subagent spawning, higher token usage, faster completion.
3

Debug Mode

When enabled, shows debug information in chat sessions (tool calls, thinking tokens, etc.).Useful for: Understanding how Claude operates and debugging issues.

​
Notification Sounds

1

Waiting Sound

Sound played when a session finishes and is waiting for your input.Options: None (default), Ding, Chime, Pop, Choo-choo
2

Review Sound

Sound played when a session finishes reviewing code.Options: None (default), Ding, Chime, Pop, Choo-choo

​
HTTP Server (API Access)

Jean includes an HTTP server for external integrations (e.g., webhooks, browser extensions).
1

Enable HTTP Server

In Preferences → Advanced → HTTP Server, toggle Enable HTTP Server.
2

Configure Port

Set the port (default: 3456).The server listens on http://localhost:<port>.
3

Security Settings

Localhost Only: When enabled, server only accepts connections from localhost (more secure).Token Required: When enabled, all requests must include an Authorization: Bearer <token> header.Token: Auto-generated token. Copy and use in external tools.
4

Auto-Start

Enable Auto-start on launch to start the server when Jean opens.

​
Common Pitfalls

Keybinding Conflicts: If you customize shortcuts, be careful not to override OS-level shortcuts (e.g., Cmd+Q for quit on Mac).Solution: Test new shortcuts immediately after assigning them.
Magic Prompt Syntax Errors: If a customized prompt has invalid XML or missing variables, the magic command may fail.Solution: Use Reset to Default and carefully re-apply your changes.
High Polling Frequency: Setting git/remote poll intervals too low can cause high CPU usage and API rate limits.Solution: Use defaults (60s) unless you need real-time updates.

​
Best Practices

Start with Defaults: Don’t customize everything at once. Use Jean for a week with defaults, then adjust what bothers you.
Theme for Your Environment: Use dark themes in low-light environments, light themes in bright offices. System theme auto-switches for you.
Optimize for Your Workflow: If you mostly fix bugs, customize the Investigate Issue prompt to focus on regression detection. If you mostly review PRs, customize the Code Review prompt to match your team’s checklist.
Use Lightweight Models for Simple Tasks: Commit messages, release notes, and session naming don’t need Opus. Save premium models for investigation and complex code changes.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us