github / github/copilot-cli

[Bug]Custom agent appears duplicated in selection list and fails to load after restart

Open
#2,475 0 comments 0 reactions 0 assignees View on GitHub
area:agents
Dominant language
Shell
Stars
11.2k
Forks
1.9k
Avg merge
14h 16m
Merged PRs (30d)
6

Description

### Describe the bug

## Summary

When a custom agent's **filename** differs from its **frontmatter `name` field**, two issues occur:

1. The agent appears **duplicated** in the `/agent` selection menu (one entry from the filename, one from the `name` field).
2. After session restart, the CLI fails to find the previously selected agent with error: `Custom agent "xxx" not found`.

## Environment

- **GitHub Copilot CLI version**: v1.0.16-1
- **Model**: Claude Opus 4.6 (6x) (high)
- **OS**: Ubuntu 24.04.4 LTS (WSL2) on Windows
- **Kernel**: Linux 6.6.87.2-microsoft-standard-WSL2 aarch64
- **Node.js**: v24.14.0
- **Agent directory**: `~/.copilot/agents/`

## Agent Configuration

Two custom agent files exist in `~/.copilot/agents/`:

| File | Frontmatter `name` |
| ------------------ | ----------------------------- |
| `azure-expert.md` | `azure-solution-expert` |
| `azure-aws-doc.md` | `azure-vs-aws-compare-expert` |

Note: the **filename** and the **`name` field in frontmatter** are intentionally different.

## Steps to Reproduce

### Bug 1: Duplicate agent entry

1. Create a custom agent file at `~/.copilot/agents/azure-expert.md` with frontmatter `name: azure-solution-expert`
2. Start `ghcp`
3. Run `/agent` to open the agent selection menu

**Expected**: The agent should appear **once** in the list.

**Actual**: The agent appears **twice**:

```
Select Agent:
1. Default (deselect current agent)
> 2. azure-solution-expert (current)
3. azure-solution-expert · user <-- duplicate
4. azure-vs-aws-compare-expert · user
```

### Bug 2: Agent not found after restart

1. Select the custom agent `azure-solution-expert` via `/agent`
2. Restart the CLI session (close and reopen, or the session restarts automatically)

**Expected**: The agent should be loaded successfully on restart.

**Actual**: Error message on startup:

```
✗ Custom agent "azure-solution-expert" not found. Available agents: azure-aws-doc, azure-expert
● Environment loaded: 5 MCP servers, 1 skill, 2 agents
● Selected custom agent: azure-solution-expert
```

The "Available agents" list uses **filenames** (`azure-aws-doc`, `azure-expert`), but the persisted selection uses the **frontmatter `name`** (`azure-solution-expert`). The lookup fails because these don't match.

## Root Cause Analysis

The CLI appears to use **two different identifiers** for agents inconsistently:

- **Agent selection/persistence**: Uses the `name` field from the agent file's YAML frontmatter
- **Agent lookup on restart**: Uses the filename (without `.md` extension)

When filename ≠ frontmatter name, the agent:

- Gets registered under both identifiers → **duplicate in list**
- Gets persisted by frontmatter name but looked up by filename on restart → **not found error**

## Expected Behavior

1. The agent should appear **exactly once** in the selection list regardless of whether the filename matches the frontmatter `name` field.
2. The CLI should use a **consistent identifier** (either filename or frontmatter `name`, not both) for selection, persistence, and lookup.
3. If the frontmatter `name` takes priority over the filename, the persisted selection should resolve correctly on restart.

## Screenshot

![Bug Screenshot](https://github.com/user-attachments/assets/placeholder)

Image

## Workaround

Rename the agent file to match the frontmatter `name` field:

```bash
mv ~/.copilot/agents/azure-expert.md ~/.copilot/agents/azure-solution-expert.md
mv ~/.copilot/agents/azure-aws-doc.md ~/.copilot/agents/azure-vs-aws-compare-expert.md
```

## Labels

`bug`, `custom-agents`, `cli`

### Affected version

_No response_

### Steps to reproduce the behavior

_No response_

### Expected behavior

_No response_

### Additional context

_No response_

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.