Skip to main content

​
Quickstart Guide

This guide will walk you through your first session with Jean - from adding a project to running your first AI-assisted chat.

​
Step 1: Add Your First Project

1

Open the Add Project Dialog

Click the Add Project button in the sidebar, or use the keyboard shortcut:
  • macOS: Cmd+N
  • Windows/Linux: Ctrl+N
2

Select a Git Repository

Click Browse and navigate to an existing git repository on your machine.
The repository must be initialized with git and have at least one commit. Jean will detect the default branch automatically.
3

Configure Project Settings

Project Name: Auto-detected from the repository directory name (can be customized)Default Branch: Auto-detected (usually main or master)Worktrees Location (optional): By default, worktrees are created in ~/jean/<project-name>/. You can customize this to any directory.Custom Avatar (optional): Upload a custom image to identify your project visually
4

Save the Project

Click Add Project. Your project will appear in the sidebar.
You can organize projects into folders by right-clicking the sidebar and selecting New Folder.

​
Step 2: Create Your First Worktree

Worktrees are isolated git branches in separate directories, allowing you to work on multiple features simultaneously.
1

Open Worktree Creation

Click your project in the sidebar, then click New Worktree or press:
  • macOS: Cmd+Shift+N
  • Windows/Linux: Ctrl+Shift+N
2

Choose a Creation Method

Jean offers several ways to create worktrees:
Just click Create for a randomly-named worktree (e.g., fuzzy-tiger-a3x9)
~/jean/my-project/fuzzy-tiger-a3x9/
3

Configure Advanced Options (Optional)

Automatically run commands after worktree creation:
npm install
npm run build
The output is captured and displayed in the worktree details.
Enable in Settings to automatically git pull the base branch before creating worktrees. Ensures you’re always working from the latest code.
4

Wait for Creation

Jean creates the worktree in the background:
  1. Creates a new git branch from your default branch
  2. Checks out the branch in a new directory
  3. Runs setup script (if configured)
  4. Indexes files for AI context
Large repositories may take a few seconds to index. Jean shows progress in the sidebar.

​
Step 3: Start Your First Chat Session

1

Open the Worktree

Click your newly created worktree in the sidebar. The chat interface opens automatically.
2

Configure Session Settings

Before sending your first message, review the toolbar settings:Model Selection:
  • Claude Opus 4.6: Most capable, best for complex tasks
  • Claude Sonnet 4.6: Balanced performance and cost (default)
  • Claude Haiku 4: Fastest, best for simple tasks
Execution Mode:
  • Plan: Read-only mode (Claude can’t modify files)
  • Build: Auto-approve file edits (you approve other actions)
  • Yolo: Auto-approve everything (use with caution!)
Thinking Level (Claude CLI):
  • Off: No thinking tokens
  • Think: 4K token budget
  • Megathink: 10K budget
  • Ultrathink: 32K budget (default)
Start with Sonnet in Plan mode with Ultrathink for safe exploration.
3

Send Your First Message

Try one of these example prompts:
Give me an overview of this project's architecture. What are the main components and how do they interact?
Press Enter to send (or Shift+Enter for new line).
4

Interact with AI Responses

As Claude responds, you’ll see:
  • Text responses: Claude’s explanation and reasoning
  • Tool calls: File reads, edits, bash commands, etc.
  • Thinking blocks: Claude’s internal reasoning (if enabled)
In Plan mode, Claude will ask permission for actions:
  • Approve Plan: Execute the proposed plan (switches to Build mode)
  • Reject: Provide feedback and iterate
In Build or Yolo mode, file changes are applied immediately. Always review changes with the diff viewer.

​
Step 4: Review and Commit Changes

1

View Changes

Click the Git Status tab to see modified files.Click any file to open the diff viewer:
  • Unified view: Traditional diff format
  • Side-by-side view: Compare old and new versions
2

Generate a Commit Message

Click the Commit button in the Git Status panel.Jean can generate a semantic commit message:
  1. Click Generate Message
  2. AI analyzes your changes
  3. Generates a conventional commit message
Or write your own and click Commit.
3

Create a Pull Request

Click Create PR in the toolbar.Jean can auto-generate PR content:
  1. Click Generate Content
  2. AI analyzes commits and changes
  3. Generates title and description
  4. Creates PR on GitHub
The PR is linked to your worktree and tracked in the sidebar.

​
Essential Keyboard Shortcuts

Jean is designed for keyboard-driven workflows:

Navigation

  • Cmd/Ctrl+K: Command palette
  • Cmd/Ctrl+P: Switch projects
  • Cmd/Ctrl+O: Switch worktrees
  • Cmd/Ctrl+1-9: Switch sessions

Actions

  • Cmd/Ctrl+N: New project
  • Cmd/Ctrl+Shift+N: New worktree
  • Cmd/Ctrl+Enter: Send message
  • Esc: Cancel streaming response

Session Control

  • Tab: Cycle execution mode forward
  • Shift+Tab: Cycle execution mode backward
  • Cmd/Ctrl+R: Run plan (in Plan mode)
  • Cmd/Ctrl+/: Toggle sidebar

View Control

  • Cmd/Ctrl+B: Toggle file browser
  • Cmd/Ctrl+G: Toggle git status
  • Cmd/Ctrl+T: Toggle terminal
  • Cmd/Ctrl+,: Open settings
Press Cmd/Ctrl+K to open the command palette and discover all available commands.

​
Using Magic Commands

Magic commands are AI-powered shortcuts for common workflows:
When you create a worktree from a GitHub issue, use:
/investigate
Jean automatically:
  1. Loads the issue context
  2. Analyzes the problem
  3. Explores the codebase
  4. Proposes a solution

​
Working with Multiple Sessions

One of Jean’s most powerful features is managing multiple parallel sessions:
1

Create a New Session

Click the + button next to the session list, or press Cmd/Ctrl+Shift+TEach session has:
  • Independent chat history
  • Separate AI context
  • Own execution mode settings
2

Switch Between Sessions

  • Click session tabs at the top
  • Use Cmd/Ctrl+1 through Cmd/Ctrl+9 for quick switching
  • Arrow keys when focused on session tabs
3

Organize with Canvas View

Click the Canvas button to see all sessions in a grid:
  • Visual overview of all sessions
  • Quick navigation with arrow keys
  • See session status at a glance (active, waiting, completed)
4

Archive Completed Sessions

Right-click a session and select Archive to clean up your workspace.Archived sessions are preserved and can be restored later.

​
Next Steps

Now that you’ve completed your first session, explore more features:

Core Concepts

Understand projects, worktrees, and sessions

Project Management

Learn advanced project organization

Magic Commands

Master AI-powered automation

GitHub Integration

Connect issues, PRs, and workflows

Keyboard Shortcuts

Full keyboard shortcut reference

Customization

Personalize Jean to your workflow

​
Common Workflows

  1. Create worktree from GitHub issue
  2. Use /investigate to understand requirements
  3. Start in Plan mode to design solution
  4. Switch to Build mode to implement
  5. Use Review to check code quality
  6. Generate commit message and commit
  7. Create PR with auto-generated content
  8. Archive worktree when PR is merged
  1. Create worktree from bug report issue
  2. Investigate the bug in Plan mode
  3. Reproduce the issue
  4. Fix in Build mode
  5. Test the fix
  6. Create commit and PR
  7. Link PR to original issue
  1. Create worktree from PR number
  2. Run local tests
  3. Use Review to find issues
  4. Add comments to PR via GitHub
  5. Request changes or approve
  6. Archive worktree after review
  1. Create quick worktree with random name
  2. Start in Yolo mode for rapid iteration
  3. Try different approaches
  4. Delete worktree if experiment fails
  5. Or commit and create PR if successful

​
Tips for Success

Start with Plan Mode: Always begin in Plan mode until you trust Claude’s proposed changes. Review file diffs carefully.
Use Multiple Sessions: Don’t cram everything into one chat. Create focused sessions for:
  • Investigation
  • Implementation
  • Testing
  • Documentation
Context Management: Claude has context limits. Use saved contexts and session recaps to manage long conversations.
Keyboard Shortcuts: Learning the keyboard shortcuts will 10x your productivity. Start with Cmd/Ctrl+K command palette.

​
Getting Help

If you run into issues:
  • Documentation: Browse the guides and reference sections
  • GitHub Issues: github.com/coollabsio/jean/issues
  • Command Palette: Press Cmd/Ctrl+K to search all commands
  • Tooltips: Hover over UI elements for contextual help

Join the Community

Star us on GitHub and contribute to the project

Build docs developers (and LLMs) love

Get started for freeTalk to us