nix-home-manager/modules/programs/github-copilot-cli.nix

{
  lib,
  pkgs,
  config,
  ...
}:
let
  inherit (lib)
    literalExpression
    mkEnableOption
    mkIf
    mkOption
    mkPackageOption
    ;

  cfg = config.programs.github-copilot-cli;

  jsonFormat = pkgs.formats.json { };
  json5 = pkgs.python3Packages.toPythonApplication pkgs.python3Packages.json5;

  # Copilot CLI drops trusted_folders from settings.json and moves
  # trustedFolders into its own state in config.json, rewriting settings.json
  # and so replacing a linked file. A merged copy would also outlive its
  # removal from Nix.
  trustedFolderKeys = [
    "trusted_folders"
    "trustedFolders"
  ];
  userSettings = removeAttrs cfg.settings trustedFolderKeys;
  settingsFile = jsonFormat.generate "github-copilot-cli-settings.json" userSettings;

  upstreamConfigDir = "${config.home.homeDirectory}/.copilot";

  # Applied after transformMcpServer so that args = [] is not filtered out.
  forCopilotFormat =
    server:
    let
      isLocal = server.type == "stdio" || server.type == "local";
    in
    server
    // {
      type = if isLocal then "local" else server.type;
    }
    // lib.optionalAttrs isLocal {
      args = server.args or [ ];
    }
    // lib.optionalAttrs (!(server ? tools)) {
      tools = [ "*" ];
    };

  enabledServers = lib.filterAttrs (
    _: server: !(server.disabled or false) && (server ? url || server ? command)
  ) config.programs.mcp.servers;

  transformedMcpServers =
    if cfg.enableMcpIntegration && config.programs.mcp.enable && enabledServers != { } then
      lib.mapAttrs (
        name: server:
        forCopilotFormat (
          lib.hm.mcp.transformMcpServer {
            inherit server;
            extraTransforms = [
              lib.hm.mcp.addType
              (lib.hm.mcp.wrapEnvFilesCommand { inherit pkgs name; })
            ];
          }
        )
      ) enabledServers
    else
      { };

  mergedMcpServers =
    transformedMcpServers
    // lib.mapAttrs (
      name: server:
      forCopilotFormat (
        lib.hm.mcp.transformMcpServer {
          inherit server;
          extraTransforms = [
            lib.hm.mcp.addType
            (lib.hm.mcp.wrapEnvFilesCommand {
              inherit pkgs name;
            })
          ];
        }
      )
    ) cfg.mcpServers;

  normalizeDirectory =
    name: option: source:
    if lib.isPath source then
      source
    else
      pkgs.runCommandLocal name { } ''
        if [[ ! -d ${lib.escapeShellArg (toString source)} ]]; then
          echo ${lib.escapeShellArg "programs.github-copilot-cli.${option} must be a directory"} >&2
          exit 1
        fi
        ln -s ${lib.escapeShellArg (toString source)} "$out"
      '';

  normalizeSkill =
    source:
    pkgs.runCommandLocal "github-copilot-cli-skill" { } ''
      source=${lib.escapeShellArg (toString source)}
      if [[ -d "$source" ]]; then
        ln -s "$source" "$out"
      elif [[ -f "$source" ]]; then
        mkdir "$out"
        ln -s "$source" "$out/SKILL.md"
      else
        echo "GitHub Copilot CLI skill source must be a file or directory: $source" >&2
        exit 1
      fi
    '';
in
{
  meta.maintainers = [ lib.maintainers.ojsef39 ];

  options.programs.github-copilot-cli = {
    enable = mkEnableOption "GitHub Copilot CLI";

    package = mkPackageOption pkgs "github-copilot-cli" { nullable = true; };

    configDir = mkOption {
      type = lib.types.str;
      default =
        if config.home.preferXdgDirectories then "${config.xdg.configHome}/copilot" else upstreamConfigDir;
      defaultText = literalExpression ''
        if config.home.preferXdgDirectories then
          "''${config.xdg.configHome}/copilot"
        else
          "''${config.home.homeDirectory}/.copilot"
      '';
      example = literalExpression ''"''${config.xdg.configHome}/copilot"'';
      description = ''
        Directory holding Copilot CLI configuration files such as
        {file}`settings.json`, {file}`mcp-config.json`,
        {file}`lsp-config.json`, and
        {file}`copilot-instructions.md`.

        Defaults to `''${config.xdg.configHome}/copilot` when
        {option}`home.preferXdgDirectories` is enabled and to `~/.copilot`
        otherwise. The {env}`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>.
      '';
    };

    enableMcpIntegration = mkOption {
      type = lib.types.bool;
      default = false;
      description = ''
        Whether to integrate the MCP servers config from
        {option}`programs.mcp.servers` into
        {option}`programs.github-copilot-cli.mcpServers`.

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

    settings = mkOption {
      type = lib.types.attrsOf jsonFormat.type;
      default = { };
      example = {
        model = "claude-sonnet-4-5";
        theme = "default";
        renderMarkdown = true;
        autoUpdate = false;
      };
      description = ''
        Configuration written to {file}`settings.json` inside
        {option}`programs.github-copilot-cli.configDir`. See
        [](#opt-programs.github-copilot-cli.mutableSettings) for how the file
        is managed. Empty settings leave the file unmanaged.

        Trusted folders (`trusted_folders`, `trustedFolders`) are not user
        settings: Copilot CLI keeps them in its own state, so they are left
        out of the file. Use
        [](#opt-programs.github-copilot-cli.trustedFolders) instead.

        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
        - `allowedUrls`, `deniedUrls` — 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.
      '';
    };

    mutableSettings = mkOption {
      type = lib.types.bool;
      default = false;
      example = true;
      description = ''
        Whether to merge [](#opt-programs.github-copilot-cli.settings) into a
        writable {file}`settings.json` at activation instead of linking it from
        the Nix store.

        A store-linked file prevents the CLI from saving settings normally.
        Versions that replace the file when saving a model or theme replace
        the link, causing a collision on the next activation.

        When enabled, declared values take precedence over existing values,
        keys later removed from [](#opt-programs.github-copilot-cli.settings)
        stay in the file, and comments and formatting are not preserved.
        Turning the option off links the file again. A merged file is replaced
        automatically only when it is byte-identical to the declared settings.
        Other files are left to the normal collision and backup handling.
        If the remaining settings are empty, the file is left unmanaged.
      '';
    };

    trustedFolders = mkOption {
      type = lib.types.listOf lib.types.str;
      default = [ ];
      example = literalExpression ''[ "''${config.home.homeDirectory}/projects" ]'';
      description = ''
        Folders Copilot CLI trusts without asking.

        Copilot CLI keeps trusted folders in its own state file,
        {file}`config.json` inside
        {option}`programs.github-copilot-cli.configDir`, which it also uses for
        login and plugin state. These folders are merged into its
        `trustedFolders` list at activation, and the rest of the file is left
        alone. Folders trusted from inside Copilot CLI are kept, and removing a
        folder here does not untrust it.
      '';
    };

    context = mkOption {
      type = lib.types.either lib.types.lines lib.types.path;
      default = "";
      example = literalExpression ''
        '''
          Review the current workspace before making edits.
          Prefer actionable findings over general commentary.
        '''
      '';
      description = ''
        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
        {file}`copilot-instructions.md` inside
        {option}`programs.github-copilot-cli.configDir`.
      '';
    };

    mcpServers = mkOption {
      type = lib.types.attrsOf jsonFormat.type;
      default = { };
      example = literalExpression ''
        {
          playwright = {
            type = "local";
            command = "npx";
            args = [ "@playwright/mcp@latest" ];
            tools = [ "*" ];
          };
          context7 = {
            type = "http";
            url = "https://mcp.context7.com/mcp";
            tools = [ "*" ];
          };
        }
      '';
      description = ''
        MCP server configurations written to {file}`mcp-config.json` inside
        {option}`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.

        These values are written to the world-readable Nix store, so avoid
        putting API keys or tokens in `headers`, `env`, or other values. For
        a local server that reads a secret from an environment variable, you
        can set `env.<NAME>.file = "/run/secrets/..."` instead; Home Manager
        then wraps the command so it reads the file at startup.

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

    lspServers = mkOption {
      type = lib.types.attrsOf jsonFormat.type;
      default = { };
      example = literalExpression ''
        {
          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";
            };
          };
        }
      '';
      description = ''
        LSP (Language Server Protocol) server configurations written to
        {file}`lsp-config.json` inside
        {option}`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
        {option}`home.packages` when needed.

        See <https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers>
        for the documentation.
      '';
    };

    agents = mkOption {
      type = lib.types.either (lib.types.attrsOf (
        lib.types.oneOf [
          lib.types.lines
          lib.types.path
          lib.types.str
        ]
      )) lib.types.path;
      default = { };
      example = literalExpression ''
        {
          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;
        }
      '';
      description = ''
        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
          {file}`''${configDir}/agents/<name>.agent.md`)
        - A path to a file (creates
          {file}`''${configDir}/agents/<name>.agent.md`)

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

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

    skills = mkOption {
      type = lib.types.either (lib.types.attrsOf (
        lib.types.oneOf [
          lib.types.lines
          lib.types.path
          lib.types.str
        ]
      )) lib.types.path;
      default = { };
      example = literalExpression ''
        {
          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.
          ''';
        }
      '';
      description = ''
        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
          {file}`''${configDir}/skills/<name>/SKILL.md`)
        - A path to a file (creates
          {file}`''${configDir}/skills/<name>/SKILL.md`)
        - A path to a directory (symlinks
          {file}`''${configDir}/skills/<name>/` to that directory)

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

        See <https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#skills-reference>
        for the documentation.
      '';
    };
  };

  config = mkIf cfg.enable {
    assertions = [
      {
        assertion = !lib.isPath cfg.agents || lib.pathIsDirectory cfg.agents;
        message = "`programs.github-copilot-cli.agents` must be a directory when set to a path";
      }
      {
        assertion = !lib.isPath cfg.skills || lib.pathIsDirectory cfg.skills;
        message = "`programs.github-copilot-cli.skills` must be a directory when set to a path";
      }
    ];

    home.packages = mkIf (cfg.package != null) [ cfg.package ];

    warnings = lib.optional (lib.any (key: lib.hasAttr key cfg.settings) trustedFolderKeys) ''
      programs.github-copilot-cli.settings: trusted_folders and trustedFolders
      are not written to settings.json. Copilot CLI keeps trusted folders in
      its own state; use programs.github-copilot-cli.trustedFolders instead.
    '';

    home.activation.githubCopilotCliTrustedFolders = mkIf (cfg.trustedFolders != [ ]) (
      lib.hm.dag.entryAfter [ "linkGeneration" ] (
        lib.hm.generators.mkImpureConfigMerger {
          inherit pkgs;
          format = "json";
          empty = "{}";
          jqOperation = ''
            $dynamic + {
              trustedFolders: (($dynamic.trustedFolders // [ ]) as $have | $have + ($static.trustedFolders - $have))
            }
          '';
          path = "${cfg.configDir}/config.json";
          staticSettings = jsonFormat.generate "github-copilot-cli-trusted-folders.json" {
            inherit (cfg) trustedFolders;
          };
          # Copilot CLI starts config.json with a comment header.
          reader = "${lib.getExe json5} --as-json";
          mode = "600";
          verboseMsg = "Adding trusted folders to ${cfg.configDir}/config.json";
        }
      )
    );

    home.activation.githubCopilotCliSettings = mkIf (cfg.mutableSettings && userSettings != { }) (
      lib.hm.dag.entryAfter [ "linkGeneration" ] (
        lib.hm.generators.mkImpureConfigMerger {
          inherit pkgs;
          format = "json";
          empty = "{}";
          jqOperation = "$dynamic * $static";
          path = "${cfg.configDir}/settings.json";
          staticSettings = settingsFile;
          reader = "${lib.getExe json5} --as-json";
        }
      )
    );

    # Turning mutableSettings off links settings.json again; remove an
    # unchanged merged copy first so the link can replace it.
    home.activation.githubCopilotCliImmutableSettings =
      let
        cleanup = lib.hm.generators.mkImpureConfigCleanup {
          file = config.home.file."${cfg.configDir}/settings.json";
        };
      in
      mkIf (!cfg.mutableSettings && userSettings != { } && cleanup != "") (
        lib.hm.dag.entryBetween [ "linkGeneration" ] [ "writeBoundary" ] cleanup
      );

    home.file = {
      "${cfg.configDir}/settings.json" = mkIf (!cfg.mutableSettings && userSettings != { }) {
        source = settingsFile;
      };

      "${cfg.configDir}/mcp-config.json" = mkIf (mergedMcpServers != { }) {
        source = jsonFormat.generate "github-copilot-cli-mcp-config.json" {
          mcpServers = mergedMcpServers;
        };
      };

      "${cfg.configDir}/lsp-config.json" = mkIf (cfg.lspServers != { }) {
        source = jsonFormat.generate "github-copilot-cli-lsp-config.json" {
          inherit (cfg) lspServers;
        };
      };

      "${cfg.configDir}/copilot-instructions.md" =
        if lib.hm.strings.isPathLike cfg.context then
          { source = cfg.context; }
        else
          mkIf (cfg.context != "") {
            text = cfg.context;
          };

      "${cfg.configDir}/agents" = mkIf (lib.hm.strings.isPathLike cfg.agents) {
        source = normalizeDirectory "github-copilot-cli-agents" "agents" cfg.agents;
        recursive = true;
      };

      "${cfg.configDir}/skills" = mkIf (lib.hm.strings.isPathLike cfg.skills) {
        source = normalizeDirectory "github-copilot-cli-skills" "skills" cfg.skills;
        recursive = true;
      };
    }
    // lib.optionalAttrs (builtins.isAttrs cfg.agents) (
      lib.mapAttrs' (
        name: content:
        lib.nameValuePair "${cfg.configDir}/agents/${name}.agent.md" (
          if lib.hm.strings.isPathLike content then { source = content; } else { text = content; }
        )
      ) cfg.agents
    )
    // lib.optionalAttrs (builtins.isAttrs cfg.skills) (
      lib.mapAttrs' (
        name: content:
        if lib.isPath content && lib.pathIsDirectory content then
          lib.nameValuePair "${cfg.configDir}/skills/${name}" {
            source = content;
            recursive = true;
          }
        else if lib.hm.strings.isPathLike content && !lib.isPath content then
          lib.nameValuePair "${cfg.configDir}/skills/${name}" {
            source = normalizeSkill content;
            recursive = true;
          }
        else
          lib.nameValuePair "${cfg.configDir}/skills/${name}/SKILL.md" (
            if lib.hm.strings.isPathLike content then { source = content; } else { text = content; }
          )
      ) cfg.skills
    );

    home.sessionVariables = mkIf (cfg.configDir != upstreamConfigDir) {
      COPILOT_HOME = cfg.configDir;
    };
  };
}