Task State Checkpoint

Core Concepts / How It Works

Information Stored in a Checkpoint

A checkpoint is not just a "note" — it structurally stores all the context needed to resume work.

Checkpoint snapshot structure:
  ├─ Git State
  │   ├─ Current branch name
  │   ├─ Latest commit hash + message
  │   ├─ List of staged/modified files
  │   └─ Whether there is a stash
  ├─ List of decisions made
  │   ├─ "Notice list uses SSR (reason: realtime not needed)"
  │   └─ "Image upload excluded from MVP"
  ├─ Remaining task list (checkboxes)
  │   ├─ [ ] Notice creation form validation
  │   ├─ [ ] Officer permission middleware
  │   └─ [ ] Pagination implementation
  └─ Current blocker / next first action

When to Use

• Just before ending a session, when you want to record where to start next time
• When you need to switch context to another task mid-work (urgent bugfix, meeting, etc.)
• When you want to save today's progress during a multi-day task
• When you open a new session and want to quickly recall "where was I?"
• When handing off work between Conductor workspaces or branches

Save vs Resume

# Save
> checkpoint  # or
> save progress  # or
> Let's stop here today, save checkpoint.

# Resume
> where was I  # or
> resume  # or
> what was I working on

Storage Location

Checkpoints are saved in a memory file (MEMORY.md or a dedicated checkpoint.md) and persist even after the session is fully closed. In this project, they are saved under C:\Users\kik32\.claude\projects\...\memory\.

One-Line Summary

This work state management skill saves a snapshot of the current Git state, decisions made, and remaining task list so that even if a session is interrupted or context switches, you can resume from exactly where you stopped.

Getting Started

/checkpoint

SKILL.md file location: ~/.claude/skills/checkpoint/SKILL.md

Copy and modify the SKILL.md content if customization is needed.

Practical Example

Situation: You were implementing an officer permission middleware in a "Student Club Notice Board" project based on Next.js 15 + TypeScript when a class notification went off. You want to record exactly where to resume when you return in 2 hours.

Saving a Checkpoint

> I need to go to class now. Save a checkpoint.
# or
> checkpoint — save progress

Example checkpoint generated by Claude:

## Checkpoint — 2026-04-12 14:30 KST

### Git State
- Branch: feat/auth-middleware
- Latest commit: a3f91c2 "feat: scaffold basic auth middleware"
- Files in progress:
  - middleware.ts (incomplete — officer role check logic at 50%)
  - app/notices/new/page.tsx (permission guard not yet connected)

### Finalized Decisions
- Auth method: Supabase Auth + custom session cookie (not next-auth)
- Role model: 'member' | 'officer' | 'admin' (enum confirmed)
- Middleware location: root middleware.ts (using matcher pattern)

### Remaining Tasks
- [ ] middleware.ts: Complete officer/admin role check logic
- [ ] app/notices/new/page.tsx: Connect middleware and handle redirect
- [ ] Run Supabase profiles table role column migration
- [ ] Role change API endpoint (for admin use)

### Next First Action
Open middleware.ts and resume at line 51 where the TODO comment is.
Complete the function that queries the profiles table using `auth.uid()` and returns the role.

Resuming a Checkpoint

# After returning from class 2 hours later
> Where was I? Resume from checkpoint.
# or
> resume

Claude's response:

Last checkpoint (2026-04-12 14:30 KST) summary:

Branch: feat/auth-middleware
File in progress: middleware.ts (stopped at line 51)

Next first action:
middleware.ts line 51 → Complete role lookup function using auth.uid()

Remaining tasks (4):
  [ ] middleware.ts role check logic
  [ ] app/notices/new/page.tsx permission guard
  [ ] Supabase role column migration
  [ ] Admin role change API

Shall I open middleware.ts now?

Context for the incomplete file:

// middleware.ts — location where checkpoint resumes
import { createMiddlewareClient } from '@supabase/auth-helpers-nextjs'
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export async function middleware(req: NextRequest) {
  const res = NextResponse.next()
  const supabase = createMiddlewareClient({ req, res })

  const { data: { user } } = await supabase.auth.getUser()

  if (!user) {
    return NextResponse.redirect(new URL('/login', req.url))
  }

  // TODO: Resume here — query profiles table for role, then check officer/admin
  // const { data: profile } = await supabase
  //   .from('profiles')
  //   .select('role')
  //   .eq('id', user.id)
  //   .single()
  // ...
}

Learning Points / Common Pitfalls

• The trap of "I'll remember it": When you come back 2 hours later or the next morning, you spend more time than expected trying to recall "where was I, why did I make that decision." Checkpoints reduce this recall time to nearly zero.
• Save the reason for decisions too: The key is not just "what was done" but also "why that decision was made." Losing the reasoning leads to re-examining the same issue later.
• Make it a routine before ending sessions: If you develop the habit of running checkpoint as the last command when finishing work, it naturally integrates with the learning records from the Learn skill.
• Common mistake: Ending the session without saving a checkpoint. In case the session is unexpectedly interrupted, save intermediate checkpoints during long work sessions.
• Next.js 15 perspective tip: If you have changes temporarily saved with git stash during feature branch work, it is good to also record the stash list in the checkpoint.

Related Resources

• using-git-worktrees — Independent work environments per branch (use with checkpoint)
• dispatching-parallel-agents — Parallel agent task state management
• subagent-driven-development — Sub-agent based development

---

Field	Value
Original URL	https://docs.anthropic.com/en/docs/claude-code/skills
Author/Source	Anthropic
License	Commentary MIT, original reference only
Translation Date	2026-04-13