Session State and Context Management

Context is what makes a session useful — and context gone wrong is what makes a session dangerous. Knowing where it lives and how to inspect it gives you control over both.

Copilot CLI does not hold context in memory and discard it when you close the terminal. Every tool call, every file read, every shell output gets appended to events.jsonl in the session directory. This persistence is a feature: you can restart your terminal mid-task, run copilot --resume to pick the session from a list (or copilot --resume <session-id> directly), and Copilot CLI picks up exactly where it left off. It is also a responsibility: that same persistence means session directories grow, and stale context from old sessions can occasionally contaminate new ones if you resume the wrong session.

What is stored and where

The structure is deterministic. Given a session ID, you know exactly where every artifact lives. events.jsonl is the most useful file for debugging — it is append-only and shows the exact sequence of tool calls that led to the current state. If Copilot CLI wrote something unexpected to a file, events.jsonl shows you what prompt triggered the write and what tool call performed it.

The inspection commands

You should not need to read raw events.jsonl during a normal session. The session inspection commands surface what matters:

The command you will use most for debugging is /context. When Copilot CLI makes a decision that surprises you — it edits the wrong file, it applies a convention you did not ask for, it avoids a file you expected it to read — run /context to see what is actually loaded in the active window. Nine times out of ten, the surprising decision is explained by something in the context you had forgotten was there.

Context window limits and degradation

Sessions degrade over time. As the context window fills — with file reads, command outputs, conversation history — older entries get compressed or dropped. This is not unique to Copilot CLI; it is how all LLM-based agents work. The practical implication is that a task you start in a fresh session will often be executed better than the same task started three hours and a dozen prompts into a session that has been doing other work.

Signs a session's context is getting stale:

• Copilot CLI "forgets" a constraint you specified earlier
• It uses a file path it already confirmed does not exist
• It repeats work it already completed earlier in the session

When you see these signs, run /clear to reset context without ending the process, then re-specify your task. Or use /new to start completely fresh.

Checkpoints and rewinding long tasks

For tasks that will take many tool calls — a large refactor, a migration across dozens of files — the session's persisted artifacts are your safety net. Copilot CLI stores workspace artifacts (plans, checkpoints, tracked files) alongside the event log in the session directory as the session progresses.

The interactive surface for undoing a wrong turn is /undo — it rewinds the last turn and reverts its file changes. If a set of changes went wrong, /undo and re-prompt with a different approach rather than asking the agent to manually re-edit its way back.

Cleaning up session state

Session directories accumulate. A month of active development generates dozens of session directories. The primary cleanup mechanism is built into the CLI: run /session cleanup (or /session prune) inside a session to clear out old session state without leaving the tool. Reach for the manual approach only as a fallback when you want to script the deletion or filter by age:

# List session directories by date
ls -lt ~/.copilot/session-state/

# Fallback: delete sessions older than 30 days from the shell
find ~/.copilot/session-state/ -maxdepth 1 -type d -mtime +30 -exec rm -rf {} \;

Keep sessions with plan.md files you might want to reference later. Delete everything else on a regular cadence.

Lesson Drill

1. Open an existing session (or start a new one and do a few prompts) and run /session. What does the session information show?
2. Run /diff after a session that made changes. Verify the changes match what you expected Copilot CLI to have touched.
3. Run /context mid-session and read the output. Identify one thing in the context you did not realize was loaded.

Bottom Line

Session state lives in ~/.copilot/session-state/{id}/ and persists across terminal restarts — resume with copilot --resume. The key artifacts are events.jsonl (full tool call history) plus the workspace artifacts: plans, checkpoints, and tracked files. Use /context to diagnose unexpected behavior, /diff to audit what was touched, and /clear or /new when context accumulation starts working against you.

The next lesson covers tool control — how to configure precisely which tools Copilot CLI can use, and which it cannot.