# Session Management — Cheat Sheet

Daily reference for managing Claude Code sessions effectively.

## Starting a Session

| Situation | Command | Notes |
|---|---|---|
| New task | `claude` | Global rules auto-load |
| Continue last session | `claude --continue` or `claude -c` | Restores full history |
| Resume named session | `claude --resume "name"` or `claude -r "name"` | Pick up by name or ID |
| Interactive resume | `/resume` (inside Claude) | Shows session picker |
| Fork (try alternative) | `claude -c --fork-session` | Branches off, original preserved |
| Use the launcher | `claude-code ~/projects/my-app` | Uses `cmux` on macOS, `tmux` elsewhere |
| Sync project to latest template | `claude-code sync [path] [--dry-run]` | Updates commands and `.claude/` files from template |

You do **not** need to run `/init` every time. `/init` is a one-time command to scaffold a project-level CLAUDE.md for a new repo. Global rules already cover everything generic.

## During a Long Session

| Action | Command | When |
|---|---|---|
| Check context usage | `/context` | Periodically — shows visual grid |
| Compress history | `/compact` or `/compact focus on X` | When context is getting heavy |
| Check token spend | `/cost` | Monitor session spend |
| Name your session | `/rename "descriptive-name"` | Before switching tasks or ending |
| View loaded memory | `/memory` | Review/edit what Claude has loaded |
| Rewind a mistake | `Esc + Esc` or `/rewind` | Undo file changes or roll back |

### Checkpointing & Rewind

Claude Code automatically checkpoints conversation state and file edits made through Claude's file-editing tools (Edit, Write, etc.). You can rewind to any of those points without leaving the session.

| Action | How |
|---|---|
| Open the rewind menu | Double-tap `Escape`, or run `/rewind` |
| Restore conversation only | Pick a message in the rewind menu, choose "conversation" |
| Restore code only | Pick a message, choose "code" |
| Restore both | Pick a message, choose "both" |
| Summarize forward from here | Pick a message, choose "summarize" — keeps the prefix, replaces the rest with a summary |

**Persistence:** Checkpoints survive across sessions. Close the terminal, come back tomorrow, run `/rewind` — the menu still has the snapshots.

**Scope — what rewind tracks:**

- File edits made through Claude's file-editing tools (Edit, Write, NotebookEdit).
- Conversation state.

**Scope — what rewind does NOT track (do not rely on it for these):**

- **Files modified by bash commands run through Claude.** This includes anything written via `cat >`, `sed -i`, `mv`, `rm`, code formatters invoked from Bash, build steps, generated files, etc. If Claude ran it from a shell, rewind will not undo it.
- Files modified by editors, formatters, or build tools running outside Claude.
- Git operations (commits, branch switches, stashes).
- External process side effects (database writes, deployed artifacts, network calls).

Because bash-side file changes are out of scope, treat rewind as a fast undo for **Claude's own edit-tool changes** — **not** a general-purpose safety net for everything that happened in the session. Commit at meaningful boundaries; rely on git, not rewind, for anything you can't afford to lose.

## Switching Tasks in Same Terminal

```
/rename "previous-work-name"     ← name what you were doing
/clear                           ← fresh context, global rules reload
(start new task)                 ← clean slate
```

## Ending a Session

```
"save memory about X"            ← tell Claude to remember key decisions
/rename "descriptive-name"       ← name it for later resumption
```

## What's Automatic

| What | Stored where | Automatic? |
|---|---|---|
| Conversation history | Internal session storage | Yes — resume with `--continue` |
| File edit checkpoints | Internal | Yes — rewind with `Esc+Esc` |
| Auto-memory (patterns) | `~/.claude/projects/<project>/memory/` | Yes (if enabled) |
| Global rules loading | `~/.claude/CLAUDE.md` + `~/.claude/rules/` | Yes — every session |

## What's NOT Automatic

- **Project session log** (`doc_internal/HISTORY.md`): Add to your project CLAUDE.md if you want it.
- **Explicit memory requests**: Say `"remember that we use pnpm"` to save to auto-memory.
- **Plan mode locality**: Claude Code's `/plan` mode writes a system file to `~/.claude/plans/` — ephemeral and invisible to new sessions or other copilot tools. **Write plan artifacts to the project directory FIRST, during plan creation:** `specs/<feature-id>/plan.md` for SDD feature work, or `doc_internal/plans/` for ad-hoc plans. Do not wait until plan mode exits. The `~/.claude/plans/` file is not the authoritative plan — the project-local file is.
- **Spec artifact handoff**: The Plan agent writes `specs/<id>/plan.md` during planning (and `spec.md` when `spec_mode` is `full` or `lightweight`). Ensure they are committed so the Build agent can read them. Include `specs/lessons-learned.md` in handoff if it was updated.

## Parallel Development with Git Worktrees

Git worktrees let you work on multiple branches simultaneously without stashing or switching. Each worktree is a separate checkout sharing the same `.git` directory.

### When to Use

- Running a long build/test on one branch while coding on another
- Comparing behaviour between branches side-by-side
- Keeping a stable branch checked out while experimenting

### Quick Reference

| Action | Command |
|---|---|
| Create worktree | `git worktree add ../feature-branch feature-branch` |
| List worktrees | `git worktree list` |
| Remove worktree | `git worktree remove ../feature-branch` |
| Prune stale entries | `git worktree prune` |

### Workflow with `claude-code` Launcher

```bash
# Create a worktree for a feature branch
git worktree add ../my-feature feature/my-feature

# Start a Claude session in the worktree
claude-code ../my-feature

# When done, clean up
git worktree remove ../my-feature
```

### Tips

- Worktrees share the object store — no extra clone needed, very fast to create.
- Each worktree has its own index/staging area, so you can stage independently.
- Avoid having the same branch checked out in two worktrees (Git prevents this by default).
- Use `git worktree prune` periodically to clean up entries for deleted directories.

## All Slash Commands

| Command | Purpose |
|---|---|
| `/init` | One-time: scaffold project CLAUDE.md |
| `/memory` | View/edit loaded memory files |
| `/compact [focus]` | Compress context with optional focus |
| `/context` | Visual context usage grid |
| `/cost` | Token usage for this session |
| `/clear` | Wipe conversation, keep session |
| `/rename "name"` | Name session for later resume |
| `/resume [name]` | Resume a previous session |
| `/rewind` | Undo file changes or conversation |
| `/config` | Open settings UI |
| `/status` | Version, model, account info |
| `/doctor` | Health check on install |
| `/model` | Switch AI model |
| `/mcp` | Manage MCP server connections |
| `/export [file]` | Export conversation to file or clipboard |
| `/plan` | Enter plan mode (or `Shift+Tab` twice) |
| `/stats` | Daily usage and session history |
