Devops Monk

A Claude Code session is your working context — conversation history, file state, permissions, and memory. Understanding how sessions work and how to manage them unlocks the ability to parallelize work, switch contexts without losing state, and recover from mistakes instantly.

This guide covers session fundamentals, parallel work patterns, and five developer habits that compound over time.

What Is a Session?

A session is:

• Directory-scoped, not branch-scoped — tied to a folder location, not a git branch
• Persistent across context limits — survives /compact and /clear
• Shareable — /rename and /resume to switch between named sessions
• Isolated — each session has its own context window, permissions, memory

Critical distinction: Sessions follow your directory, not your branch. When you git checkout feature-x, the same session continues — Claude reads files from the new branch, but the conversation history stays. This is intentional and useful (you remember context), but it means you need separate sessions for parallel work on different branches.

Session Lifecycle

1. Start
   └─→ claude                          [new session in current directory]
       └─→ claude -c                   [resume last session]
       └─→ claude --resume name        [resume by name]

2. Work
   └─→ Type prompts
   └─→ Claude reads/edits files from current branch
   └─→ Memory is written automatically

3. Pause
   └─→ /rename my-task                [name the session]
   └─→ Cmd+D or exit                   [pause without closing]

4. Resume
   └─→ claude -c                       [same session, full history]
   └─→ claudeSession list              [see all sessions]

5. Cleanup
   └─→ Cmd+D                           [close session]
   └─→ Sessions auto-clean after 7 days of inactivity (configurable)

Directory-Scoped Sessions

Sessions are tied to directories, not branches. This matters:

cd ~/myrepo
git checkout main
claude                    # Session A starts, reads main branch

git checkout feature-x
# Same Session A continues, now reads feature-x branch

git checkout main
# Still Session A, now reads main branch again

Advantage: You remember context across branches Disadvantage: If you’re working on multiple branches simultaneously, you need separate sessions

Git Worktrees: Parallel Sessions

For true parallel work on multiple branches, use git worktrees:

# Terminal 1: Main branch
cd ~/myrepo
claude                    # Session A for main branch

# Terminal 2: Feature branch (in a new worktree)
claude --worktree feature-auth     # Creates worktree + new session B
# New folder created: ~/myrepo/.claude/worktrees/feature-auth
# New branch created: worktree-feature-auth
# Session B opens inside that isolated folder

# Terminal 3: Bug fix branch (another worktree)
claude --worktree bugfix-api       # Creates worktree + new session C

Each worktree has:

• Separate folder — files are independent copies
• Separate branch — changes never conflict
• Separate session — different conversation history and context
• Same git history — all worktrees share the repository’s git log and remotes

Workflow:

Main Branch (Terminal 1)          Feature Branch (Terminal 2)
│                                 │
├─ Session A                       ├─ Session B
│  ├─ Working on refactor         │  ├─ Building OAuth2
│  ├─ Running tests               │  ├─ Testing authentication
│  └─ Writing docs                └─ Opening PR (Session B)
│
└─ Ready to commit                 Ready to review

When you’re done with a worktree:

# Inside the worktree session
exit                          # Closes the session
# Worktree is automatically cleaned up

# Or manually remove
git worktree remove .claude/worktrees/feature-auth

Session Resumption and Forking

Resume: Continue Where You Left Off

# Resume last session
claude -c

# Resume a named session
claude --resume my-task

# List all sessions
claudeSession list

When you resume:

• Full conversation history is restored
• Files are in the state they were when you paused
• Permissions reset (you re-approve them, like security passes expiring)
• Memory loads automatically

Fork: Branch Off Without Losing Original

# Fork current session into a copy
claude --continue --fork-session

This creates a new session with the same conversation history. The original stays untouched. Useful when:

• You want to try a different approach without losing context
• You’re at a decision point and want to explore both paths
• You’re debugging and want to revert to a stable point without losing history

Example:

Original Session A
├─ "Implement OAuth2"
├─ [writes code]
└─ [code review finds issues]
   │
   └─ Fork → Session A' (copy of conversation)
      ├─ "Try a different approach"
      ├─ [rewrites code differently]
      └─ [compare approaches later]

Session Naming

Name sessions immediately when starting meaningful work:

# At the start of a task
/rename oauth-implementation

# Later, resume by name
claude --resume oauth-implementation

Why this matters:

After a month of work, you’ll have 50+ sessions. Without names, finding the right one is impossible. Named sessions appear in:

• claudeSession list — easy to find
• Session sidebar (desktop app) — visual organization
• /resume autocomplete — quick access

Naming convention: feature-name or fix-description or task-type-description

/rename payment-gateway-refactor
/rename fix-auth-race-condition
/rename security-audit-2026-06

Five Developer Habits That Scale

These habits are simple but compound dramatically over months:

Habit 1: Clear Between Tasks

When: After finishing one task, before starting the next Command: /clear Why: Previous conversations pollute new work

# Finished the auth feature
# Context is now filled with auth-related history

/clear

# Now starting the payment feature
# Fresh context, no auth noise

Cost impact: Saves ~100K tokens per task switch. On a 5-task day, that’s 500K tokens saved (roughly 40% of daily cost).

Habit 2: Compact at Breakpoints

When: After finishing a subtask, before starting a new phase Command: /compact keep only: [what matters] Why: Preserves knowledge while freeing context

# Finished phase 1: schema design
# About to start phase 2: implementation

/compact keep only: final schema, API design decisions, performance notes

# Now 30% context used instead of 80%

Best practices:

• Compact before context reaches 80%, not after
• Give Claude guidance on what to preserve
• Run /context first to understand what’s consuming space

Habit 3: Name Your Sessions

When: Immediately after starting work Command: /rename descriptive-name Why: Future you will thank present you

claude                           # Start session
# [do some work]
/rename redis-migration-phase1   # Name it now

After a week:

• Without names: “Which of these 12 unnamed sessions was the Redis work?”
• With names: /resume redis-migration-phase1 (instant access)

Habit 4: Monitor Your Context

When: Periodically during work (every 30 minutes) Command: /context Why: Catch context creep before it blocks you

/context

# Output:
# Conversation history: 42% (300K tokens)
# Files loaded: 25% (180K tokens)
# Tool outputs: 18% (130K tokens)
# ---
# Total: 85% of context window

Actions:

• Below 60%: keep working, plenty of room
• 60-75%: consider compact if you have a pause point
• 75-85%: compact soon, plan next task carefully
• 85%+: compact immediately or start next task fresh

Habit 5: Document and Clear for Big Tasks

When: Task will consume most of context window Pattern: “Document → Clear → Resume” Why: Unlimited context by resetting strategically

# Phase 1: Architecture
[work through architecture design]
/compact keep architecture decisions in a file

# Ask Claude to write progress to a file
"Save our architecture decisions to docs/ARCHITECTURE.md"

/clear

# Phase 2: Implementation
"Read docs/ARCHITECTURE.md and implement based on this design"
[fresh context, full knowledge]

/clear

# Phase 3: Testing
"Read docs/ARCHITECTURE.md and write comprehensive tests"
[another fresh context, full knowledge]

Result: You never run out of context for large projects, and knowledge persists via git-committed documentation.

Parallel Workflows

Pattern 1: Developer + Reviewer

Terminal 1 (Writer):

cd ~/myrepo
claude --worktree feature-auth
# Implement OAuth2 authentication

Terminal 2 (Reviewer):

cd ~/myrepo
claude --worktree review-session
# In parallel, review code from feature-auth branch
# Use: "Review @../myrepo/.claude/worktrees/feature-auth/src/auth.ts"

Both work simultaneously:

• Writer implements, runs tests, iterates
• Reviewer provides feedback as code is written
• No context pollution (separate sessions)
• No merge conflicts (separate branches)

Pattern 2: Multiple Features in Parallel

# Terminal 1: OAuth Feature
claude --worktree oauth-feature
# [working on auth]

# Terminal 2: Payment Feature
claude --worktree payment-feature
# [working on payments]

# Terminal 3: DevOps Task
claude --worktree infra-update
# [working on infrastructure]

Three engineers (or one person’s three sessions) working in parallel on different features. Commits never conflict because they’re on different branches.

Pattern 3: Bug Fix While Continuing Main Work

# Main development
cd ~/myrepo
claude

# Bug reported
# Without closing main session:
claude --worktree bugfix-issue-234

# [fix the bug, commit, PR]
# Main session still running, unaffected

Session State and Permissions

Each session maintains state:

Important: When you resume with claude -c, permissions reset. This is intentional — like security passes expiring when you leave the building. You’ll see permission prompts again on first tool use.

Session Storage and Cleanup

Sessions are stored in:

~/.claude/sessions/
├── <directory-hash>/
│   ├── current.jsonl        # Latest session conversation
│   ├── history/
│   │   └── <session-id>.jsonl
│   └── metadata.json

Auto-cleanup:

• Sessions older than 7 days of inactivity are deleted
• Configure with: sessionRetentionDays in .claude/settings.json

{
  "sessionRetentionDays": 30   # keep inactive sessions for 30 days
}

Tips Most Engineers Miss

1. Use /rename immediately

claude
/rename current-task
# Now it's findable later

2. Monitor context in real-time

Add status line to your shell prompt showing context percentage. When it climbs past 70%, you know it’s time to compact.

/statusline

3. Use --add-dir for monorepos

claude --add-dir ../frontend ../shared-lib

# Now Claude can read/edit in all three folders
# Single session, multiple working areas

4. Worktrees for parallel work

Never do serial refactoring when you could do parallel work:

# Serial (slow): finish feature-a, then start feature-b
# Parallel (fast): start both in worktrees simultaneously
claude --worktree feature-a &
claude --worktree feature-b &

5. The session recovery pattern

Lost context mid-task?

# Don't: manually re-type context
# Do: resume the session
claude -c

6. /compact beats /clear

# Don't: /clear (lose all context)
# Do: /compact keep only: X

Compacting preserves what matters while freeing space.

7. Checkpoints are your safety net

/rewind
# See all checkpoints, restore code-only, conversation-only, or both

Checkpoints are free (just git internally). Use them without guilt.

Session Patterns for Teams

Pattern: Shared Session Log

For pair programming or async collaboration:

# Session started at 10am
/rename feature-oauth-[date]

# Throughout the day, both team members:
claude --resume feature-oauth-[date]

# Same conversation history, same code changes
# Like pair programming across time zones

Pattern: Session Handoff

Engineer A starts work, Engineer B continues:

# Engineer A
/rename fixing-db-query
[works for 2 hours]
/rename fixing-db-query-[assigned-to-B]
exit

# Engineer B
claude --resume fixing-db-query-[assigned-to-B]
# Full context! Reads the entire conversation, understands decisions

Common Mistakes

1. Not using worktrees for parallel work

Branches solve version control, but sessions are separate. Use worktrees for true parallelization.

2. Letting context fill to 100%

Monitor context. Compact at 75%. Never let it max out.

3. Forgetting to name sessions

Name sessions immediately. Unnamed sessions are unsearchable.

4. Clearing instead of compacting

/compact preserves knowledge. /clear deletes it. Choose wisely.

5. Long sessions without checkpoints

Checkpoints are free. Use them. Rewind instantly if something breaks.

Advanced: Custom Session Configuration

Per-session settings in .claude/settings.json:

{
  "sessionDefaults": {
    "autoMemoryEnabled": true,
    "defaultModel": "claude-sonnet-4-6",
    "permissionMode": "acceptEdits"
  },
  "sessionRetentionDays": 30
}

Session management is the foundation of productive Claude Code work. Master these five habits and you’ll never lose context, never conflict on branches, and never struggle to find your previous work.