Back to all posts
02 March 2026 💻 Copilot CLI 📦 Copilot SDK

Compaction and Infinite Sessions in CLI and SDK

GitHub Copilot CLI supports infinite sessions. You can stay in one long-running conversation, and Copilot automatically compacts older context into summaries so the session remains usable without you manually managing token limits.

Availability: All GitHub Copilot paid plans (Pro, Pro+, Business, and Enterprise).

Automatic context window management

Copilot CLI handles context growth automatically. As a session gets longer, it creates checkpoints and compacts older conversation history into high-signal summaries, keeping important intent and decisions. In most cases, manual compaction is not needed.

Session artifacts are stored under:

~/.copilot/session-state/{session-id}/
├── events.jsonl      # Full session history
├── workspace.yaml    # Session/workspace metadata
├── plan.md           # Plan mode output (if created)
├── checkpoints/      # Compaction snapshots
└── files/            # Temporary session artifacts

Session management commands

Command What it does When to use it
/session Shows information about the current session Quick sanity check of where you are and what state is active
/session checkpoints Lists available compaction checkpoints Inspect summary boundaries after long runs
/session checkpoints NUMBER Displays one specific checkpoint summary Validate that compaction preserved key requirements
/session files Lists temporary files created during the session Review artifacts before deciding what belongs in your repo
/session plan Shows the active plan when using plan mode Re-anchor implementation work to the agreed plan
/context Displays context usage breakdown Understand token distribution and remaining space
/compact Manually triggers compaction Rarely needed; useful only when you want an immediate summary boundary

Best practice: keep sessions focused

Infinite sessions are powerful, but quality is highest when one session stays on one problem domain. For unrelated work, start fresh with /new or clear context with /clear. This reduces cross-task noise and makes Copilot's next decisions more reliable.

A practical flow for long tasks

  1. Start with a clear objective and constraints in your first prompt.
  2. Use /plan for multi-step changes and confirm the generated plan.
  3. During implementation, check /session and /context when you need visibility.
  4. Review /session checkpoints if the task spans many turns.
  5. When switching to unrelated work, run /new or /clear before continuing.

SDK perspective: session persistence and resume

In Copilot SDK, persistence is explicit and app-controlled. The SDK writes session state under ~/.copilot/session-state/{sessionId}/ so apps can resume after restarts.

Stored on disk Purpose Persisted?
checkpoints/*.json Conversation snapshots used for compaction/resume Yes
plan.md Planning state and implementation strategy Yes
files/ Session artifacts generated by the agent Yes
Provider API keys BYOK credentials No (security)

To make sessions reliably resumable, use your own deterministic sessionId instead of random IDs. 

// TypeScript
const session = await client.createSession({
  sessionId: "user-alice-pr-42"
});

const resumed = await client.resumeSession("user-alice-pr-42", {
  model: "gpt-5.2-codex"
});

# Python
session = client.create_session({"session_id": "user-alice-pr-42"})
resumed = client.resume_session("user-alice-pr-42", {"model": "gpt-5.2-codex"})

// .NET
var session = await client.CreateSessionAsync(new SessionConfig { SessionId = "user-alice-pr-42" });
var resumed = await client.ResumeSessionAsync("user-alice-pr-42", new ResumeSessionConfig());

SDK infinite session thresholds

SDK infinite sessions use ratio-based thresholds (not absolute tokens):

  • backgroundCompactionThreshold default 0.80: async compaction starts
  • bufferExhaustionThreshold default 0.95: processing pauses for blocking compaction

Because thresholds are percentages of the current model context window, behavior stays consistent across different model sizes.

Important SDK caveats

  • BYOK re-authentication: provider keys are not persisted, so pass provider again when resuming.
  • Writable storage required: ~/.copilot/session-state/ must be writable.
  • No built-in session locking: avoid concurrent writes to the same sessionId from multiple processes.
  • Tool runtime state: in-memory tool state is not auto-persisted; persist externally if needed.

Documentation

Best practices for GitHub Copilot CLI: 3. Leverage infinite sessions ↗  ·  Copilot SDK: Session persistence and infinite sessions ↗  ·  copilot-sdk session persistence guide (source) ↗