|
| 1 | +--- |
| 2 | +title: GitHub Copilot CLI configuration directory |
| 3 | +shortTitle: CLI configuration directory |
| 4 | +allowTitleToDifferFromFilename: true |
| 5 | +intro: 'Find information about the `~/.copilot` directory, where {% data variables.copilot.copilot_cli_short %} stores configuration, session data, and customizations.' |
| 6 | +versions: |
| 7 | + feature: copilot |
| 8 | +category: |
| 9 | + - Author and optimize with Copilot # Copilot discovery page |
| 10 | + - Configure Copilot CLI # Copilot CLI bespoke page |
| 11 | +contentType: reference |
| 12 | +--- |
| 13 | + |
| 14 | +{% data variables.copilot.copilot_cli_short %} 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`). |
| 15 | + |
| 16 | +This article describes the contents of this directory and how you can use them. |
| 17 | + |
| 18 | +## Directory overview |
| 19 | + |
| 20 | +The `~/.copilot` directory contains the following top-level items. |
| 21 | + |
| 22 | +| Path | Type | Description | |
| 23 | +|------|------|-------------| |
| 24 | +| `config.json` | File | Your personal configuration settings | |
| 25 | +| `mcp-config.json` | File | User-level MCP server definitions | |
| 26 | +| `permissions-config.json` | File | Saved tool and directory permissions per project | |
| 27 | +| `agents/` | Directory | Personal custom agent definitions | |
| 28 | +| `skills/` | Directory | Personal custom skill definitions | |
| 29 | +| `hooks/` | Directory | User-level hook scripts | |
| 30 | +| `logs/` | Directory | Session log files | |
| 31 | +| `session-state/` | Directory | Session history and workspace data | |
| 32 | +| `session-store.db` | File | SQLite database for cross-session data | |
| 33 | +| `installed-plugins/` | Directory | Installed plugin files | |
| 34 | +| `ide/` | Directory | IDE integration state | |
| 35 | + |
| 36 | +> [!NOTE] |
| 37 | +> 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. |
| 38 | +
|
| 39 | +## User-editable files |
| 40 | + |
| 41 | +The following files are designed to be edited by you directly, or managed through CLI commands. |
| 42 | + |
| 43 | +### `config.json` |
| 44 | + |
| 45 | +This is the primary configuration file for {% data variables.copilot.copilot_cli_short %}. 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). |
| 46 | + |
| 47 | +Common settings include: |
| 48 | + |
| 49 | +| Key | Type | Description | |
| 50 | +|-----|------|-------------| |
| 51 | +| `model` | string | AI model to use (e.g., `"gpt-5.2"`, `"claude-sonnet-4.6"`) | |
| 52 | +| `effortLevel` | string | Reasoning effort level for models that support it | |
| 53 | +| `theme` | string | Color theme: `"auto"`, `"dark"`, or `"light"` | |
| 54 | +| `alt_screen` | boolean | Use the alternate screen buffer (default: `true`) | |
| 55 | +| `mouse` | boolean | Enable mouse support in alt screen mode (default: `true`) | |
| 56 | +| `banner` | string | Animated banner frequency: `"always"`, `"once"`, or `"never"` (default: `"once"`) | |
| 57 | +| `render_markdown` | boolean | Render markdown in responses (default: `true`) | |
| 58 | +| `screen_reader` | boolean | Enable screen reader optimizations (default: `false`) | |
| 59 | +| `auto_update` | boolean | Automatically download CLI updates (default: `true`) | |
| 60 | +| `stream` | boolean | Stream responses token by token (default: `true`) | |
| 61 | +| `includeCoAuthoredBy` | boolean | Add Co-authored-by to agent-created commits (default: `true`) | |
| 62 | +| `respectGitignore` | boolean | Exclude gitignored files from the `@` file picker (default: `true`) | |
| 63 | +| `trusted_folders` | string[] | Folders where read/execute permission has been granted | |
| 64 | +| `allowed_urls` | string[] | URLs or domains allowed without prompting | |
| 65 | +| `denied_urls` | string[] | URLs or domains that are always denied | |
| 66 | +| `log_level` | string | Log verbosity: `"none"`, `"error"`, `"warning"`, `"info"`, `"debug"`, `"all"`, or `"default"` (default: `"default"`) | |
| 67 | +| `disableAllHooks` | boolean | Disable all hooks (default: `false`) | |
| 68 | +| `hooks` | object | Inline user-level hook definitions | |
| 69 | + |
| 70 | +For a full list of configuration settings, enter `copilot help config` in your terminal. |
| 71 | + |
| 72 | +> [!TIP] |
| 73 | +> Some settings can also be set using command-line flags. For example, `--alt-screen` and `--no-alt-screen` set the `alt_screen` value and persist it to `config.json`. The `/model` slash command writes your model selection to this file so it persists across sessions. |
| 74 | +
|
| 75 | +### `mcp-config.json` |
| 76 | + |
| 77 | +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`, `.github/mcp.json`, or `.vscode/mcp.json`) take precedence over user-level definitions when server names conflict. |
| 78 | + |
| 79 | +For more information, see [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers). |
| 80 | + |
| 81 | +### `agents/` |
| 82 | + |
| 83 | +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. |
| 84 | + |
| 85 | +For more information, see [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli). |
| 86 | + |
| 87 | +### `skills/` |
| 88 | + |
| 89 | +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. |
| 90 | + |
| 91 | +For more information, see [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/create-skills). |
| 92 | + |
| 93 | +### `hooks/` |
| 94 | + |
| 95 | +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. |
| 96 | + |
| 97 | +For more information, see [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/use-hooks). |
| 98 | + |
| 99 | +## Automatically managed files |
| 100 | + |
| 101 | +The following items are managed by the CLI. You generally should not edit them manually. |
| 102 | + |
| 103 | +### `permissions-config.json` |
| 104 | + |
| 105 | +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. |
| 106 | + |
| 107 | +> [!NOTE] |
| 108 | +> 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. |
| 109 | +
|
| 110 | +### `session-state/` |
| 111 | + |
| 112 | +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`). |
| 113 | + |
| 114 | +### `session-store.db` |
| 115 | + |
| 116 | +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. |
| 117 | + |
| 118 | +### `logs/` |
| 119 | + |
| 120 | +Contains log files for CLI sessions. Each session creates a log file named `process-{timestamp}-{pid}.log`. These files are useful for debugging issues. |
| 121 | + |
| 122 | +> [!TIP] |
| 123 | +> 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. |
| 124 | +
|
| 125 | +### `installed-plugins/` |
| 126 | + |
| 127 | +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. |
| 128 | + |
| 129 | +For more information, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-plugin-reference). |
| 130 | + |
| 131 | +### `ide/` |
| 132 | + |
| 133 | +Contains lock files and state for IDE integrations (for example, when {% data variables.copilot.copilot_cli_short %} connects to {% data variables.product.prodname_vscode %}). This directory is automatically managed. |
| 134 | + |
| 135 | +## Changing the location of the configuration directory |
| 136 | + |
| 137 | +You can override the default `~/.copilot` location in two ways: |
| 138 | + |
| 139 | +- **Environment variable**: Set `COPILOT_HOME` to the path of the directory you want to use. |
| 140 | + |
| 141 | + ```bash copy |
| 142 | + export COPILOT_HOME=/path/to/my/copilot-config |
| 143 | + ``` |
| 144 | + |
| 145 | +- **Command-line option**: Use `--config-dir` when launching the CLI. |
| 146 | + |
| 147 | + ```bash copy |
| 148 | + copilot --config-dir /path/to/my/copilot-config |
| 149 | + ``` |
| 150 | + |
| 151 | +The `--config-dir` option takes precedence over `COPILOT_HOME`, which in turn takes precedence over the default `~/.copilot` location. |
| 152 | + |
| 153 | +### Things to be aware of |
| 154 | + |
| 155 | +- `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. |
| 156 | +- 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. |
| 157 | +- 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: |
| 158 | + - **macOS**: `~/Library/Caches/copilot` |
| 159 | + - **Linux**: `$XDG_CACHE_HOME/copilot` or `~/.cache/copilot` |
| 160 | + - **Windows**: `%LOCALAPPDATA%/copilot` |
| 161 | + |
| 162 | + To override the cache directory separately, set `COPILOT_CACHE_HOME`. |
| 163 | + |
| 164 | +## What you can safely delete |
| 165 | + |
| 166 | +| Item | Safe to delete? | Effect | |
| 167 | +|------|-----------------|--------| |
| 168 | +| `logs/` | Yes | Log files are re-created each session. Deleting them has no functional impact. | |
| 169 | +| `session-state/` | With caution | Deleting removes session history. You will no longer be able to resume past sessions. | |
| 170 | +| `session-store.db` | With caution | Deleting removes cross-session data. The file is re-created automatically. | |
| 171 | +| `config.json` | With caution | Resets all configuration to defaults. You will need to reconfigure your preferences. | |
| 172 | +| `permissions-config.json` | With caution | Resets all saved permissions. The CLI will prompt you again for tool and directory approvals. | |
| 173 | +| `installed-plugins/` | Not recommended | Use `copilot plugin uninstall` instead, to ensure plugin metadata in `config.json` stays consistent. | |
| 174 | +| `mcp-config.json` | Not recommended | You will lose your user-level MCP server definitions. Back up first. | |
| 175 | +| `agents/`, `skills/`, `hooks/` | Not recommended | You will lose your personal customizations. Back up first. | |
| 176 | + |
| 177 | +## Further reading |
| 178 | + |
| 179 | +* [AUTOTITLE](/copilot/how-tos/copilot-cli) |
| 180 | +* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference) |
| 181 | +* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-programmatic-reference) |
| 182 | +* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-plugin-reference) |
0 commit comments