Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

programs.github-copilot-cli.enable

Whether to enable GitHub Copilot CLI.

Type: boolean

Default:

false

Example:

true

Declared by:

programs.github-copilot-cli.enableMcpIntegration

Whether to integrate the MCP servers config from programs.mcp.servers into programs.github-copilot-cli.mcpServers.

Servers defined in programs.mcp.servers are merged with programs.github-copilot-cli.mcpServers, with the latter taking precedence. Disabled servers (where disabled = true) are excluded from the generated configuration.

Type: boolean

Default:

false

Declared by:

programs.github-copilot-cli.package

The github-copilot-cli package to use.

Type: null or package

Default:

pkgs.github-copilot-cli

Declared by:

programs.github-copilot-cli.agents

Custom agents for GitHub Copilot CLI.

This option can either be:

  • An attribute set defining agents
  • A path to a directory containing multiple agent files

If an attribute set is used, the attribute name becomes the agent filename, and the value is either:

  • Inline content as a string (creates ${configDir}/agents/<name>.agent.md)
  • A path to a file (creates ${configDir}/agents/<name>.agent.md)

If a path is used, it is expected to contain agent files. The directory is symlinked to ${configDir}/agents/.

See https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#custom-agents-reference for the documentation.

Type: (attribute set of (strings concatenated with “\n” or absolute path or string)) or absolute path

Default:

{ }

Example:

{
  code-reviewer = ''
    ---
    description: High signal code review for logic, security, and test gaps.
    tools: ["*"]
    ---

    Review the current changes and report only actionable findings.
  '';
  documentation = ./agents/documentation.agent.md;
}

Declared by:

programs.github-copilot-cli.configDir

Directory holding Copilot CLI configuration files such as config.json, mcp-config.json, lsp-config.json, and copilot-instructions.md.

Defaults to ${config.xdg.configHome}/copilot when home.preferXdgDirectories is enabled and to ~/.copilot otherwise. The COPILOT_HOME environment variable is exported automatically whenever the directory differs from the upstream default of ~/.copilot.

See https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference#changing-the-location-of-the-configuration-directory.

Type: string

Default:

if config.home.preferXdgDirectories then
  "${config.xdg.configHome}/copilot"
else
  "${config.home.homeDirectory}/.copilot"

Example:

"${config.xdg.configHome}/copilot"

Declared by:

programs.github-copilot-cli.context

Global instructions for GitHub Copilot CLI.

The value is either:

  • Inline content as a string
  • A path to a file containing the content

The configured content is written to copilot-instructions.md inside programs.github-copilot-cli.configDir.

Type: strings concatenated with “\n” or absolute path

Default:

""

Example:

''
  Review the current workspace before making edits.
  Prefer actionable findings over general commentary.
''

Declared by:

programs.github-copilot-cli.lspServers

LSP (Language Server Protocol) server configurations written to lsp-config.json inside programs.github-copilot-cli.configDir.

Each attribute defines a server entry under lspServers in the config file. Supported fields include:

  • command — command used to start the LSP server
  • args — arguments passed to the command
  • fileExtensions — map of file extensions to language IDs
  • env — environment variables for the server process
  • rootUri — server root directory relative to the Git root
  • initializationOptions — custom startup options
  • requestTimeoutMs — request timeout in milliseconds

Language server packages are not installed automatically. Add them to home.packages when needed.

See https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-lsp-servers for the documentation.

Type: attribute set of (JSON value)

Default:

{ }

Example:

{
  typescript = {
    command = "typescript-language-server";
    args = [ "--stdio" ];
    fileExtensions = {
      ".ts" = "typescript";
      ".tsx" = "typescriptreact";
      ".js" = "javascript";
      ".jsx" = "javascriptreact";
    };
  };
  python = {
    command = lib.getExe' pkgs.pyright "pyright-langserver";
    args = [ "--stdio" ];
    fileExtensions = {
      ".py" = "python";
      ".pyw" = "python";
      ".pyi" = "python";
    };
  };
}

Declared by:

programs.github-copilot-cli.mcpServers

MCP server configurations written to mcp-config.json inside programs.github-copilot-cli.configDir.

Each attribute defines a server entry under mcpServers in the config file. Supported server types:

  • local — starts a local process via stdio (command, optional args, env)
  • http — connects to a remote HTTP server (url, optional headers)
  • sse — legacy HTTP with Server-Sent Events (same structure as http)

The tools field accepts ["*"] to enable all tools or a list of specific tool names.

See https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers for the documentation.

Type: attribute set of (JSON value)

Default:

{ }

Example:

{
  playwright = {
    type = "local";
    command = "npx";
    args = [ "@playwright/mcp@latest" ];
    tools = [ "*" ];
  };
  context7 = {
    type = "http";
    url = "https://mcp.context7.com/mcp";
    headers = { CONTEXT7_API_KEY = "YOUR-API-KEY"; };
    tools = [ "*" ];
  };
}

Declared by:

programs.github-copilot-cli.settings

Configuration written to config.json inside programs.github-copilot-cli.configDir.

Known configuration keys include:

  • model — AI model selection
  • effortLevel — reasoning effort for capable models
  • theme — "default", "dim", "high-contrast", or "colorblind"
  • mouse — enable mouse support (default: true)
  • banner — frequency of animated banner display
  • renderMarkdown — markdown rendering toggle (default: true)
  • screenReader — accessibility optimizations (default: false)
  • autoUpdate — automatic CLI updates (default: true)
  • stream — token-by-token response streaming (default: true)
  • includeCoAuthoredBy — agent commit attribution (default: true)
  • respectGitignore — exclude gitignored files from file picker
  • trusted_folders — list of pre-approved directory paths
  • allowed_urls, denied_urls — URL allowlists/blocklists
  • logLevel — log verbosity
  • disableAllHooks — global hook disable toggle
  • hooks — inline hook definitions
  • enabledFeatureFlags — enable or disable specific feature flags

See https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference for the documentation.

Type: attribute set of (JSON value)

Default:

{ }

Example:

{
  autoUpdate = false;
  model = "claude-sonnet-4-5";
  renderMarkdown = true;
  theme = "default";
  trusted_folders = [
    "/home/user/projects"
  ];
}

Declared by:

programs.github-copilot-cli.skills

Custom skills for GitHub Copilot CLI.

This option can be either:

  • An attribute set defining skills
  • A path to a directory containing skill folders

If an attribute set is used, the attribute name becomes the skill directory name, and the value is either:

  • Inline content as a string (creates ${configDir}/skills/<name>/SKILL.md)
  • A path to a file (creates ${configDir}/skills/<name>/SKILL.md)
  • A path to a directory (symlinks ${configDir}/skills/<name>/ to that directory)

If a path is used, it is expected to contain one folder per skill name, each containing a SKILL.md. The directory is symlinked to ${configDir}/skills/.

See https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#skills-reference for the documentation.

Type: (attribute set of (strings concatenated with “\n” or absolute path or string)) or absolute path

Default:

{ }

Example:

{
  data-analysis = ./skills/data-analysis;
  release-notes = ''
    ---
    name: release-notes
    description: Draft release notes from commits and pull requests.
    ---

    Summarize user-visible changes and call out migrations.
  '';
}

Declared by: