Skip to main content

​
Overview

Projects in Jean are git repositories that you work on. Each project can have multiple worktrees (isolated branches) and customizable settings. This guide walks through adding projects and configuring them for optimal workflow.

​
Adding Your First Project

1

Open the Projects Sidebar

Press Cmd+B (Mac) or Ctrl+B (Windows/Linux) to toggle the left sidebar if it’s hidden.
2

Add a New Project

Click the ”+” button at the top of the sidebar. You’ll see the “Add Project” dialog.
3

Select Your Repository

Click Browse to navigate to your git repository’s root directory. Jean will automatically detect:
  • Project name (from directory name)
  • Default branch (e.g., main or master)
  • Remote URL (for GitHub integration)
4

Review Settings

Before clicking Add Project, verify:
  • The project name is correct (you can rename it later)
  • The default branch matches your main branch
  • The path points to the correct repository
5

Add the Project

Click Add Project. The project appears in your sidebar and you can now create worktrees.

​
Configuring Project Settings

Each project has its own settings that override global defaults.
1

Open Project Settings

Right-click the project in the sidebar and select Settings, or click the project name to focus it, then press Cmd+,.
2

General Settings

In the General tab, you can configure:Project Name: Display name shown in the sidebarDefault Branch: Branch used as the base for new worktrees (usually main or master)Worktrees Location: Custom directory for storing worktrees. By default, worktrees are created in ~/jean/<project-name>/. You can set a custom location like:
  • /Users/you/dev/workspaces for a centralized location
  • Same directory as your repository for keeping everything together
Changing the worktrees location does NOT move existing worktrees. It only affects new worktrees.
Project Avatar: Upload a custom icon to personalize your project (PNG, JPG, or SVG)
3

Backend & Model Settings

Configure which AI backend and model to use for this project:Backend: Choose between Claude, Codex, or OpenCode
  • Claude: Anthropic’s models (Opus, Sonnet, Haiku)
  • Codex: OpenAI’s GPT models optimized for coding
  • OpenCode: Custom model configurations
Provider: Select API provider (Anthropic, OpenRouter, custom)Default Model: Set the model used for new sessions in this project
Leave these blank to use your global defaults from Preferences.
4

Custom System Prompt

Add a custom system prompt that gets appended to every chat session in this project. This is useful for:
  • Project-specific coding standards
  • Architecture guidelines
  • Tech stack reminders
Example:
This project uses React 19 with TypeScript. Always use functional components
with hooks. Follow the existing patterns in src/components/. Use Tailwind
for styling. Run tests with `bun test` before committing.

​
Setting Up MCP Servers

MCP (Model Context Protocol) servers provide additional tools and context to Claude. Common servers include:
  • filesystem: Access to read/write files
  • brave-search: Web search capabilities
  • github: GitHub API integration
  • postgres: Database queries
1

Install MCP Servers

MCP servers are configured in ~/.claude.json (for Claude backend). Example configuration:
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-api-key"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
      }
    }
  }
}
2

Enable Servers Globally

Open Preferences (Cmd+,) → MCP Servers tab. You’ll see all configured servers.Toggle the switches to enable servers globally (they’ll be available in all projects by default).
3

Enable Servers Per-Project

For finer control, disable global defaults and enable servers per-project:
  1. Open project settings (right-click project → Settings)
  2. Go to the MCP Servers tab
  3. Enable only the servers needed for this project
Enable github only for projects with GitHub remotes. Enable postgres only for backend projects.
4

Test MCP Servers

In Preferences → MCP Servers, click Check Health to verify all servers are running correctly.Healthy servers show a green checkmark. Failed servers show error details.

​
Jean.json Setup Script

The jean.json file in your repository root defines setup commands that run when creating new worktrees.
1

Create jean.json

In your repository root, create a jean.json file:
{
  "scripts": {
    "setup": "bun install && bun run build",
    "run": "bun run dev"
  }
}
  • setup: Runs when creating a new worktree (install dependencies, build, etc.)
  • run: Triggered by Cmd+R in Jean (start dev server, run tests, etc.)
2

Test the Setup Script

Create a new worktree (Cmd+N). Jean will:
  1. Create the git worktree
  2. Run the setup script automatically
  3. Show script output in the worktree’s logs
If the setup fails, you’ll see error details and can debug the issue.
3

Advanced Setup Scripts

You can use multi-line scripts or shell commands:
{
  "scripts": {
    "setup": "npm install && npm run build && cp .env.example .env",
    "run": "docker-compose up -d && npm run dev"
  }
}

​
Organizing Projects with Folders

1

Create a Folder

Click the ”+” button and select New Folder. Name it (e.g., “Work”, “Personal”, “Open Source”).
2

Move Projects into Folders

Drag and drop projects onto folders in the sidebar to organize them.
3

Reorder Projects

Drag projects up and down to reorder them within folders or at the root level.

​
Common Pitfalls

Not a Git Repository: Jean requires projects to be git repositories. If you select a non-git folder, the “Add Project” button will be disabled.Solution: Run git init in the directory first, or select a different folder.
Wrong Default Branch: If Jean detects the wrong default branch (e.g., master when you use main), manually correct it in project settings.Why it matters: New worktrees are created from the default branch. If it’s wrong, your worktrees will be out of date.
MCP Servers Not Starting: If MCP servers show as unhealthy:
  • Check that Node.js/npm/npx is installed
  • Verify API keys in ~/.claude.json
  • Look at error messages in the health check results
  • Try running the server command manually in a terminal

​
Best Practices

Use Folders for Context Switching: Organize projects by client, company, or type (personal, work, experiments). This makes it faster to find projects.
Set Per-Project Models: Use faster, cheaper models (Haiku) for experimental projects. Use premium models (Opus) for production work.
Custom Worktrees Location: If you’re working on a shared filesystem or network drive, set a custom worktrees location to avoid performance issues.
Keep Setup Scripts Fast: Long setup scripts delay worktree creation. Move heavy operations (like full rebuilds) to the run script instead.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us