Claude Code Compaction: Plan Mode and To-Do List Persistence Strategy

Research Date: 2026-01-20
Source URL: https://x.com/nummanali/status/2010042788566720955
Category: software/ai-ml/agentic-coding

Reference URLs

• Numman Ali Tweet - Compaction Solution
• Claude Code Auto-Compact Documentation
• Claude Code Auto-Compact Buffer
• Claude Code Plan Mode
• Auto Plan Mode
• Context Recovery Hooks
• Automatic Context Compaction - Anthropic Cookbook

Summary

A workflow pattern shared by Numman Ali on January 11, 2026, demonstrates a practical approach to mitigating Claude Code’s context compaction issues. The technique involves initiating sessions in Plan Mode and explicitly requesting a comprehensive To-Do list at the outset. According to the report, plans and To-Do items persist across compaction events, enabling extended autonomous coding sessions without loss of task context. The example case achieved a 52-minute 54-second runtime producing a multi-module agent-orchestrator project. This approach addresses a common pain point in agentic coding workflows where context summarization can cause loss of instructions, architectural decisions, and work progress.

Context Compaction Mechanisms

Auto-Compaction

Auto-compaction is Claude Code’s mechanism for managing context window limits. When conversation history approaches the token ceiling, the system automatically summarizes older, less relevant messages into a condensed representation, preserving the ability to continue the session without hard truncation.

Auto-Compact Buffer

A reserved portion of the context window dedicated to compaction operations. This buffer ensures sufficient space for summarization to occur before hitting hard limits. The buffer size is typically not user-adjustable—it operates as either enabled or disabled.

Micro-Compact

A lighter compaction variant that selectively removes older tool calls or irrelevant context while preserving recent messages. Unlike full compaction, micro-compact avoids complete summarization, extending session length with less information loss.

Known Compaction Issues

The Plan Mode Persistence Strategy

Core Technique

The workflow pattern reported by Numman Ali consists of three elements:

1. Start in Plan Mode: Begin the session using Plan Mode rather than immediately executing code changes
2. Request Comprehensive To-Do List: Explicitly instruct the model to create a detailed task list before implementation
3. Leverage Persistence: Plans and To-Do items survive compaction events as structured data

Why This Works

Plan Mode creates structured, named artifacts (plans, task lists) that the compaction algorithm treats as higher-priority context. Unlike freeform conversation, structured task lists have clear boundaries and explicit state (pending, in progress, completed), making them more likely to be preserved during summarization.

Complementary Persistence Mechanisms

Demonstrated Project: Agent Orchestrator

The tweet’s attached image shows output from an agent-orchestrator project built during the 52-minute session. The project architecture demonstrates the complexity achievable with proper compaction management.

Module Architecture

CLI Usage Pattern

# Enhanced mode (all features enabled)
npx tsx packages/agent-orchestrator/src/cli.ts \
  --task-id "task-123" \
  --flow-type "feature" \
  --instruction "Implement the feature" \
  --enhanced

# Individual options
--persist-state    # Save state to BD notes
--save-artifacts   # Store outputs to .agent/
--create-pr        # Create PR on completion

System Design

The architecture implements several patterns relevant to long-running agent sessions:

• State Persistence: BDStateManager enables saving session state externally, allowing recovery after compaction or session restart
• Artifact Storage: Outputs preserved to .agent/ directory, decoupling results from conversation context
• Git Integration: ReadonlyGuard with fingerprinting provides safety mechanisms for autonomous git operations

Best Practices for Compaction Resilience

Workflow Recommendations

1. Initialize with Plan Mode: Start complex tasks by requesting a detailed plan and task breakdown before any implementation
2. Maintain External Task Files: Keep TODO.md or similar files updated by the agent, with completed items marked
3. Use Work Cycle Boundaries: Manually trigger /compact at natural breakpoints (feature completion, module boundaries)
4. Configure Recovery Hooks: Set up pre-compaction and session-start hooks to backup and reload critical context

CLAUDE.md Structure for Persistence

## Project Goals
[High-level objectives that should survive compaction]

## Current Sprint Tasks
- [ ] Task 1 - Description
- [ ] Task 2 - Description
- [x] Task 3 - Completed

## Architectural Decisions
[Key decisions that must persist across sessions]

## Constraints
[Rules the agent must always follow]

Configuration Options

Engagement Metrics

The original tweet achieved significant engagement, suggesting community resonance with the compaction challenge:

The high bookmark-to-like ratio (0.78) indicates users saving the technique for future reference, characteristic of practical tips rather than entertainment content.

Key Findings

• Plan Mode combined with explicit To-Do list creation provides a practical mitigation for compaction-related context loss
• Structured artifacts (plans, task lists with states) have higher preservation priority during compaction than freeform conversation
• The technique enabled a 52-minute autonomous coding session producing a multi-module project
• Complementary mechanisms (CLAUDE.md, external task files, hooks) further reinforce persistence
• The agent-orchestrator project demonstrates state persistence patterns applicable to other long-running agent workflows
• Community engagement metrics suggest compaction management is a widespread pain point among Claude Code users

References

1. Numman Ali (@nummanali) - Twitter/X Post - January 11, 2026
2. Claude Code Auto-Compact FAQ - Accessed January 20, 2026
3. Claude Code Auto-Compact Buffer FAQ - Accessed January 20, 2026
4. Claude Code Plan Mode Quick Tip - Accessed January 20, 2026
5. Auto Plan Mode FAQ - Accessed January 20, 2026
6. Context Recovery Hook Guide - Accessed January 20, 2026
7. Automatic Context Compaction - Anthropic Cookbook - Accessed January 20, 2026
8. r/ClaudeCode - Compaction Discussion - Accessed January 20, 2026