# GitHub Copilot Integration

AVELIN API works with [GitHub Copilot](https://github.com/features/copilot) via the **Bring Your Own Key (BYOK)** feature. This lets you route Copilot's Chat and Agent mode through AVELIN's frontier models — combining Copilot's deep VS Code integration with AVELIN's 1M-token context, model diversity, and competitive pricing.

> **Why AVELIN + GitHub Copilot?** Unlock Copilot's Agent mode with frontier coding models, 1M-token context windows, and automatic failover — while keeping the Copilot UI and workflows you already know.

---

## Prerequisites

Before setting up AVELIN with Copilot BYOK, ensure you have:

- **GitHub Copilot subscription** (Individual, Business, or Enterprise)
- **BYOK enabled** in your Copilot settings (available for Copilot Individual and Business plans)
- **VS Code** with the GitHub Copilot and Copilot Chat extensions installed
- **AVELIN API key** from [avelin.ai](https://avelin.ai)

:::note
BYOK (Bring Your Own Key) is a Copilot feature that allows custom API endpoints. Check [GitHub's documentation](https://docs.github.com/en/copilot) for the latest availability and plan requirements.
:::

---

## Quick Setup

### Step 1: Get your AVELIN API key

Sign up at [avelin.ai](https://avelin.ai) and generate an API key. It will look like `sk-ave...xxxx`.

### Step 2: Install GitHub Copilot

1. Open VS Code
2. Go to Extensions (`Cmd+Shift+X` / `Ctrl+Shift+X`)
3. Install **GitHub Copilot** and **GitHub Copilot Chat**
4. Sign in with your GitHub account

### Step 3: Configure BYOK in VS Code

Open your VS Code `settings.json` (Cmd+Shift+P → "Preferences: Open User Settings (JSON)") and add the AVELIN custom model configuration:

```json
{
  "chat.experimental.modelProvider": {
    "openai-compatible": {
      "name": "AVELIN",
      "baseUrl": "https://api.avelin.ai/v1",
      "apiKey": "sk-ave...xxxx"
    }
  },
  "github.copilot.chat.models": [
    {
      "id": "avelin-coding-pro",
      "name": "AVELIN Coding Plus",
      "url": "https://api.avelin.ai/v1",
      "apiKey": "sk-ave...xxxx",
      "maxOutputTokens": 65536
    },
    {
      "id": "avelin-coding-fast",
      "name": "AVELIN Coding",
      "url": "https://api.avelin.ai/v1",
      "apiKey": "sk-ave...xxxx",
      "maxOutputTokens": 65536
    },
    {
      "id": "avelin-fast",
      "name": "AVELIN Fast",
      "url": "https://api.avelin.ai/v1",
      "apiKey": "sk-ave...xxxx",
      "maxOutputTokens": 16384
    }
  ]
}
```

:::tip
The exact settings key names may vary as GitHub updates the BYOK feature. Check [GitHub Copilot docs](https://docs.github.com/en/copilot) for the current configuration format. The key principle is pointing the custom model endpoint to AVELIN's OpenAI-compatible API.
:::

### Step 4: Select Your Model

1. Open the Copilot Chat panel
2. Click the model dropdown at the top of the chat
3. Select your AVELIN model (e.g., **AVELIN Coding Plus**)
4. Start chatting or switch to **Agent** mode

---

## Recommended Models

### Primary Recommendation: `avelin-coding-pro`

For Copilot Chat and Agent mode:

| Feature | avelin-coding-pro | Why it matters for Copilot |
|---|---|---|
| **Context window** | **1M tokens** | Large codebases in Agent mode without context loss |
| **Max output** | **65K tokens** | Generate large files and multi-step implementations |
| **Throughput** | **~100 tokens/sec** | 2× faster than standard tiers — responsive interactions |
| **Reasoning** | Deep step-by-step thinking | Catches subtle bugs in complex codebases |
| **Tool calling** | First-class support | Reliable multi-file edits in Agent mode |

### Alternative Models

| Model | When to use |
|---|---|
| `avelin-coding-fast` | Lighter coding tasks, quick questions — saves cost on simple work |
| `avelin-coding-ultra` | System design, architecture reviews, security-sensitive refactors |
| `avelin-fast` | Quick lookups and simple completions — lowest cost, fastest response |

---

## Why AVELIN for GitHub Copilot?

### 1. **Cost Optimization**

Copilot Chat and Agent mode make many API calls per session. AVELIN optimizes costs:

- **Prompt caching**: ~80% cost reduction on repeated system prompts
- **Competitive pricing**: Lower per-token costs than direct provider APIs
- **Pay-per-token**: Only pay for what you use, no per-seat overhead beyond your Copilot subscription

### 2. **Model Diversity**

Access multiple frontier coding models through one endpoint. AVELIN routes your requests to a diverse set of frontier models across multiple cloud providers, ensuring high availability and consistent quality. If one provider is slow or unavailable, your request automatically routes to the next best option.

### 3. **Reliability**

- **Automatic failover**: If one provider is slow or down, AVELIN switches to another
- **Retry logic**: Transient errors are handled automatically
- **99.9% uptime**: Enterprise-grade infrastructure

### 4. **1M Context Windows**

Copilot's Agent mode accumulates context across file reads, terminal outputs, and multi-step edits. AVELIN's 1M-token context windows enable longer, more capable agentic sessions.

---

## Example Workflows

### Agent Mode: Feature Implementation

Switch Copilot to **Agent** mode for autonomous multi-step tasks:

```
Copilot Agent:

You> Add input validation to all API endpoints using Zod schemas.
     Update the error handling to return proper validation errors.

Agent: I'll add Zod validation to your API endpoints.

[Reads src/routes/users.ts]
[Reads src/routes/posts.ts]
[Reads src/middleware/errorHandler.ts]

I can see 5 endpoints that need validation. Let me implement schemas
and update each route...

[Creates src/schemas/user.schema.ts]
[Creates src/schemas/post.schema.ts]
[Updates src/routes/users.ts with validation middleware]
[Updates src/routes/posts.ts with validation middleware]
[Updates src/middleware/errorHandler.ts for ZodError]
[Runs tests — all passing]

Done! All 5 endpoints now validate input with Zod schemas.
```

### Chat: Code Explanation and Refactoring

```
You: /explain @src/services/cache.ts

Copilot: This file implements a multi-layer caching service...

[Provides detailed explanation]

You: Refactor it to support cache invalidation by tags.

Copilot: I'll add tag-based invalidation...

[Shows refactored code with tag support]
```

### Inline Suggestions

For inline completions (Tab completions), Copilot uses its built-in model. AVELIN enhances the **Chat** and **Agent** modes where custom models are supported.

---

## Advanced Configuration

### Environment-Based Configuration

Use VS Code workspace settings (`.vscode/settings.json`) to configure AVELIN per project:

```json
{
  "github.copilot.chat.models": [
    {
      "id": "avelin-coding-pro",
      "name": "AVELIN Coding Plus",
      "url": "https://api.avelin.ai/v1",
      "apiKey": "${env:AVELIN_API_KEY}",
      "maxOutputTokens": 65536
    }
  ]
}
```

Set `AVELIN_API_KEY` in your environment or `.env` file to avoid committing secrets.

### Custom Instructions for Copilot Chat

Add project-specific instructions via VS Code settings:

```json
{
  "github.copilot.chat.codeGeneration.instructions": [
    "Use TypeScript with strict mode",
    "Write JSDoc comments for all public functions",
    "Use async/await for all async operations",
    "Follow the repository pattern for database access"
  ]
}
```

### Using with Copilot Workspace

If you use GitHub Copilot Workspace for planning, you can reference AVELIN models in your workflow:

1. Plan features using `avelin-coding-ultra` for architectural decisions
2. Implement using `avelin-coding-pro` in Agent mode for code generation
3. Review using `avelin-coding-fast` for quick code review passes

---

## Troubleshooting

| Issue | Solution |
|---|---|
| **Model not showing in dropdown** | Restart VS Code after updating `settings.json`. Ensure the model ID and URL are correct. |
| **"API key invalid"** | Verify your AVELIN API key starts with `sk-ave` and is active |
| **BYOK option not available** | Check that your Copilot plan supports BYOK. Contact GitHub support if needed. |
| **Agent mode not working** | Ensure Agent mode is enabled in Copilot Chat. Try switching models — `avelin-coding-pro` has best tool support. |
| **Slow responses** | Try `avelin-fast` for quicker responses on simple tasks |
| **Tool calls failing in Agent mode** | Use `avelin-coding-pro` — it has first-class function calling |
| **"Model not found" error** | Verify the model ID exactly: `avelin-coding-pro`, `avelin-coding-fast`, `avelin-fast` |
| **Settings not taking effect** | Some BYOK settings require VS Code restart. Check Output panel > GitHub Copilot for errors. |

---

## Related

- [API Quickstart](../../api/quickstart.md) — First API call in 5 minutes
- [Cursor Guide](cursor.md) — AI-first code editor (VS Code fork)
- [Windsurf Guide](windsurf.md) — Codeium's AI-first IDE
- [Cline Guide](cline.md) — Autonomous coding agent in VS Code
- [Model Catalog](../../models/README.md) — Full model comparison
- [GitHub Copilot Docs](https://docs.github.com/en/copilot) — Official Copilot documentation