## Copilot CLI Documentation

Copilot CLI is GitHub’s AI-powered coding agent for the command line. Entire captures sessions from Copilot CLI, tracking file changes, conversation transcripts, and token usage. The Copilot CLI integration is in preview and may contain bugs.

## Prerequisites

- [Entire CLI installed](https://docs.entire.io/installation)
- [Copilot CLI](https://github.com/features/copilot/cli) installed
- A Git repository with Entire enabled

## Enable

```
entire agent add copilot-cli
copilot
```

`entire agent add copilot-cli` creates `.github/hooks/entire.json`, which Copilot CLI automatically discovers and executes at key lifecycle events.

You can commit `.github/hooks/entire.json` to your repository so your team gets Entire integration automatically.

### How it works

1. **Session Detection** — Copilot CLI fires hooks on session start and end.
2. **Turn Tracking** — each prompt and agent response is captured via hooks.
3. **Checkpoint Creation** — created when you or the agent make a Git commit.
4. **Transcript Capture** — session transcripts are read from Copilot CLI’s JSONL event log.
5. **Session Storage** — data saved to the `entire/checkpoints/v1` branch.

### What gets captured

| Data          | Description                                  |
|---------------|----------------------------------------------|
| Conversation  | Full transcript of prompts and responses     |
| File changes  | All files modified during the session       |
| Token usage   | Input, output, and cache tokens              |
| Timestamps    | Session and checkpoint timing                |
| Checkpoints   | Rewind points within sessions                |

### Features

**Rewind during sessions.** Use `entire checkpoint rewind` to restore to a previous checkpoint during or after a Copilot CLI session. See the [`checkpoint rewind` command reference](https://docs.entire.io/cli-reference/checkpoint#checkpoint-rewind) for full flag documentation.  
  
**Resume previous sessions.** Switch to a session’s branch with `entire session resume BRANCH`. The CLI restores the session log if needed and prints `copilot --resume SESSION_ID`. See the [`session resume` command reference](https://docs.entire.io/cli-reference/sessions#session-resume) for full flag documentation.  
  
**Explain commits.** Inspect any commit or checkpoint with `entire checkpoint explain`. See the [`checkpoint explain` command reference](https://docs.entire.io/cli-reference/checkpoint#checkpoint-explain) for full flag documentation.

The `--generate` flag on `entire checkpoint explain` requires the configured provider CLI, such as Claude CLI, to be installed and authenticated.

### Caveats and limitations

- Token usage is only available in aggregate after the session ends, not mid-session.
- No subagent start hook — only subagent stop events are captured.
- The `userPromptSubmitted` hook fires before `sessionStart` on the first prompt (handled automatically).
- Works best when you commit at logical stopping points, or tell the agent to handle committing.

### Best practices

**Commit at logical points.** Commit when you’ve made meaningful progress:

```
git add .
git commit -m "Implement feature with Copilot assistance"
```

**Review sessions in PRs.** Commits include `Entire-Checkpoint` trailers. Reviewers can click through to view session details — understanding _why_ code was written helps with review.

### Example workflow

```
# 1. Setup
cd my-project
entire agent add copilot-cli

# 2. Start Copilot CLI
copilot

# 3. Work with Copilot
# Ask it to write code, make changes, etc.

# 4. Check session (in another terminal)
entire status

# 5. Rewind if needed
entire checkpoint rewind

# 6. Commit when ready
git add .
git commit -m "Add feature with Copilot"

# 7. Push to see on entire.io
git push
```

## Troubleshooting

### Session not detected

1. Ensure you’re in an Entire-enabled repo: `entire status`
2. Verify hooks are installed: check `.github/hooks/entire.json` exists
3. Make sure Copilot CLI is running from within the repository
4. Run `entire agent add copilot-cli` to reinstall hooks

### No checkpoints created

1. Checkpoints require file changes
2. Make sure Copilot is modifying files in the repository
3. Check your settings in `.entire/settings.json`

### Transcript not captured

1. Verify Copilot CLI is writing events to `~/.copilot/session-state/`
2. Check that the session has a valid `events.jsonl` file
3. Token usage is only fully available after the session ends.