AgileFlow

/session:new

PreviousNext

Create a parallel session with git worktree for multi-session work

/session:new

Create a new parallel Claude Code session with automatic git worktree setup. This allows you to work on multiple tasks simultaneously without conflicts.

Quick Start

/agileflow:session:new

How It Works

When you run this command, you'll be presented with options:

  1. Auto-create Session N - Automatically creates a numbered session (e.g., Session 2, Session 3)
  2. Name this session - Give a nickname like "auth" or "refactor"
  3. Use existing branch - Attach to a branch you already have

The command then:

  1. Creates a new git worktree in a parallel directory
  2. Registers the session in the session registry
  3. Shows you the cd command to switch to the new workspace

Example Output

Creating Session 2...

✓ Session created successfully

  Session ID: 2
  Path: /home/user/myproject-2
  Branch: session-2

To start working in this session:
  cd /home/user/myproject-2 && claude

Parameters

This command uses interactive prompts (AskUserQuestion) instead of command-line parameters.

OptionDescription
Auto-createUses next available session ID
Named sessionCreates with custom nickname (e.g., "auth" → /home/user/myproject-auth)
Existing branchAttaches to a branch without creating a new one

Why Use Parallel Sessions?

The Problem

Running multiple Claude Code instances in the same directory causes:

  • File locking conflicts (especially on macOS)
  • Risk of conflicting edits to the same files
  • Shared ~/.claude/ directory issues
  • No visibility into what other sessions are working on

The Solution

Git worktrees provide:

  • Isolated directories - Each session has its own folder
  • Shared .git - Disk efficient, no duplicate repo
  • Independent branches - No merge conflicts during work
  • Clean separation - Sessions can't step on each other

Workflow

Starting a Second Task

# In your main project
/agileflow:session:new
# Pick "Auto-create Session 2"
 
# Claude shows:
#   cd /home/user/myproject-2 && claude
 
# Open new terminal
cd /home/user/myproject-2
claude

Naming Sessions by Feature

# Create session for auth work
/agileflow:session:new
# Pick "Name this session" → "auth"
 
# Creates: /home/user/myproject-auth on branch session-auth

Using Existing Branch

# You have a feature branch already
git branch
# feature/new-api
# main
 
/agileflow:session:new
# Pick "Use existing branch" → "feature/new-api"
 
# Creates worktree attached to that branch

Session Registry

Sessions are tracked in .agileflow/sessions/registry.json:

{
  "sessions": {
    "1": {
      "path": "/home/user/myproject",
      "branch": "main",
      "is_main": true
    },
    "2": {
      "path": "/home/user/myproject-2",
      "branch": "session-2",
      "nickname": null
    }
  }
}

Best Practices

  • One task per session - Keep sessions focused
  • Use nicknames for long-running work - Easier to remember than numbers
  • End sessions when done - Use /session:end to clean up
  • Check status before starting - Use /session:status to see what's running

Related Commands