# GitHub Copilot CLI configuration directory

Find information about the ~/.copilot directory, where Copilot CLI stores configuration, session data, and customizations.

Copilot CLI stores its configuration, session history, logs, and customizations in a single directory on your machine. By default, this directory is `~/.copilot` (that is, `$HOME/.copilot`).

This article describes the contents of this directory and how you can use them.

## Directory overview

The `~/.copilot` directory contains the following top-level items.

| Path                      | Type      | Description                                      |
| ------------------------- | --------- | ------------------------------------------------ |
| `config.json`             | File      | Your personal configuration settings             |
| `mcp-config.json`         | File      | User-level MCP server definitions                |
| `permissions-config.json` | File      | Saved tool and directory permissions per project |
| `agents/`                 | Directory | Personal custom agent definitions                |
| `skills/`                 | Directory | Personal custom skill definitions                |
| `hooks/`                  | Directory | User-level hook scripts                          |
| `logs/`                   | Directory | Session log files                                |
| `session-state/`          | Directory | Session history and workspace data               |
| `session-store.db`        | File      | SQLite database for cross-session data           |
| `installed-plugins/`      | Directory | Installed plugin files                           |
| `ide/`                    | Directory | IDE integration state                            |

> \[!NOTE]
> Not all of these items appear immediately. Some are created on demand the first time you use a particular feature—for example, `installed-plugins/` appears only after you install your first plugin.

## User-editable files

The following files are designed to be edited by you directly, or managed through CLI commands.

### `config.json`

This is the primary configuration file for Copilot CLI. You can edit it directly in a text editor, or use interactive commands like `/model` and `/theme` to change specific values from within a session. The file supports JSON with comments (JSONC).

Common settings include:

| Key                   | Type      | Description                                                                                                          |
| --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------- |
| `model`               | string    | AI model to use (e.g., `"gpt-5.2"`, `"claude-sonnet-4.6"`)                                                           |
| `effortLevel`         | string    | Reasoning effort level for models that support it                                                                    |
| `theme`               | string    | Color theme: `"auto"`, `"dark"`, or `"light"`                                                                        |
| `mouse`               | boolean   | Enable mouse support in alt screen mode (default: `true`)                                                            |
| `banner`              | string    | Animated banner frequency: `"always"`, `"once"`, or `"never"` (default: `"once"`)                                    |
| `renderMarkdown`      | boolean   | Render Markdown in responses (default: `true`)                                                                       |
| `screenReader`        | boolean   | Enable screen reader optimizations (default: `false`)                                                                |
| `autoUpdate`          | boolean   | Automatically download CLI updates (default: `true`)                                                                 |
| `stream`              | boolean   | Stream responses token by token (default: `true`)                                                                    |
| `includeCoAuthoredBy` | boolean   | Add Co-authored-by to agent-created commits (default: `true`)                                                        |
| `respectGitignore`    | boolean   | Exclude gitignored files from the `@` file picker (default: `true`)                                                  |
| `trusted_folders`     | string\[] | Folders where read/execute permission has been granted                                                               |
| `allowed_urls`        | string\[] | URLs or domains allowed without prompting                                                                            |
| `denied_urls`         | string\[] | URLs or domains that are always denied                                                                               |
| `logLevel`            | string    | Log verbosity: `"none"`, `"error"`, `"warning"`, `"info"`, `"debug"`, `"all"`, or `"default"` (default: `"default"`) |
| `disableAllHooks`     | boolean   | Disable all hooks (default: `false`)                                                                                 |
| `hooks`               | object    | Inline user-level hook definitions                                                                                   |

For a full list of configuration settings, enter `copilot help config` in your terminal.

> \[!TIP]
> Some settings can also be set using command-line flags. For example, the `/model` slash command writes your model selection to this file so it persists across sessions.

### `mcp-config.json`

Defines MCP (Model Context Protocol) servers available at the user level. These servers are available in all your sessions, regardless of which project directory you're in. Project-level MCP configurations (in `.mcp.json` or `.github/mcp.json`) take precedence over user-level definitions when server names conflict.

For more information, see [Adding MCP servers for GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers).

### `agents/`

Store personal custom agent definitions here as `.agent.md` files. Agents placed in this directory are available in all your sessions. Project-level agents (in `.github/agents/`) take precedence over personal agents if they share the same name.

For more information, see [Creating and using custom agents for GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli).

### `skills/`

Store personal custom skill definitions here. Each skill lives in a subdirectory containing a `SKILL.md` file—for example, `~/.copilot/skills/my-skill/SKILL.md`. Personal skills are available in all your sessions. Project-level skills take precedence over personal skills if they share the same name.

For more information, see [Adding agent skills for GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills).

### `hooks/`

Store user-level hook scripts here. These hooks apply to all your sessions. You can also define hooks inline in `config.json` using the `hooks` key. Repository-level hooks (in `.github/hooks/`) are loaded alongside user-level hooks.

For more information, see [Using hooks with GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/use-hooks).

## Automatically managed files

The following items are managed by the CLI. You generally should not edit them manually.

### `permissions-config.json`

Stores your saved tool and directory permission decisions, organized by project location. When you approve a tool or grant access to a directory, the CLI records the decision here so you aren't prompted again in the same project.

> \[!NOTE]
> If you want to reset permissions for a project, you can delete the relevant entry from this file. However, editing the file while a session is running may cause unexpected behavior.

### `session-state/`

Contains session history data, organized by session ID in subdirectories. Each session directory stores an event log (`events.jsonl`) and workspace artifacts (plans, checkpoints, tracked files). This data enables session resume (`--resume` or `--continue`).

### `session-store.db`

A SQLite database used by the CLI for cross-session data such as checkpoint indexing and search. This file is automatically managed and should not be edited.

### `logs/`

Contains log files for CLI sessions. Each session creates a log file named `process-{timestamp}-{pid}.log`. These files are useful for debugging issues.

> \[!TIP]
> To find the log file for your current session, enter `/session` in an interactive session. The output includes the full path to the log file, along with other session details such as the session ID, duration, and working directory.

### `installed-plugins/`

Contains the files for plugins you have installed. Plugins installed from a marketplace are stored under `installed-plugins/{marketplace-name}/{plugin-name}/`. Directly installed plugins are stored under `installed-plugins/_direct/`. Manage plugins using the `copilot plugin` commands rather than editing this directory directly.

For more information, see [GitHub Copilot CLI plugin reference](/en/copilot/reference/copilot-cli-reference/cli-plugin-reference).

### `ide/`

Contains lock files and state for IDE integrations (for example, when Copilot CLI connects to Visual Studio Code). This directory is automatically managed.

## Changing the location of the configuration directory

You can override the default `~/.copilot` location in two ways:

* **Environment variable**: Set `COPILOT_HOME` to the path of the directory you want to use.

  ```bash copy
  export COPILOT_HOME=/path/to/my/copilot-config
  ```

* **Command-line option**: Use `--config-dir` when launching the CLI.

  ```bash copy
  copilot --config-dir /path/to/my/copilot-config
  ```

The `--config-dir` option takes precedence over `COPILOT_HOME`, which in turn takes precedence over the default `~/.copilot` location.

### Things to be aware of

* `COPILOT_HOME` replaces the entire `~/.copilot` path. The value you set should be the complete path to the directory you want to use for the configuration files and subdirectories.
* Changing the directory means your existing configuration, session history, installed plugins, and saved permissions will not be found in the new location. Copy or move the contents of `~/.copilot` to the new location if you want to preserve them.
* The **cache directory** (used for marketplace caches, auto-update packages, and other ephemeral data) follows platform conventions and is not affected by `COPILOT_HOME`. It is located at:

  * **macOS**: `~/Library/Caches/copilot`
  * **Linux**: `$XDG_CACHE_HOME/copilot` or `~/.cache/copilot`
  * **Windows**: `%LOCALAPPDATA%/copilot`

  To override the cache directory separately, set `COPILOT_CACHE_HOME`.

## What you can safely delete

| Item                           | Safe to delete? | Effect                                                                                               |
| ------------------------------ | --------------- | ---------------------------------------------------------------------------------------------------- |
| `logs/`                        | Yes             | Log files are re-created each session. Deleting them has no functional impact.                       |
| `session-state/`               | With caution    | Deleting removes session history. You will no longer be able to resume past sessions.                |
| `session-store.db`             | With caution    | Deleting removes cross-session data. The file is re-created automatically.                           |
| `config.json`                  | With caution    | Resets all configuration to defaults. You will need to reconfigure your preferences.                 |
| `permissions-config.json`      | With caution    | Resets all saved permissions. The CLI will prompt you again for tool and directory approvals.        |
| `installed-plugins/`           | Not recommended | Use `copilot plugin uninstall` instead, to ensure plugin metadata in `config.json` stays consistent. |
| `mcp-config.json`              | Not recommended | You will lose your user-level MCP server definitions. Back up first.                                 |
| `agents/`, `skills/`, `hooks/` | Not recommended | You will lose your personal customizations. Back up first.                                           |

## Further reading

* [GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli)
* [GitHub Copilot CLI command reference](/en/copilot/reference/copilot-cli-reference/cli-command-reference)
* [GitHub Copilot CLI programmatic reference](/en/copilot/reference/copilot-cli-reference/cli-programmatic-reference)
* [GitHub Copilot CLI plugin reference](/en/copilot/reference/copilot-cli-reference/cli-plugin-reference)