Skip to main content

​
Overview

Sessions in Jean are individual AI chat conversations within a worktree. Each worktree can have multiple sessions, letting you organize work by task, context, or experiment. Key concepts:
  • Sessions are isolated conversations with their own message history
  • Each session has its own model, provider, and settings
  • Sessions can be labeled, archived, and restored
  • The canvas view shows all sessions in a worktree at once

​
Creating Sessions

1

New Session in Current Worktree

Press Cmd+T (Mac) or Ctrl+T (Windows/Linux) to create a new session in the active worktree.Alternatively, click the ”+” button in the chat toolbar.
2

Choose Model and Settings

A new session starts with:
  • The default model for the project (or global default)
  • No message history
  • A random generated name (if auto-naming is enabled)
You can change the model/backend at any time using the dropdowns in the toolbar.
3

Start Chatting

Type your first message in the chat input. If auto-naming is enabled, Jean will:
  • Send your message to a lightweight model (Haiku)
  • Generate a descriptive 4-5 word name
  • Update the session name in the sidebar
Disable auto-naming in Preferences → General if you prefer to name sessions manually.

​
Session Execution Modes

Jean has three execution modes that control how Claude operates:

​
Plan Mode (Default)

Claude first creates a plan before executing. This is the safest mode for complex tasks. How it works:
  1. You ask Claude to do something
  2. Claude responds with a plan (list of steps)
  3. You review and approve the plan (Cmd+Enter)
  4. Claude executes the approved plan
When to use:
  • Complex features requiring architectural decisions
  • Tasks involving multiple files or systems
  • When you want visibility into Claude’s approach before changes are made

​
Build Mode

Claude executes immediately without planning. Faster but less predictable. When to use:
  • Simple, well-defined tasks
  • Following up on previous work
  • Quick fixes or iterations
Keyboard shortcut:
  • Approve plan and switch to Build: Cmd+Shift+Enter

​
Yolo Mode

Claude executes immediately with minimal safeguards. Fastest but least controlled. When to use:
  • Prototyping and experiments
  • When speed matters more than safety
  • Iterating rapidly on small changes
Keyboard shortcuts:
  • Approve plan and switch to Yolo: Cmd+Y
  • Approve plan, clear context, and start new Yolo session: Cmd+Shift+Y

​
Switching Modes

Press Shift+Tab to cycle through Plan → Build → Yolo → Plan. The current mode is shown in the chat toolbar.

​
Organizing Sessions

1

Rename Sessions

Click the session name in the sidebar and type a new name. Good names describe the task:
  • “Add user authentication”
  • “Fix login bug #245”
  • “Refactor API client”
  • “Investigate performance issue”
2

Label Sessions

Press Cmd+S to toggle the “Needs Testing” label on the current session. Labeled sessions show a colored badge in the sidebar.
Currently, only one label (“Needs Testing”) is supported. More labels may be added in the future.
3

Reorder Sessions

Drag and drop sessions in the sidebar to reorder them. The order is saved per-worktree.
4

Use Canvas View

Press / (forward slash) to open the canvas view, which shows all sessions as cards in a grid.Canvas view lets you:
  • See session status at a glance (waiting, reviewing, complete)
  • Navigate with arrow keys
  • Open plans and recaps quickly (press P or R on a selected card)

​
Session Plans and Recaps

Jean generates summaries to help you understand session state without reading full transcripts.

​
Plans

When Claude creates a plan (in Plan mode), you can view it later:
1

View Plan

Press P with a session selected (in canvas view), or click the plan icon in the chat toolbar.
2

Review Steps

The plan shows:
  • Numbered list of steps
  • Current progress (which steps are complete)
  • Any unresolved questions or blockers
3

Approve or Modify

From the plan dialog, you can:
  • Approve the plan (Cmd+Enter)
  • Go back to chat and ask for changes
  • Switch execution mode before approving

​
Recaps

Recaps are AI-generated summaries of what happened in a session.
1

Enable Recaps

Open Preferences → Experimental Features and enable Session Recaps.
2

Generate Recap

Press R with a session selected (in canvas view), or click Create Recap in the Magic Modal (Cmd+M).Jean will send the conversation history to a model (Haiku by default) and generate:
  • Chat Summary: One-sentence overview of the goal and status
  • Last Action: What was just completed in the last exchange
3

View Recap

Recaps are shown:
  • In the session card on canvas view (below the session name)
  • In a dialog when you press R on a session
Recaps help you quickly remember what a session was about without reading the full transcript.

​
Archiving and Restoring Sessions

1

Close a Session

Press Cmd+W to close the current session.Depending on your Session Removal Behavior setting (Preferences → General):
  • Archive: Session is hidden but can be restored later
  • Delete: Session is permanently deleted
2

Restore Last Archived

Press Cmd+Shift+T to restore the most recently archived session.This works across all worktrees in the current project.
3

View All Archived Sessions

Right-click a worktree in the sidebar → View Archived.You’ll see a list of all archived sessions with timestamps. Click one to restore it.
4

Permanently Delete Archived Sessions

Archived sessions are automatically deleted after a retention period (default: 7 days).Change the retention period in Preferences → General → Archive Retention Days.Set to 0 to keep archived sessions forever.

​
Session Context Management

As sessions grow longer, token usage increases and performance may degrade. Jean provides tools to manage context.
1

Check Token Usage

The chat toolbar shows the current token count for the session. Large sessions (>100K tokens) may be slower and more expensive.
2

Save Context

When you reach a good stopping point, press Cmd+M → Save Context.Jean will:
  1. Send the conversation history to Opus (by default)
  2. Generate a structured summary with:
    • Main goal and key decisions
    • Problems solved and trade-offs considered
    • Current state and next steps
    • Important file paths and patterns
  3. Save the summary to .ai/summaries/<slug>.md
  4. Show a toast notification with a link to the saved file
3

Clear Context and Continue

Press Cmd+Shift+Enter (from a plan approval) to:
  • Approve the current plan
  • Clear the session context
  • Start a fresh Build session
Or press Cmd+Shift+Y to do the same but start a Yolo session.
Clearing context removes all messages from the session. Make sure you’ve saved important context first.
4

Load Context

Press Cmd+M → Load Context to load saved summaries into a new session.You can select multiple summaries to combine context from different sessions.

​
Finished Sessions

Jean tracks when sessions are “finished” (waiting for your input) and notifies you.
1

Enable Notifications

In Preferences → General → Notification Sounds, choose a sound for:
  • Waiting Sound: Plays when a session finishes and is waiting for input
  • Review Sound: Plays when a session finishes reviewing code
2

View Finished Sessions

Press Cmd+Shift+F to open the Finished Sessions popover.This shows all sessions across all worktrees that are waiting for your input.
3

Jump to Session

Click a session in the Finished Sessions list to jump directly to it.The popover closes automatically and the session opens in the chat view.

​
Common Pitfalls

Lost Context After Switching Sessions: When you switch sessions, the previous session’s context is NOT loaded into the new session. Each session is isolated.Solution: If you need to continue work from a previous session, either keep working in the same session or use Save Context → Load Context to transfer summaries.
Session Names Too Generic: Auto-generated names sometimes miss the mark. If a session is named “Code changes” or “Bug investigation”, rename it to be more specific.Solution: Rename sessions immediately after creation so you remember what they’re for.
Clearing Context Too Early: If you clear context before Claude finishes a multi-step task, you’ll lose important context and Claude may repeat work or make mistakes.Solution: Only clear context at natural stopping points (feature complete, bug fixed, tests passing).

​
Best Practices

One Session per Task: Create separate sessions for different tasks (even within the same worktree). This keeps context focused and token counts low.
Use Plan Mode for New Work: Start complex tasks in Plan mode. You can switch to Build or Yolo later once the approach is clear.
Save Context Regularly: After completing a major milestone, save context. This creates checkpoints you can return to later.
Archive Completed Sessions: Once a session’s work is merged and deployed, archive it. This keeps your sidebar clean and focused on active work.
Label Work-In-Progress: Use the “Needs Testing” label to mark sessions that have changes waiting for manual testing or review.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us