How to Configure Copilot Suggestions (Language and Context) via the Copilot SDK

You configure Copilot suggestions by customizing the systemMessage parameter when creating a session, using append, replace, or customize mode to control the language identifier and environment context passed to the underlying model.

The GitHub Copilot SDK enables fine-grained control over AI-generated code completions by allowing you to shape the prompts that drive the Copilot CLI. By configuring the system message when initializing a session, you can explicitly define the programming language, surrounding codebase context, and environmental parameters that influence suggestion generation.

How the Copilot SDK Manages Suggestion Context

The SDK constructs a system message for every session that acts as the foundation for all suggestions. This message includes an environment_context block containing the current working directory, operating system, git root, available tools, and crucially, the preferred language identifier.

According to the source code in nodejs/src/client.ts, the SDK automatically builds this context when sessions are created, but exposes three distinct modes for customization: append, replace, and customize.

The Three Configuration Modes

• Append (default): The SDK builds its standard foundation prompt and appends your custom text. Ideal for quick instructions like "Prefer concise TypeScript snippets."

• Replace: Your content completely substitutes the SDK's system message. Use this when you need total control over the prompt but must manually replicate safety guardrails.

• Customize: You override specific sections (such as environment_context) while preserving the rest of the SDK-managed structure. This is the recommended approach for modifying language context without losing built-in safety features.

Configuring Language Context via SystemMessageCustomizeConfig

To explicitly set or modify the language used for suggestions, target the environment_context section exposed by SystemMessageCustomizeConfig in nodejs/src/types.ts. This section normally auto-detects the language from the current file, but you can override it to force Python, TypeScript, Go, or any other language identifier.

Append Mode: Adding Language Hints

Use append mode when you want to nudge the model toward a specific language without replacing the entire context infrastructure.

import { CopilotClient } from "@github/copilot";

const client = new CopilotClient();

await client.session.create({
  systemMessage: {
    mode: "append",
    content: "When generating code, always use TypeScript syntax and prefer interface over type aliases."
  }
});

Replace Mode: Complete Prompt Control

Use replace mode to supply a fully custom system prompt that overrides all SDK defaults, including language detection.

await client.session.create({
  systemMessage: {
    mode: "replace",
    content: `
You are a helpful assistant.
Generate **Python** code only.
Do not mention other languages or provide explanations.
`
  }
});

Customize Mode: Targeting Environment Context

Customize mode allows surgical modification of the environment_context section. As implemented in nodejs/src/client.ts at line 1330, this mode merges your overrides with the SDK's base configuration.

await client.session.create({
  systemMessage: {
    mode: "customize",
    sections: {
      environment_context: {
        action: "replace",
        content: "CWD=/my/project, OS=linux, gitRoot=/my/project, language=JavaScript"
      }
    },
    content: "Prefer concise snippets."
  }
});

Multi-Language SDK Examples

The Copilot SDK supports multiple languages. Below are implementations in Python and Go that demonstrate the customize mode for language context.

Python Implementation

from copilot import CopilotClient

client = CopilotClient()
await client.session.create(
    system_message={
        "mode": "customize",
        "sections": {
            "environment_context": {
                "action": "replace",
                "content": "language=Python, cwd=/app, os=linux, gitRoot=/app"
            }
        }
    }
)

Go Implementation

package main

import (
    "context"
    "github.com/github/copilot-sdk-go/copilot"
)

func main() {
    ctx := context.Background()
    client := copilot.NewClient()
    
    _, err := client.SessionCreate(ctx, copilot.SessionConfig{
        SystemMessage: copilot.SystemMessageCustomizeConfig{
            Mode: "customize",
            Sections: map[copilot.SystemMessageSection]copilot.SectionOverride{
                copilot.EnvironmentContext: {
                    Action:  "replace",
                    Content: "language=Go, cwd=/src, os=darwin",
                },
            },
        },
    })
}

Source Code Reference

The system message configuration is defined in nodejs/src/types.ts, which exports SystemMessageConfig and SystemMessageCustomizeConfig. The runtime logic that processes these configurations—specifically the merging of custom sections and injection of environment_context—resides in nodejs/src/client.ts around line 1330.

The test suite in nodejs/test/e2e/session_config.e2e.test.ts validates custom system message handling, while nodejs/test/toolSet.test.ts (line 267) demonstrates how the SDK automatically adds or removes the environment_context section based on configuration.

Summary

• The Copilot SDK controls suggestions through a configurable system message passed during session creation.
• Use append mode for quick language hints, replace mode for total prompt control, or customize mode for surgical context modification.
• The environment_context section contains the language identifier; override it via SystemMessageCustomizeConfig to force specific languages.
• Reference nodejs/src/types.ts for interface definitions and nodejs/src/client.ts for implementation details.

Frequently Asked Questions

How do I force Copilot to suggest code in a specific language using the SDK?

Set the systemMessage mode to customize and override the environment_context section, setting the language parameter to your target language (e.g., language=Python). Alternatively, use append mode to add instructions like "Generate Python code only."

What is the difference between replace and customize mode in the Copilot SDK?

Replace mode substitutes the entire system message with your custom text, removing all SDK-managed guardrails and context. Customize mode allows you to override specific sections (like environment_context) while preserving the rest of the SDK's built-in safety and context management.

Can I remove language context entirely to get generic suggestions?

Yes. In customize mode, set the environment_context action to replace with content that omits the language field, or use an empty string. According to tests in nodejs/test/toolSet.test.ts, the SDK supports removing this section to generate language-agnostic completions.

Which source file defines the SystemMessageCustomizeConfig interface?

The interface is defined in nodejs/src/types.ts in the GitHub Copilot SDK repository. This file contains the TypeScript definitions for all system message configuration options, including the sections map and environment_context overrides.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}