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.

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. Em uma sessão, você pode usar o comando interativo /settings para alterar valores específicos ou executar /settings KEY VALUE para definir um único valor ou editar o arquivo diretamente em um editor de texto. O arquivo dá suporte a JSON com comentários (JSONC).

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.

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/settings.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.

extensions/

Armazene arquivos de extensão no nível do usuário aqui. As extensões neste diretório estão disponíveis entre sessões.

Você pode criar arquivos neste diretório manualmente ou criar uma extensão e editar o arquivo gerado.

Arquivos gerenciados automaticamente

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

config.json

Armazena o estado do aplicativo interno que é gerenciado automaticamente pela CLI, incluindo dados de autenticação, metadados de plug-in instalados e outras informações de runtime. Normalmente, não é necessário editar esse arquivo.

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 para o local atual, a CLI registra a decisão aqui para que você não seja solicitado novamente no mesmo repositório ou diretório.

Local do arquivo

CLI do Copilot resolve o arquivo do diretório de configuração.

A --config-dir opção é uma opção herdada. Prefira COPILOT_HOME quando precisar alterar o diretório de configuração.

No Windows, o arquivo padrão normalmente é:

C:\Users\YOUR-USER\.copilot\permissions-config.json

Builds mais antigos usavam um arquivo sem extensão chamado permissions-config. Se permissions-config.json não existir, mas o arquivo sem extensão existir, a CLI ainda continuará usando o arquivo legado. Use permissions-config.json para novas edições.

Os locais anteriores de configuração baseados em XDG são migrados para ~/.copilot na inicialização quando COPILOT_HOME não está definido.

Chaves de localização

O objeto de nível locations superior é chaveado por um caminho absoluto.

• Para um repositório Git, use a raiz do Git como base para definir o escopo das permissões.
• As worktrees vinculadas apontam para a raiz do repositório principal, portanto compartilham permissões com a worktree principal.
• Os submódulos usam seu próprio diretório de trabalho.
• Para um diretório que não esteja em um repositório Git, use o diretório de trabalho atual normalizado.

A chave deve corresponder ao local em que CLI do Copilot está em execução. Se a chave não corresponder, as aprovações salvas não serão aplicadas.

A CLI carrega as aprovações do local correspondente quando uma sessão é iniciada e quando o diretório de trabalho ativo é alterado.

Schema

O arquivo deve conter um objeto JSON.

permissions-config.json não dá suporte a regras de negação, regras de "pergunta", modos padrão, regras de URL, filtragem de ferramentas ou política compartilhada local do repositório. Para esses comportamentos, use opções de linha de comando, como --deny-tool, --available-tools, , --excluded-toolse --allow-url``--deny-url. As regras de URL salvas são armazenadas em settings.json, não em permissions-config.json.

Campos desconhecidos não fazem parte do esquema. A CLI pode ignorá-las, e operações de gravação subsequentes podem removê-las.

Tipos de aprovação

Cada item em tool_approvals deve ser um dos seguintes objetos.

Para aprovações do MCP, serverName deve corresponder exatamente ao nome do servidor MCP configurado. Use o nome original do servidor da sua configuração do MCP, não um prefixo de nome de ferramenta sanitizado.

Correspondência de comandos do Shell

commandIdentifiers correspondem aos identificadores de comando extraídos de uma solicitação de shell. A correspondência é exata, exceto pelo :* sufixo.

O sufixo :* não é um padrão glob genérico. Ele corresponde ao tronco exato ou ao tronco seguido por um espaço e mais texto.

Correspondência de diretórios

allowed_directories as entradas permitem CLI do Copilot acessar caminhos dentro desses diretórios sem um prompt de caminho separado. Eles não aprovam a operação da ferramenta em si. Por exemplo, editar um arquivo em um diretório permitido ainda pode exigir uma write aprovação.

Cada allowed_directories entrada deve ser um diretório absoluto, não vazio e acessível. A CLI resolve os symlinks antes de comparar caminhos, bloqueia caminhos de rede UNC, a menos que sejam caminhos locais de comprimento estendido, compara caminhos sem diferenciar maiúsculas de minúsculas em Windows e compara caminhos de forma sensível a maiúsculas de minúsculas em outras plataformas. Se uma entrada não puder ser aplicada, a CLI registrará um aviso e ignorará essa entrada.

Exemplos

Permitir todos os subcomandos git e acessar um diretório local extra:

{
  "locations": {
    "C:\\src\\my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": ["git:*"]
        }
      ],
      "allowed_directories": ["C:\\src\\shared-docs"]
    }
  }
}

{
  "locations": {
    "C:\\src\\my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": ["git:*"]
        }
      ],
      "allowed_directories": ["C:\\src\\shared-docs"]
    }
  }
}

Permitir comandos selecionados, enquanto ainda solicita confirmação antes de gravações em arquivos:

{
  "locations": {
    "/Users/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": [
            "git status",
            "git diff",
            "git log",
            "npm test",
            "npm run build"
          ]
        }
      ]
    }
  }
}

{
  "locations": {
    "/Users/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": [
            "git status",
            "git diff",
            "git log",
            "npm test",
            "npm run build"
          ]
        }
      ]
    }
  }
}

Aprovar gravações de arquivo e um servidor MCP para um repositório:

{
  "locations": {
    "/home/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "write"
        },
        {
          "kind": "mcp",
          "serverName": "github-mcp-server",
          "toolName": null
        }
      ]
    }
  }
}

{
  "locations": {
    "/home/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "write"
        },
        {
          "kind": "mcp",
          "serverName": "github-mcp-server",
          "toolName": null
        }
      ]
    }
  }
}

Aprove uma ferramenta MCP, gravações na memória e acesso às permissões da extensão:

{
  "locations": {
    "C:\\src\\my-repo": {
      "tool_approvals": [
        {
          "kind": "mcp",
          "serverName": "github-mcp-server",
          "toolName": "search_code"
        },
        {
          "kind": "memory"
        },
        {
          "kind": "extension-permission-access",
          "extensionName": "my-extension"
        }
      ]
    }
  }
}

{
  "locations": {
    "C:\\src\\my-repo": {
      "tool_approvals": [
        {
          "kind": "mcp",
          "serverName": "github-mcp-server",
          "toolName": "search_code"
        },
        {
          "kind": "memory"
        },
        {
          "kind": "extension-permission-access",
          "extensionName": "my-extension"
        }
      ]
    }
  }
}

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).

Excluir arquivos desse diretório remove apenas cópias locais. Se você tiver sincronizado sessões com sua GitHub conta, os dados sincronizados serão armazenados separadamente e não serão afetados pela exclusão de arquivo local. Você pode excluir ou ocultar sessões sincronizadas de GitHub.com. Para obter mais informações, consulte Sobre os dados de sessão CLI do GitHub Copilot.

command-history-state/

Contém dados de histórico de comandos usados para pesquisa reversa (Ctrl+R) e navegação de histórico na interface interativa. Esse diretório é gerenciado automaticamente e não deve ser editado.

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.

Se você excluir esse arquivo, poderá recompilá-lo usando o /chronicle reindex comando. A reindexação também sincroniza seus dados de sessão com sua conta.

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.

A CLI também pode criar logs específicos de extensão em logs/extensions/.

Isso é separado do ~/.copilot/extensions/, que armazena o código de extensão criado pelo usuário.

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.

mcp-oauth-config/

Contém arquivos de contingência do token OAuth do MCP, de registro e de PKCE quando o armazenamento com suporte do chaveiro não está disponível. Esse diretório é gerenciado automaticamente.

mcp-secrets/

Inclui armazenamento de arquivos de contingência e um índice para marcadores de posição de segredos do MCP quando o armazenamento baseado em chaveiro não está disponível. Esse diretório é gerenciado automaticamente.

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

Para substituir o local padrão ~/.copilot , defina a COPILOT_HOME variável de ambiente para o caminho do diretório que você deseja usar.

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

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

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

Configurações do arquivo de configuração

As configurações são aplicadas nesta ordem (as posteriores substituem as anteriores):

1. Padrões integrados
2. Configurações gerenciadas por MDM (gerenciamento de dispositivos móveis)
3. Configurações do usuário (~/.copilot/settings.json)
4. Configurações do repositório (.github/copilot/settings.json)
5. Configurações locais (.github/copilot/settings.local.json)
6. Variáveis de ambiente
7. Sinalizadores de linha de comando

As configurações gerenciadas por MDM são carregadas durante a inicialização e mescladas com as configurações do usuário como linha de base da política. Para a maioria das chaves, as configurações do usuário podem substituir essa linha de base. Para permissions.disableBypassPermissionsMode, um valor MDM de "disable" sempre prevalece. Para obter mais informações, consulte as configurações gerenciadas do MDM.

A interface de linha de comando também lê .claude/settings.json e .claude/settings.local.json para o subconjunto compartilhado entre ferramentas das configurações do repositório (como companyAnnouncements, disableAllHooks, enabledPlugins, extraKnownMarketplaces e hooks).

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

Essas configurações se aplicam em todas as suas sessões e repositórios. Você pode usar o /settings comando barra para executar uma caixa de diálogo interativa ou usar comandos de barra específicos para atualizar valores individuais ou editar esse arquivo diretamente.

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.

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

Crie .github/copilot/settings.local.json no repositório para configurações pessoais que não devem ser confirmadas. 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.

Configurações gerenciadas de MDM

Os administradores de TI podem implantar a política de base por meio de configurações gerenciadas por MDM (Mobile Gerenciamento de Dispositivos), em vez de exigir configuração individual por usuário. Essas configurações aplicam padrões no nível do dispositivo para chaves compatíveis e são carregadas antes das configurações do usuário.

Fontes de configurações gerenciadas do MDM

CLI do Copilot lê as configurações gerenciadas de locais específicos do MDM ou de arquivos específicos da plataforma.

Formato de arquivo

Escreva configurações gerenciadas baseadas em arquivo como JSON.

{
    "permissions": {
        "disableBypassPermissionsMode": "disable"
    }
}

Chaves com suporte

Somente as chaves a seguir têm suporte nas configurações gerenciadas do MDM.

Leitura adicional

• CLI do GitHub Copilot
• referência de comando da CLI GitHub Copilot
• referência programática do GitHub Copilot CLI
• referência de plugin da CLI GitHub Copilot
• Referência de ganchos do GitHub Copilot