📞 Sessions & Custom Instructions¶

What Is a Session?¶

Think of a session as a phone call between you and Copilot:

Phone Call	Copilot Session
📱 You dial someone	You open a terminal and type `copilot`
💬 You chat back and forth — they remember the conversation	You ask questions — Copilot remembers everything said so far
📴 You hang up	You close the terminal (or type `/clear`)
📱 You call again	You open a new terminal — fresh start, no memory of last call

Aspect	How It Works
Created when	You launch `copilot` or open a new terminal panel
Memory scope	Everything discussed within this session only
Ends when	You close the terminal, type `/exit`, `/clear`, or start a new session
Resume with	Type `/resume` → pick a past session from the list → you're back where you left off

Separate panels = separate sessions

If you split your terminal into two panels, each one is a completely independent session. They don't share memory or context — it's like two separate phone calls happening at the same time.

The Passport vs Phone Call Strategy 🛂📞¶

This is the most important concept for getting the best experience out of Copilot CLI. You have three types of memory — understand them and you'll never lose anything important.

📞 Phone Calls (Sessions / Conversations)¶

Sessions are temporary by design. You start them, use them, and let them go.

Everything you discuss lives only inside that session
It's OK to lose the details — that's what sessions are for
/compact = condense the conversation (keep the key points, free up memory)
/clear = hang up completely (nuclear reset)
/new = start a fresh page but the session history is still saved

When to use sessions

Asking a one-off question, exploring something, debugging a problem, running commands. These are phone calls — use them and move on.

🛂 Passport (Custom Instructions File)¶

Your instructions file is your permanent memory. It travels with you everywhere — every session, every device, every /clear.

It loads automatically at the start of every session
It tells Copilot who you are, how you work, and what you care about
It survives /clear, /compact, terminal restarts, even reboots
Think of it as your passport: it carries your identity everywhere you go

When to update your passport

You discover a preference ("I like tables, not paragraphs"), learn something about your environment ("My lab tenant ID is X"), or establish a workflow ("Always explain commands before running them").

📚 Learning Portal (Documentation — This Site!)¶

Everything you learn goes into your documentation site. Sessions come and go, but lessons live here forever.

Becomes your personal teaching material
Organises knowledge by topic
Can be shared with others or used as a reference

The Golden Rule 🏆

Save important stuff to your instructions file during the conversation, then /clear or /compact freely — nothing important is lost!

The workflow: Learn it → Save it to passport → Clear the session → Move on

Custom Instructions File¶

Where Is It?¶

C:\Users\<your-username>\.copilot\copilot-instructions.md

What does the dot (.) mean?

The .copilot folder starts with a dot — this is a computing convention that means "hidden configuration folder". On Windows, you won't see it in File Explorer unless you turn on View → Show → Hidden items. Every major tool uses this pattern: .git, .vscode, .ssh, .copilot.

What Goes in It?¶

Your instructions file is a Markdown document. Put anything you want Copilot to know in every session:

Category	Examples
Identity	Your name, role, background ("I'm an IT admin, not a developer")
Formatting	"Use bullet points", "Keep answers under 300 words", "Use tables for comparisons"
Learning style	"Explain like I'm new to tech", "Use analogies", "Show me the 'why' not just the 'how'"
Environment	Lab tenant info, subscription IDs, preferred Azure region
Preferences	"Always explain commands before running them", "Use PowerShell, not Bash"
Discovered facts	Things learned during conversations ("My lab uses E5 licenses")

How to Update It¶

Method 1 — Ask Copilot (easiest):

Just say it naturally during any conversation:

"Add to my custom instructions that I prefer dark mode examples"

"Update my instructions to include that my lab tenant is M365CPI52224224"

"Save to my passport that I like tables instead of long paragraphs"

Copilot will edit the file for you.

Method 2 — Edit manually with Notepad:

# Open the instructions file in Notepad
notepad "$HOME\.copilot\copilot-instructions.md"

Method 3 — Edit with VS Code (if installed):

code "$HOME\.copilot\copilot-instructions.md"

Reference File (Advanced)¶

For more detailed context, you can create a second file alongside your main instructions:

C:\Users\<your-username>\.copilot\copilot-instructions.md            ← Punchy essentials
C:\Users\<your-username>\.copilot\copilot-instructions-reference.md  ← Detailed context

File	Purpose	Style
`copilot-instructions.md`	Quick rules and preferences	Short, punchy bullet points
`copilot-instructions-reference.md`	Detailed background and context	Longer explanations, examples, tenant details

Keep the main file lean

The main instructions file is loaded into every session. If it gets too long, it eats into your context window (Copilot's working memory). Keep it focused — move detailed reference material to the reference file.

Auto-Save: Let Copilot Be Proactive¶

Copilot should proactively scan conversations and offer to save important discoveries to your instructions file without you having to ask. If you learn something useful — a preference, a fact about your environment, a workflow that works well — Copilot should suggest: "Want me to save this to your instructions?"

Train Copilot to do this

Add this to your instructions file: "Proactively scan conversations and save important discoveries (preferences, environment facts, workflows) to my instructions file without being asked."

Session Management Commands¶

Command Reference¶

Command	What It Does	Analogy
`/exit`	Save the session and close the CLI completely	📴 Hanging up the phone — conversation is saved in call history
`/restart`	Restart the CLI but keep the current session	🔄 Phone glitching? Reboot it — same call history, same number
`/resume`	Go back to a previous session — pick from a list	📱 Calling someone back
`/new`	Start a fresh conversation (session history is still saved)	📝 Flipping to a fresh page on your notepad
`/clear`	Abandon the session and start over (stays in CLI)	🗑️ Throwing away the entire notepad
`/compact`	Smart shrink — condense the conversation, keep key points, free memory	✂️ Erasing old scribbles but keeping a summary note
`/rename`	Give the current session a name for easy finding later	🏷️ Labelling a folder

/exit vs /clear vs /restart — Which One Should I Use?¶

This is one of the most common questions! Here's the definitive comparison:

	`/exit`	`/clear`	`/restart`
Closes the CLI?	✅ Yes — exits completely	❌ No — stays open	✅ Yes — then relaunches
Session saved?	✅ Yes — saved to history	❌ No — abandoned	✅ Yes — preserved
Can resume later?	✅ `/resume` after relaunching	❌ Gone forever	✅ Automatically resumes
Context cleared?	✅ Fresh start next time	✅ Fresh start immediately	⚠️ Same session continues
Custom instructions?	✅ Reloaded on next launch	✅ Reloaded immediately	✅ Reloaded on restart

☕ Café analogy: Think of it like closing the café at the end of the day:

/exit = Close up shop for the night. Lock the door, go home. Tomorrow is a fresh day, but today's sales records are safely saved.

/clear = Wipe the whiteboard mid-shift. You're still at work, but you've erased everything and started blank. Yesterday's whiteboard notes? Gone.

/restart = Power-cycle the coffee machine — it was acting weird, so you unplug it and plug it back in. Same machine, same settings, same day.

Quick decision guide

Done for the day? → /exit ✅ (saves everything, closes cleanly)
Switching to a totally different topic? → /clear (fresh context, old session is gone)
CLI acting buggy or slow? → /restart (fresh process, same session)
Topic change but want to keep history? → /new (fresh conversation, old one saved)

Session History — How Many Sessions Are Stored?¶

Sessions are stored in a local SQLite database on your machine. There is no known hard limit on how many sessions are kept.

Question	Answer
Where are sessions stored?	`~/.copilot/` folder (local SQLite database)
How many can I keep?	No published limit — sessions accumulate over time
Disk space impact?	Minimal — sessions are text (conversations + checkpoints), not media files
Auto-cleanup?	No automatic deletion — sessions persist indefinitely
How to find old sessions?	`/resume` shows a list of past sessions with timestamps
Can I name sessions?	✅ `/rename` gives a session a meaningful name (e.g., "AI Dashboard Setup")

Pro tip: Name your important sessions

Before you /exit, run /rename and give the session a descriptive name like "MCP Hands-On Lab" or "AI Dashboard Deployment". Makes it much easier to find with /resume later!

Session Exit Summary — Your Receipt 🧾¶

When you /exit a session (or it ends), Copilot displays a session summary — think of it like a receipt after a restaurant meal. It tells you exactly what happened, how long it took, and what it cost.

Here's what each section means:

Example Exit Summary¶

╭─────────────────────────────────────────────────╮
│  Session Summary                                │
│                                                 │
│  Duration:          3h 42m                      │
│  API time:          28m 15s                     │
│  Turns:             47                          │
│  Code changes:      12 files changed            │
│                                                 │
│  Model usage:                                   │
│    Claude Opus 4.6       38 turns    22m 10s    │
│    Claude Haiku 4.5       9 turns     6m 05s    │
│                                                 │
│  Resume this session:                           │
│    copilot --resume abc12345-6789-...           │
╰─────────────────────────────────────────────────╯

What Each Metric Means¶

Metric	What It Measures	Analogy
Duration	Total wall-clock time from when you launched `copilot` to when you exited	⏱️ How long the restaurant visit lasted (including waiting)
API time	Time the AI model actually spent thinking and generating responses	👨‍🍳 How long the chef was actually cooking (not the waiting-for-a-table time)
Turns	Number of back-and-forth exchanges (you ask → Copilot responds = 1 turn)	💬 Number of times you ordered something from the waiter
Code changes	Number of files Copilot created or modified during the session	📝 Number of dishes that came out of the kitchen

Code changes includes documentation too

Despite being called "code changes", this counter tracks any file Copilot modified — code files, Markdown documentation, config files, CSV data files, YAML configs, etc. If Copilot used the edit or create tool on a file, it counts. In a documentation session, all your .md file updates appear here.

Model Usage Breakdown¶

The model usage section shows which AI models were used and how much:

Column	Meaning
Model name	Which AI model handled those turns (e.g., Claude Opus 4.6, Claude Haiku 4.5, GPT-5.1)
Turns	How many of your interactions used that model
Time	Total API thinking time for that model

Why are there multiple models?

Even if you selected one model (e.g., Opus 4.6), Copilot uses sub-agents behind the scenes for certain tasks — like the explore agent (uses Haiku for fast file searching) or task agent (uses Haiku for running commands). These are the cheaper, faster models that handle the grunt work while your main model handles the complex thinking. That's why you see multiple models in the breakdown.

Resume Session Command¶

The last line gives you the exact command to pick up this session later:

copilot --resume abc12345-6789-...

This is the same as launching copilot and then running /resume — but faster because it skips the session picker and goes straight to the session you want.

Save the session ID if it matters

If you're working on something important and plan to come back, copy the resume command before the terminal scrolls away. Alternatively, use /rename before exiting to give it a memorable name — then you can find it easily with /resume without needing the ID.

/clear vs /compact vs /new — The Café Order Pad ☕¶

Imagine you're a waiter taking orders on an order pad:

Command	Café Analogy	What Actually Happens
`/compact`	Erasing old completed orders but keeping a summary note ("Table 3 had the pasta special")	Copilot summarises the conversation into key points and discards the detailed back-and-forth. Memory is freed but context is preserved.
`/new`	Flipping to a fresh page on the order pad — old pages are still there if you flip back	A brand-new conversation starts. The previous session is saved and can be resumed with `/resume`.
`/clear`	Throwing away the entire order pad and starting with a blank one	Everything is gone. The session cannot be resumed. Only your custom instructions file survives (because it's your passport 🛂).

Which should I use?

Running low on memory? → /compact (keeps context, frees space)
Done with this topic, starting something new? → /new (clean slate, old session saved)
Something went wrong and you want a total reset? → /clear (nuclear option)

Backup¶

Automated Backup System¶

Your Copilot configuration is backed up automatically so you never lose your custom instructions, plugins, or session history.

Setting	Value
Schedule	Daily at 9:00 AM
Primary destination	`OneDrive - Microsoft\CopilotCLI_Backups\`
Secondary destination	Google Drive (if configured)
Retention	Last 30 backups kept (older ones auto-deleted)
What's included	Config files, plugins, session history (excludes large MCP server binaries)
Missed schedule	Runs on wake if laptop was off (`StartWhenAvailable` enabled)
Managed by	Windows Scheduled Task: `CopilotCLI_BackupInstructions`

Checking & Running Backups¶

# Check if the backup task exists and its status
Get-ScheduledTask -TaskName "CopilotCLI_BackupInstructions"

# See when it last ran
Get-ScheduledTaskInfo -TaskName "CopilotCLI_BackupInstructions"

# Run a backup manually right now
& "$HOME\.copilot\backup-instructions.ps1"

Don't skip backups

Your custom instructions file is the result of weeks of learning and tuning. If it gets corrupted or accidentally deleted, the backup is your safety net. Verify the backup task is running with the command above.

Instruction File Locations Copilot Looks For¶

Copilot doesn't just read one file — it checks multiple locations and merges them. This is useful to know so you don't accidentally create conflicting instructions.

File / Pattern	Scope	Purpose
`$HOME\.copilot\copilot-instructions.md`	Global — all sessions everywhere	Your personal identity and preferences (the "passport")
`.github\copilot-instructions.md`	Repository — this project only	Project-specific rules (coding style, frameworks, conventions)
`.github\instructions\*\.instructions.md`	Repository — this project only	Topic-specific instructions (e.g., `testing.instructions.md`)
`AGENTS.md`	Repository — this project only	Instructions for AI agents working on this repo
`CLAUDE.md`	Repository — this project only	Claude-specific instructions (also read by Copilot)
`GEMINI.md`	Repository — this project only	Gemini-specific instructions (also read by Copilot)

Priority order

When instructions conflict, more specific wins. Repository-level instructions override global ones. Think of it like laws: city laws override state laws for local matters, but state laws apply everywhere else.

For non-developers

You'll mostly use the global file ($HOME\.copilot\copilot-instructions.md). The repository-level files are mainly used by development teams to set coding standards. You don't need to worry about them unless you're working inside a code project.