{"meta":{"title":"GitHub Copilot CLI configuration directory","intro":"Find information about the ~/.copilot directory, where Copilot CLI stores configuration, session data, and customizations.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/copilot","title":"GitHub Copilot"},{"href":"/en/copilot/reference","title":"Reference"},{"href":"/en/copilot/reference/copilot-cli-reference","title":"Copilot CLI reference"},{"href":"/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference","title":"CLI configuration directory"}],"documentType":"article"},"body":"# GitHub Copilot CLI configuration directory\n\nFind information about the ~/.copilot directory, where Copilot CLI stores configuration, session data, and customizations.\n\nCopilot 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`).\n\nThis article describes the contents of this directory and how you can use them.\n\n## Directory overview\n\nThe `~/.copilot` directory contains the following top-level items.\n\n| Path                      | Type      | Description                                      |\n| ------------------------- | --------- | ------------------------------------------------ |\n| `config.json`             | File      | Your personal configuration settings             |\n| `mcp-config.json`         | File      | User-level MCP server definitions                |\n| `permissions-config.json` | File      | Saved tool and directory permissions per project |\n| `agents/`                 | Directory | Personal custom agent definitions                |\n| `skills/`                 | Directory | Personal custom skill definitions                |\n| `hooks/`                  | Directory | User-level hook scripts                          |\n| `logs/`                   | Directory | Session log files                                |\n| `session-state/`          | Directory | Session history and workspace data               |\n| `session-store.db`        | File      | SQLite database for cross-session data           |\n| `installed-plugins/`      | Directory | Installed plugin files                           |\n| `ide/`                    | Directory | IDE integration state                            |\n\n> \\[!NOTE]\n> 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.\n\n## User-editable files\n\nThe following files are designed to be edited by you directly, or managed through CLI commands.\n\n### `config.json`\n\nThis 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).\n\nCommon settings include:\n\n| Key                   | Type      | Description                                                                                                          |\n| --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------- |\n| `model`               | string    | AI model to use (e.g., `\"gpt-5.2\"`, `\"claude-sonnet-4.6\"`)                                                           |\n| `effortLevel`         | string    | Reasoning effort level for models that support it                                                                    |\n| `theme`               | string    | Color theme: `\"auto\"`, `\"dark\"`, or `\"light\"`                                                                        |\n| `mouse`               | boolean   | Enable mouse support in alt screen mode (default: `true`)                                                            |\n| `banner`              | string    | Animated banner frequency: `\"always\"`, `\"once\"`, or `\"never\"` (default: `\"once\"`)                                    |\n| `renderMarkdown`      | boolean   | Render Markdown in responses (default: `true`)                                                                       |\n| `screenReader`        | boolean   | Enable screen reader optimizations (default: `false`)                                                                |\n| `autoUpdate`          | boolean   | Automatically download CLI updates (default: `true`)                                                                 |\n| `stream`              | boolean   | Stream responses token by token (default: `true`)                                                                    |\n| `includeCoAuthoredBy` | boolean   | Add Co-authored-by to agent-created commits (default: `true`)                                                        |\n| `respectGitignore`    | boolean   | Exclude gitignored files from the `@` file picker (default: `true`)                                                  |\n| `trusted_folders`     | string\\[] | Folders where read/execute permission has been granted                                                               |\n| `allowed_urls`        | string\\[] | URLs or domains allowed without prompting                                                                            |\n| `denied_urls`         | string\\[] | URLs or domains that are always denied                                                                               |\n| `logLevel`            | string    | Log verbosity: `\"none\"`, `\"error\"`, `\"warning\"`, `\"info\"`, `\"debug\"`, `\"all\"`, or `\"default\"` (default: `\"default\"`) |\n| `disableAllHooks`     | boolean   | Disable all hooks (default: `false`)                                                                                 |\n| `hooks`               | object    | Inline user-level hook definitions                                                                                   |\n\nFor a full list of configuration settings, enter `copilot help config` in your terminal.\n\n> \\[!TIP]\n> 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.\n\n### `mcp-config.json`\n\nDefines 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.\n\nFor more information, see [Adding MCP servers for GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers).\n\n### `agents/`\n\nStore 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.\n\nFor 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).\n\n### `skills/`\n\nStore 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.\n\nFor more information, see [Adding agent skills for GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills).\n\n### `hooks/`\n\nStore 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.\n\nFor more information, see [Using hooks with GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/use-hooks).\n\n## Automatically managed files\n\nThe following items are managed by the CLI. You generally should not edit them manually.\n\n### `permissions-config.json`\n\nStores 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.\n\n> \\[!NOTE]\n> 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.\n\n### `session-state/`\n\nContains 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`).\n\n### `session-store.db`\n\nA 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.\n\n### `logs/`\n\nContains log files for CLI sessions. Each session creates a log file named `process-{timestamp}-{pid}.log`. These files are useful for debugging issues.\n\n> \\[!TIP]\n> 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.\n\n### `installed-plugins/`\n\nContains 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.\n\nFor more information, see [GitHub Copilot CLI plugin reference](/en/copilot/reference/copilot-cli-reference/cli-plugin-reference).\n\n### `ide/`\n\nContains lock files and state for IDE integrations (for example, when Copilot CLI connects to Visual Studio Code). This directory is automatically managed.\n\n## Changing the location of the configuration directory\n\nYou can override the default `~/.copilot` location in two ways:\n\n* **Environment variable**: Set `COPILOT_HOME` to the path of the directory you want to use.\n\n  ```bash copy\n  export COPILOT_HOME=/path/to/my/copilot-config\n  ```\n\n* **Command-line option**: Use `--config-dir` when launching the CLI.\n\n  ```bash copy\n  copilot --config-dir /path/to/my/copilot-config\n  ```\n\nThe `--config-dir` option takes precedence over `COPILOT_HOME`, which in turn takes precedence over the default `~/.copilot` location.\n\n### Things to be aware of\n\n* `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.\n* 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.\n* 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:\n\n  * **macOS**: `~/Library/Caches/copilot`\n  * **Linux**: `$XDG_CACHE_HOME/copilot` or `~/.cache/copilot`\n  * **Windows**: `%LOCALAPPDATA%/copilot`\n\n  To override the cache directory separately, set `COPILOT_CACHE_HOME`.\n\n## What you can safely delete\n\n| Item                           | Safe to delete? | Effect                                                                                               |\n| ------------------------------ | --------------- | ---------------------------------------------------------------------------------------------------- |\n| `logs/`                        | Yes             | Log files are re-created each session. Deleting them has no functional impact.                       |\n| `session-state/`               | With caution    | Deleting removes session history. You will no longer be able to resume past sessions.                |\n| `session-store.db`             | With caution    | Deleting removes cross-session data. The file is re-created automatically.                           |\n| `config.json`                  | With caution    | Resets all configuration to defaults. You will need to reconfigure your preferences.                 |\n| `permissions-config.json`      | With caution    | Resets all saved permissions. The CLI will prompt you again for tool and directory approvals.        |\n| `installed-plugins/`           | Not recommended | Use `copilot plugin uninstall` instead, to ensure plugin metadata in `config.json` stays consistent. |\n| `mcp-config.json`              | Not recommended | You will lose your user-level MCP server definitions. Back up first.                                 |\n| `agents/`, `skills/`, `hooks/` | Not recommended | You will lose your personal customizations. Back up first.                                           |\n\n## Further reading\n\n* [GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli)\n* [GitHub Copilot CLI command reference](/en/copilot/reference/copilot-cli-reference/cli-command-reference)\n* [GitHub Copilot CLI programmatic reference](/en/copilot/reference/copilot-cli-reference/cli-programmatic-reference)\n* [GitHub Copilot CLI plugin reference](/en/copilot/reference/copilot-cli-reference/cli-plugin-reference)"}