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

> Learn to configure Copilot suggestions language and context using the Copilot SDK. Customize system messages to control identifiers and environment context for better code completions.

- Repository: [GitHub/copilot-sdk](https://github.com/github/copilot-sdk)
- Tags: how-to-guide
- Published: 2026-07-20

---

**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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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.

```typescript
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.

```typescript
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`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/client.ts) at line 1330, this mode merges your overrides with the SDK's base configuration.

```typescript
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

```python
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

```go
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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/client.ts) around line 1330.

The test suite in [`nodejs/test/e2e/session_config.e2e.test.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/test/e2e/session_config.e2e.test.ts) validates custom system message handling, while [`nodejs/test/toolSet.test.ts`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/types.ts) for interface definitions and [`nodejs/src/client.ts`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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.