Where GitHub Copilot CLI Stores Configuration Files

GitHub Copilot CLI stores various configuration files, session data, and custom agents in specific locations on your system. Understanding these locations helps you customize your setup, backup configurations, troubleshoot issues, and migrate to new machines.

Directory Structure Overview

Here is the complete directory structure for Copilot CLI configuration:

~/.copilot/                          # Main configuration directory
├── config.json                      # Core CLI settings
├── mcp-config.json                  # MCP server configurations
├── command-history-state.json       # Command history
├── session-state/                   # Active session data (v0.0.342+)
│   └── [session files]
├── history-session-state/           # Legacy session storage
│   └── [legacy session files]
├── agents/                          # Custom agent definitions
│   └── my-agent.md
└── logs/                            # Debug and error logs
    └── [log files]

~/project/.copilot/                  # Project-specific config
└── mcp-config.json                  # Project MCP servers

~/project/.github/                   # Repository instructions
├── copilot-instructions.md          # Main instructions file
└── instructions/                    # Additional instruction files
    └── *.instructions.md

~/.config/gh/                        # GitHub CLI credentials
└── hosts.yml                        # Authentication tokens

User-Level Configuration Files

Main Configuration Directory

The primary configuration directory is ~/.copilot/. All platform-independent settings live here.

Platform-specific paths:

config.json

The main configuration file for Copilot CLI settings.

Location: ~/.copilot/config.json

This file stores:

• Default model selection
• Editor preferences
• Output formatting options
• Feature flags

Example structure:

{
  "model": "claude-sonnet-4-5",
  "editor": "code",
  "theme": "auto"
}

mcp-config.json (User-Level)

Model Context Protocol (MCP) server configurations that apply globally to all sessions.

Location: ~/.copilot/mcp-config.json

This file defines external tools and data sources that Copilot CLI can access:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
    }
  }
}

Session State

Copilot CLI maintains session state to preserve context between interactions.

Current location (v0.0.342+): ~/.copilot/session-state/

Legacy location: ~/.copilot/history-session-state/

Session state includes:

• Conversation history
• Context from previous interactions
• Temporary working data

Note: Session state is ephemeral and should not be backed up or transferred between machines.

Command History

Your command history is stored for easy recall with the up arrow key.

Location: ~/.copilot/command-history-state.json

This file contains:

• Previous prompts and commands
• Timestamps
• Session references

Custom Agents

Custom agent definitions that extend Copilot CLI capabilities.

Location: ~/.copilot/agents/

Each agent is defined in a markdown file:

~/.copilot/agents/
├── code-reviewer.md
├── docs-writer.md
└── security-auditor.md

To use a custom agent:

copilot @code-reviewer "review this function for potential issues"

Logs

Debug and error logs for troubleshooting.

Location: ~/.copilot/logs/

Logs are useful when:

• Debugging connection issues
• Reporting bugs to GitHub
• Understanding unexpected behavior

Project-Level Configuration

Project MCP Configuration

Project-specific MCP servers that only apply when working in that directory.

Location: ./copilot/mcp-config.json (in project root)

This allows you to define project-specific tools:

{
  "servers": {
    "database": {
      "command": "node",
      "args": ["./scripts/db-mcp-server.js"]
    }
  }
}

Project MCP configurations are merged with user-level configurations, with project settings taking precedence.

Repository Instructions

copilot-instructions.md

The main file for repository-specific instructions that guide Copilot behavior.

Location: .github/copilot-instructions.md

This file tells Copilot CLI about:

• Project conventions
• Coding standards
• Preferred patterns
• Things to avoid

Example:

# Project Guidelines

- Use TypeScript for all new code
- Follow the existing naming conventions
- Write tests for all new functions
- Prefer functional programming patterns

Additional Instruction Files

For larger projects, you can split instructions across multiple files.

Location: .github/instructions/*.instructions.md

.github/instructions/
├── security.instructions.md
├── testing.instructions.md
└── documentation.instructions.md

AGENTS.md

An alternative to copilot-instructions.md that some projects use.

Location: ./AGENTS.md (project root)

This file serves the same purpose as copilot-instructions.md but follows a different naming convention used by some AI coding tools.

Organization Agents

For GitHub Enterprise, organizations can define shared agents.

Location: .github repository in your organization, agents/ directory

These agents are available to all members of the organization when using Copilot CLI in organization repositories.

Credentials and Authentication

GitHub CLI Credentials

Copilot CLI uses the GitHub CLI (gh) for authentication when available.

Location: ~/.config/gh/hosts.yml

This file contains your GitHub authentication tokens. Copilot CLI reads these credentials automatically if you have authenticated with gh auth login.

Environment Variables

You can also authenticate using environment variables:

Priority order: Copilot CLI checks for tokens in this order:

1. COPILOT_GITHUB_TOKEN
2. GH_TOKEN
3. GITHUB_TOKEN
4. ~/.config/gh/hosts.yml

IDE Copilot vs CLI Copilot Storage

Copilot CLI and IDE Copilot extensions store configurations in completely different locations:

Important: Changes to VS Code Copilot settings do not affect Copilot CLI, and vice versa. Configure each tool independently.

Backup and Migration

What to Backup

For a complete backup of your Copilot CLI configuration:

# User configuration
cp -r ~/.copilot/config.json ~/backup/copilot/
cp -r ~/.copilot/mcp-config.json ~/backup/copilot/
cp -r ~/.copilot/agents/ ~/backup/copilot/

# Project configurations (for each project)
cp ./copilot/mcp-config.json ~/backup/projects/projectname/
cp .github/copilot-instructions.md ~/backup/projects/projectname/

What NOT to Backup

Do not backup or transfer:

• ~/.copilot/session-state/ - Session-specific data
• ~/.copilot/history-session-state/ - Legacy session data
• ~/.config/gh/hosts.yml - Contains authentication tokens
• ~/.copilot/logs/ - Machine-specific logs

Migrating to a New Machine

1. Copy configuration files:

   # On old machine
   tar -czvf copilot-config.tar.gz \
     ~/.copilot/config.json \
     ~/.copilot/mcp-config.json \
     ~/.copilot/agents/
   
   # Transfer to new machine, then extract
   tar -xzvf copilot-config.tar.gz -C ~/
   

   Copy

2. Re-authenticate on the new machine:

   copilot
   # Use /login when prompted
   

   Copy

3. Verify configuration:

   copilot --version
   copilot "test that everything is working"
   

   Copy

Troubleshooting Configuration Issues

Config File Not Being Read

If your settings are not taking effect:

1. Check file permissions:

   ls -la ~/.copilot/config.json
   

   Copy

2. Validate JSON syntax:

   cat ~/.copilot/config.json | python -m json.tool
   

   Copy

3. Check for XDG override:

   echo $XDG_CONFIG_HOME
   

   Copy

MCP Servers Not Loading

If project MCP servers are not available:

1. Verify file location is exactly .copilot/mcp-config.json (note the leading dot)
2. Check JSON syntax in the MCP config file
3. Ensure the server command is installed and in your PATH

Session State Corruption

If Copilot CLI behaves unexpectedly:

# Clear session state
rm -rf ~/.copilot/session-state/
rm -rf ~/.copilot/history-session-state/

# Restart Copilot CLI
copilot

Next Steps

• Learn how to install Copilot CLI if you have not already
• Explore Copilot CLI slash commands for advanced features
• Set up custom agents to extend functionality
• Configure GitHub Actions integration for CI/CD workflows

Need help configuring AI development tools for your team? Inventive HQ helps organizations implement AI coding assistants with proper security controls and team-wide configurations. Contact us for a consultation.