> For the complete documentation index, see [llms.txt](https://docs.observal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.observal.io/integrations/copilot.md).

# Copilot

Copilot is a first-class Observal harness integration. Observal can install GitHub Copilot agents, configure MCP servers, expose skills, and bridge telemetry hooks.

***

## Overview

Copilot agent profiles are Markdown files stored in `.github/agents/`.

Copilot currently supports project installation scope only. MCP servers, hooks, skills, and agent profiles are managed through the project configuration.

***

## Supported capabilities

| Capability      | Support                               |
| --------------- | ------------------------------------- |
| Agent profiles  | Project scope                         |
| Hook bridge     | Supported                             |
| MCP servers     | `.vscode/mcp.json`                    |
| Skills          | `.github/skills/{name}/SKILL.md`      |
| Session parsing | Built-in `copilot-cli` session parser |
| Default scope   | Project                               |

***

## Setup

### 1. Install the Observal CLI

```bash
uv tool install observal-cli
# or: pipx install observal-cli
```

### 2. Authenticate

```bash
observal auth login
```

This writes credentials to `~/.observal/config.json`.

### 3. Pull an agent into Copilot

```bash
observal agent pull <agent-name> --harness copilot
```

By default, the agent is written to:

```
.github/agents/{name}.agent.md
```

***

## Config paths

| Purpose       | Project scope                    |
| ------------- | -------------------------------- |
| Agent profile | `.github/agents/{name}.agent.md` |
| MCP config    | `.vscode/mcp.json`               |
| Skills        | `.github/skills/{name}/SKILL.md` |
| Hook config   | `.github/hooks/{name}.json`      |

Copilot MCP configuration uses the `servers` key.

***

## Hook spec

### Event map

| Observal event     | Copilot event      |
| ------------------ | ------------------ |
| `SessionStart`     | `SessionStart`     |
| `UserPromptSubmit` | `UserPromptSubmit` |
| `PreToolUse`       | `PreToolUse`       |
| `PostToolUse`      | `PostToolUse`      |
| `Stop`             | `Stop`             |

***

## Session parsing and delivery

Copilot uses the built-in `copilot-cli` server parser while retaining separate source adapters for VS Code Copilot and Copilot CLI. VS Code hook events are durably materialized as JSONL-compatible source records; Copilot CLI discovers its native `events.jsonl` sessions.

Both adapters route through the shared spool-first delivery engine. Hook execution writes to the durable outbox and defers network work, retries keep stable source indexes, and cursors advance only after contiguous server acknowledgement. Recovery uses the authenticated server checkpoint. Finalization audits the complete source hash and rewinds/replays a mismatched range.

***

## Caveats

**Only project scope is supported.** Agents are installed into `.github/agents/`.

**Configuration is split across project directories.** MCP servers are stored in `.vscode/mcp.json`, while hooks and skills live under `.github/`.

**Rules are not supported.** Copilot supports agent profiles, MCP servers, skills, and hooks, but does not expose a rules configuration.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.observal.io/integrations/copilot.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.