Diretório de configuração do GitHub Copilot CLI

          CLI do Copilot armazena sua configuração, histórico de sessão, logs e personalizações em um único diretório em seu computador. Por padrão, esse diretório é `~/.copilot` (ou seja, `$HOME/.copilot`).

Este artigo descreve o conteúdo deste diretório e como você pode usá-los.

Visão geral do diretório

O ~/.copilot diretório contém os seguintes itens de nível superior.

Caminho	Tipo	Descrição
`settings.json`	Arquivo	Suas configurações pessoais
`copilot-instructions.md`	Arquivo	Instruções personalizadas pessoais (aplicadas a todas as sessões)
`instructions/`	Diretório	Arquivos pessoais adicionais `*.instructions.md`
`mcp-config.json`	Arquivo	Definições de servidor MCP no nível do usuário
`lsp-config.json`	Arquivo	Definições de servidor LSP no nível do usuário
`permissions-config.json`	Arquivo	Permissões de ferramenta e diretório salvas por projeto
`agents/`	Diretório	Definições de agente personalizado pessoal
`skills/`	Diretório	Definições de habilidades personalizadas pessoais
`hooks/`	Diretório	Scripts de gancho no nível do usuário
`logs/`	Diretório	Arquivos de log de sessão
`session-state/`	Diretório	Histórico de sessão e dados do workspace
`session-store.db`	Arquivo	Banco de dados SQLite para dados entre sessões
`installed-plugins/`	Diretório	Arquivos de plug-in instalados
`plugin-data/`	Diretório	Dados persistentes para plug-ins instalados
`ide/`	Diretório	Estado de integração do IDE

Observação

Nem todos esses itens aparecem imediatamente. Alguns são criados sob demanda na primeira vez que você usa um recurso específico— por exemplo, installed-plugins/ aparece somente depois de instalar seu primeiro plug-in.

Arquivos editáveis pelo usuário

Os arquivos a seguir foram projetados para serem editados diretamente por você ou gerenciados por meio de comandos da CLI.

`settings.json`

Este é o arquivo de configuração principal para CLI do Copilot. Você pode editá-lo diretamente em um editor de texto ou usar comandos interativos como /model e /theme alterar valores específicos de dentro de uma sessão. O arquivo dá suporte a JSON com comentários (JSONC).

Observação

O arquivo de configuração foi renomeado de config.json para settings.json. As configurações existentes são migradas automaticamente na inicialização de ~/.copilot/config.json.

Para obter a lista completa de configurações e como elas interagem com a configuração no nível do repositório, consulte configurações de arquivo mais adiante neste artigo.

Dica

Execute copilot help config em seu terminal para obter uma referência rápida.

`copilot-instructions.md`

Instruções personalizadas pessoais que se aplicam a todas as suas sessões, independentemente de em qual projeto você está trabalhando. Esse arquivo funciona da mesma maneira que um nível copilot-instructions.md de repositório, mas se aplica globalmente.

Para obter mais informações, consulte Adicionando instruções personalizadas do repositório para GitHub Copilot.

`instructions/`

Armazene aqui arquivos de instrução pessoal adicionais como arquivos *.instructions.md. Elas são carregadas junto com copilot-instructions.md e se aplicam a todas as suas sessões. Você pode organizar instruções por tópico, por exemplo, ~/.copilot/instructions/code-style.instructions.md.

`mcp-config.json`

Define os servidores MCP (Protocolo de Contexto de Modelo) disponíveis no nível do usuário. Esses servidores estão disponíveis em todas as suas sessões, independentemente de qual diretório de projeto você esteja. As configurações MCP de nível de projeto (em .mcp.json ou .github/mcp.json) têm precedência sobre definições no nível do usuário quando os nomes de servidor entram em conflito.

Para obter mais informações, consulte Adicionando servidores MCP para CLI do GitHub Copilot.

`lsp-config.json`

Define servidores LSP (Language Server Protocol) disponíveis no nível do usuário. Esses servidores fornecem inteligência de linguagem (diagnóstico, conclusões etc.) para o agente. Gerencie este arquivo usando o /lsp comando de barra, ou edite-o diretamente.

Para obter mais informações, consulte Adicionando servidores LSP para CLI do GitHub Copilot.

`agents/`

Armazene as definições de agente personalizado pessoal aqui como .agent.md arquivos. Os agentes colocados neste diretório estão disponíveis em todas as suas sessões. Agentes de nível de projeto (dentro de .github/agents/) têm precedência sobre agentes pessoais se compartilharem o mesmo nome.

Para obter mais informações, consulte Criando e usando agentes personalizados para CLI do GitHub Copilot.

`skills/`

Armazene as definições de habilidades personalizadas pessoais aqui. Cada habilidade reside em um subdiretório que contém um SKILL.md arquivo, por exemplo, ~/.copilot/skills/my-skill/SKILL.md. As habilidades pessoais estão disponíveis em todas as suas sessões. Habilidades de nível de projeto têm prioridade sobre habilidades pessoais caso compartilhem o mesmo nome.

Para obter mais informações, consulte Adicionando habilidades de agente para CLI do GitHub Copilot.

`hooks/`

Armazene os scripts de gancho no nível do usuário aqui. Esses ganchos se aplicam a todas as suas sessões. Você também pode definir ganchos em linha no arquivo de configuração do usuário (~/.copilot/config.json) usando a chave hooks. Os ganchos no nível do repositório (in .github/hooks/) são carregados junto com ganchos no nível do usuário.

Para obter mais informações, consulte Usando ganchos com CLI do GitHub Copilot.

Arquivos gerenciados automaticamente

Os itens a seguir são gerenciados pela CLI. Você geralmente não deve editá-los manualmente.

`permissions-config.json`

Armazena as suas decisões de permissão de ferramenta e diretório salvas, organizadas pelo local do projeto. Quando você aprova uma ferramenta ou concede acesso a um diretório, a CLI registra a decisão aqui para que você não seja solicitado novamente no mesmo projeto.

Observação

Se você quiser redefinir permissões para um projeto, poderá excluir a entrada relevante desse arquivo. No entanto, editar o arquivo enquanto uma sessão está em execução pode causar um comportamento inesperado.

`session-state/`

Contém dados de histórico de sessão, organizados por ID de sessão em subdiretórios. Cada diretório de sessão armazena um log de eventos (events.jsonl) e artefatos de workspace (planos, pontos de verificação, arquivos rastreados). Esses dados permitem que a sessão seja retomada (--resume ou --continue).

`session-store.db`

Um banco de dados SQLite usado pela CLI para armazenamento de dados entre sessões, como indexação e buscas de checkpoints. Esse arquivo é gerenciado automaticamente e não deve ser editado.

`logs/`

Contém arquivos de log para sessões da CLI. Cada sessão cria um arquivo de log chamado process-{timestamp}-{pid}.log. Esses arquivos são úteis na depuração de problemas.

Dica

Para localizar o arquivo de log da sessão atual, insira /session em uma sessão interativa. A saída inclui o caminho completo para o arquivo de log, juntamente com outros detalhes da sessão, como a ID da sessão, a duração e o diretório de trabalho.

`installed-plugins/`

Contém os arquivos para plug-ins instalados. Os plug-ins instalados de um marketplace são armazenados em installed-plugins/{marketplace-name}/{plugin-name}/. Os plug-ins instalados diretamente são armazenados em installed-plugins/_direct/. Gerencie plug-ins usando os copilot plugin comandos em vez de editar esse diretório diretamente.

Para obter mais informações, consulte referência de plugin da CLI GitHub Copilot.

`plugin-data/`

Contém dados persistentes para plug-ins instalados, organizados pelo marketplace e pelo nome do plug-in. Esses dados são gerenciados pelos próprios plug-ins e não devem ser editados manualmente.

`ide/`

Contém arquivos de bloqueio e estado para integrações de IDE (por exemplo, quando CLI do Copilot se conecta a Visual Studio Code). Esse diretório é gerenciado automaticamente.

Alterando o local do diretório de configuração

Você pode substituir o local padrão ~/.copilot de duas maneiras:

        **Variável de ambiente**: defina `COPILOT_HOME` como o caminho do diretório que você deseja usar.

Bash

export COPILOT_HOME=/path/to/my/copilot-config

export COPILOT_HOME=/path/to/my/copilot-config

        **Opção de linha de comando**: use `--config-dir` ao iniciar a CLI.

Bash

copilot --config-dir /path/to/my/copilot-config

copilot --config-dir /path/to/my/copilot-config

A --config-dir opção tem precedência sobre COPILOT_HOME, que, por sua vez, tem precedência sobre o local padrão ~/.copilot .

Coisas que devem ser observadas

        `COPILOT_HOME` substitui todo o caminho `~/.copilot`. O valor definido deve ser o caminho completo para o diretório que você deseja usar para os arquivos de configuração e subdiretórios.

Alterar o diretório significa que a configuração existente, o histórico de sessão, os plug-ins instalados e as permissões salvas não serão encontrados no novo local. Copie ou mova o conteúdo de ~/.copilot para o novo local, para preservá-los.
O diretório de cache (usado para caches do marketplace, pacotes de atualização automática e outros dados efêmeros) segue as convenções da plataforma e não é afetado por COPILOT_HOME. Ele está localizado em:
```
        **macOS**: `~/Library/Caches/copilot`
```
- Linux: $XDG_CACHE_HOME/copilot ou ~/.cache/copilot
```
        **Windows**: `%LOCALAPPDATA%/copilot`
```
Para substituir o diretório de cache separadamente, defina COPILOT_CACHE_HOME.

O que você pode excluir com segurança

Item	É seguro excluir?	Efeito
`agents/`

          `skills/`
          `hooks/`
         | Não recomendado | Você perderá suas personalizações pessoais. Faça backup primeiro. |

Configurações do arquivo de configuração

As configurações são aplicadas em cascata, do usuário para o repositório e depois para o local, com níveis mais específicos substituindo os mais gerais. As opções de linha de comando e as variáveis de ambiente sempre têm a precedência mais alta.

Scope	Localidade	Propósito
Usuário	`~/.copilot/settings.json`	Padrões globais para todos os repositórios. Use a variável de `COPILOT_HOME` ambiente para especificar um caminho alternativo.
Repositório	`.github/copilot/settings.json`	Configuração do repositório compartilhado (comitada no repositório).
Local	`.github/copilot/settings.local.json`	Substituições pessoais (adicione-as a `.gitignore`).

Configurações do usuário (`~/.copilot/settings.json`)

Essas configurações se aplicam em todas as suas sessões e repositórios. Você pode editar esse arquivo diretamente ou usar comandos de barra para atualizar valores individuais.

Chave	Tipo	Default	Descrição
`allowedUrls`	`string[]`	`[]`	URLs ou domínios permitidos sem solicitação. Dá suporte a URLs exatas, padrões de domínio e subdomínios curinga (por exemplo, `"*.github.com"`).
`askUser`	`boolean`	`true`	Permitir que o agente faça perguntas esclarecedoras. Defina para `false` para operação totalmente autônoma. Também pode ser definido com `--no-ask-user`.
`autoUpdate`	`boolean`	`true`	Baixe automaticamente as atualizações da CLI.
`autoUpdatesChannel`

          `"stable"`
          \|
          `"prerelease"`
         | `"stable"` | Atualizar canal. Defina para `"prerelease"` receber atualizações de pré-lançamento. |

| banner | "always" | "once" | "never" | "once" | Frequência de exibição de banner animado. | | bashEnv | boolean | false | Habilite suporte para BASH_ENV em shells bash. Também pode ser definido com --bash-env ou --no-bash-env. | | beep | boolean | true | Reproduza um bipe audível quando a atenção é necessária. | | colorMode | "default" | "dim" | "high-contrast" | "colorblind" | "default" | Modo de contraste de cores. Gerenciado pelo comando de barra /theme. | | compactPaste | boolean | true | Colapsar colagens grandes (mais de 10 linhas) em tokens compactos. | | companyAnnouncements | string[] | [] | Mensagens personalizadas mostradas aleatoriamente na inicialização. Uma mensagem é selecionada aleatoriamente sempre que a CLI é iniciada. Útil para anúncios ou lembretes da equipe. | | continueOnAutoMode | boolean | false | Alterne automaticamente para o modo automático quando limitado por taxa. Quando os erros de limite de taxa elegíveis disparam uma troca automática para o modo automático e tentam novamente. Não se aplica a limites de taxa globais ou provedores BYOK. | | copyOnSelect | boolean | true (macOS), false (outros) | Copie automaticamente o texto selecionado pelo mouse para a área de transferência do sistema no modo de tela alternativa. | | customAgents.defaultLocalOnly | boolean | false | Use apenas agentes personalizados locais (nenhuma organização remota ou agentes empresariais). | | deniedUrls | string[] | [] | URLs ou domínios que sempre são negados. As regras de negação têm precedência sobre as regras de permissão. | | disableAllHooks | boolean | false | Desabilite todos os ganchos (nível de repositório e nível de usuário). | | disabledMcpServers | string[] | [] | Nomes de servidor MCP para desabilitar. Os servidores listados são configurados, mas não iniciados. | | disabledSkills | string[] | [] | Nomes de habilidade para desabilitar. As habilidades listadas foram identificadas, mas não carregadas. | | effortLevel | string | "medium" | Nível de esforço de raciocínio para o pensamento estendido: "low", "medium", ou "high"``"xhigh". Níveis mais altos usam mais computação. | | enabledMcpServers | string[] | [] | Habilite servidores MCP internos que estão desabilitados por padrão (por exemplo, "computer-use"). | | enabledPlugins | Record<string, boolean> | {} | Instalação automática do plug-in declarativo. As chaves são especificações de plug-in; os valores são true (habilitados) ou false (desabilitados). | | experimental | boolean | false | Habilitar recursos experimentais. Também pode ser habilitado com a opção --experimental de linha de comando ou o /experimental comando de barra. | | extraKnownMarketplaces | Record<string, {...}> | {} | Marketplaces de plug-in adicionais. Cada chave é um nome do marketplace; o valor especifica a origem ("directory"ou "git"``"github"). | | footer | object | — | Controla quais itens aparecem na linha de status. Subtarefas: showModelEffort, , showDirectory, showBranch, showContextWindow, showQuota, showAgent (todos boolean). Gerenciado pelo comando de barra /statusline. | | hooks | object | — | Definições inline de hooks no nível do usuário, chaveadas pelo nome do evento. Usa o mesmo esquema que os arquivos .github/hooks/*.json. Consulte Usando ganchos com CLI do GitHub Copilot. | | ide.autoConnect | boolean | true | Conecte-se automaticamente a um workspace do IDE na inicialização. Quando false, você ainda pode se conectar manualmente usando o comando /ide. | | ide.openDiffOnEdit | boolean | true | Abre as diferenças de edição nos arquivos no IDE conectado para aprovação. Quando false, as aprovações de edição de arquivo são mostradas somente no terminal. | | includeCoAuthoredBy | boolean | true | Adicione um trailer Co-authored-by às confirmações do git feitas pelo agente. | | logLevel | "none" | "error" | "warning" | "info" | "debug" | "all" | "default" | "default" | Verbosidade de registro em log. | | mergeStrategy | "rebase" | "merge" | — | Estratégia de resolução de conflitos para /pr fix conflicts. Quando definido como "rebase", os conflitos são resolvidos fazendo rebase para o branch base. Quando definido como "merge", o ramo base é mesclado no ramo de funcionalidade. Se não estiver configurado, uma caixa de diálogo de seleção será mostrada. | | model | string | varies | Modelo de IA a ser usado. Defina para "auto" para que Copilot selecione automaticamente o melhor modelo disponível. Gerenciado pelo comando de barra /model. | | mouse | boolean | true | Habilite o suporte ao mouse no modo de tela alternativa. Também pode ser definido com --mouse ou --no-mouse. | | powershellFlags | string[] | ["-NoProfile", "-NoLogo"] | Sinalizadores passados para o PowerShell (pwsh) na inicialização. Apenas para Windows. | | renderMarkdown | boolean | true | Renderizar Markdown na saída do terminal. | | respectGitignore | boolean | true | Exclua os arquivos gitignored do seletor de arquivos mencionados @. Quando false, o seletor inclui arquivos normalmente excluídos por .gitignore. | | screenReader | boolean | false | Habilitar otimizações de leitor de tela. | | skillDirectories | string[] | [] | Diretórios adicionais para pesquisar definições de habilidade personalizadas (além de ~/.copilot/skills/). | | statusLine | object | — | Exibição da linha de status personalizada. type: deve ser "command". command: caminho para um script executável que recebe JSON de sessão no stdin e imprime o conteúdo de status no stdout. padding: quantidade opcional de espaços de preenchimento à esquerda. | | storeTokenPlaintext | boolean | false | Armazene tokens de autenticação em texto sem formatação no arquivo de configuração quando nenhum conjunto de chaves do sistema estiver disponível. | | stream | boolean | true | Habilitar respostas de streaming. | | streamerMode | boolean | false | Ocultar os nomes do modelo de pré-visualização e os detalhes da cota. Útil ao demonstrar CLI do Copilot ou ao compartilhar a tela. | | theme | "auto" | "dark" | "light" | "auto" | Tema de cor do terminal. "auto" detecta a tela de fundo do terminal e escolhe adequadamente. | | updateTerminalTitle | boolean | true | Mostrar a intenção atual na guia do terminal ou no título da janela. |

Configurações do repositório (`.github/copilot/settings.json`)

As configurações do repositório se aplicam a todos que trabalham no repositório. Eles são comprometidos com o repositório e compartilhados com colaboradores.

Somente as chaves listadas na tabela a seguir têm suporte no nível do repositório. Todas as outras chaves, incluindo chaves válidas no arquivo de configuração do usuário, são ignoradas silenciosamente.

Chave	Tipo	Comportamento de mesclagem	Descrição
`companyAnnouncements`	`string[]`	Substituído — o repositório assume precedência	Mensagens mostradas aleatoriamente na inicialização.
`disableAllHooks`	`boolean`	Repositório tem precedência	Desabilite todos os ganchos.
`enabledPlugins`	`Record<string, boolean>`	Mesclado — o repositório tem prioridade sobre o usuário para a mesma chave	Instalação automática do plug-in declarativo.
`extraKnownMarketplaces`	`Record<string, {...}>`	Mesclado — o repositório tem prioridade sobre o usuário para a mesma chave	Marketplaces de plug-in disponíveis neste repositório.
`hooks`	`object`	Concatenados — gatilhos do repositório são executados após os gatilhos do usuário	Definições de gancho destinadas a este repositório. Consulte Usando ganchos com CLI do GitHub Copilot.
`mergeStrategy`

          `"rebase"`
          \|
          `"merge"`
         | Repositório tem precedência | Estratégia de resolução de conflitos para `/pr fix conflicts`. |

Configurações locais (`.github/copilot/settings.local.json`)

Crie .github/copilot/settings.local.json no repositório para ajustes pessoais que não devem ser cometidos. Adicione este arquivo a .gitignore.

O arquivo de configuração local usa o mesmo esquema que o arquivo de configuração do repositório (.github/copilot/settings.json) e tem precedência sobre ele.

Diretório de configuração do GitHub Copilot CLI

Neste artigo

Visão geral do diretório

Arquivos editáveis pelo usuário

`settings.json`

`copilot-instructions.md`

`instructions/`

`mcp-config.json`

`lsp-config.json`

`agents/`

`skills/`

`hooks/`

Arquivos gerenciados automaticamente

`permissions-config.json`

`session-state/`

`session-store.db`

`logs/`

`installed-plugins/`

`plugin-data/`

`ide/`

Alterando o local do diretório de configuração

Coisas que devem ser observadas

O diretório de cache (usado para caches do marketplace, pacotes de atualização automática e outros dados efêmeros) segue as convenções da plataforma e não é afetado por `COPILOT_HOME`. Ele está localizado em:

- Linux: `$XDG_CACHE_HOME/copilot` ou `~/.cache/copilot`

O que você pode excluir com segurança

Configurações do arquivo de configuração

Configurações do usuário (`~/.copilot/settings.json`)

Configurações do repositório (`.github/copilot/settings.json`)

Configurações locais (`.github/copilot/settings.local.json`)

Leitura adicional