github / github/copilot-cli

Recursively discover AGENTS.md in subfolders, like VS Code's chat.useNestedAgentsMdFiles

Open
#3,051 0 comments 8 reactions 0 assignees View on GitHub
area:configuration area:context-memory
Dominant language
Shell
Stars
11.2k
Forks
1.9k
Avg merge
14h 16m
Merged PRs (30d)
6

Description

### Describe the feature or problem you'd like to solve

The Copilot CLI currently discovers `AGENTS.md` files only along the path **from the current working directory up to the git root** (per the resolution of #1655). Files in *sibling* or *deeper* subfolders that are not on the CWD-to-root path are not discovered when the CLI is started at the repo root.

In a monorepo started from the root, this means folder-local `AGENTS.md` files (e.g., `frontend/AGENTS.md`, `backend/AGENTS.md`, `packages/lib-a/AGENTS.md`) are invisible to the agent unless the user `cd`s into each subfolder before starting the CLI — which defeats the point of having scoped, co-located instructions.

VS Code already solves this with the experimental setting [`chat.useNestedAgentsMdFiles`](https://code.visualstudio.com/docs/copilot/customization/custom-instructions#_use-multiple-agentsmd-files-experimental):

> *"VS Code searches recursively in all subfolders of your workspace for `AGENTS.md` files and adds their relative path to the chat context. The agent can then decide which instructions to use based on the files being edited."*

The CLI should provide the same behavior so that the same `AGENTS.md` layout works identically in VS Code Chat and in the CLI.

### Proposed solution

Make the CLI recursively discover `AGENTS.md` files in all subfolders of the workspace / git root (respecting `.gitignore`), matching VS Code's `chat.useNestedAgentsMdFiles` behavior:

1. **Discovery:** walk the workspace (git root or CWD when not in a repo) and collect all `AGENTS.md` files. Honor `.gitignore` and skip the usual heavy directories (`node_modules`, `.git`, `dist`, `build`, etc.) by default.
2. **Context exposure:** add the discovered files (paths + contents, or paths only with on-demand load) to the agent's context, so the model can decide which scope applies based on the files being edited — same model-driven selection as VS Code.
3. **Opt-in / opt-out parity with VS Code:** ship behind a setting (e.g., `useNestedAgentsMdFiles` or an env var / CLI flag) so users can match VS Code's behavior. Defaulting it on would be ideal; if there are concerns about token cost on large monorepos, off-by-default with a clear toggle is acceptable.
4. **Precedence:** when multiple `AGENTS.md` files apply to a given file, deeper-nested files should take precedence over shallower ones (same direction as the existing CWD-to-root resolution).

### Example prompts or workflows

**Monorepo layout:**

```
repo/ ← git root, where the CLI is started
├── AGENTS.md ← repo-wide rules (already discovered)
├── frontend/
│ ├── AGENTS.md ← React/TS conventions (NOT discovered today)
│ └── src/...
├── backend/
│ ├── AGENTS.md ← Go service conventions (NOT discovered today)
│ └── cmd/...
└── packages/
├── lib-a/AGENTS.md ← package-specific rules (NOT discovered today)
└── lib-b/AGENTS.md ← package-specific rules (NOT discovered today)
```

**Today (CLI started at `repo/`):** only the root `AGENTS.md` is loaded. If the user asks *"add a new endpoint to backend/cmd/api"*, the agent doesn't see `backend/AGENTS.md` and won't follow its conventions unless the user manually `cd`s into `backend/` first.

**Expected (with this feature):** all four nested `AGENTS.md` files are discovered. When the agent works on a file under `backend/cmd/api/`, the `backend/AGENTS.md` rules are applied. Same behavior the user already gets in VS Code Chat with `chat.useNestedAgentsMdFiles` enabled.

### Additional context

- Resolution of #1655 only covers the CWD-to-root path, which is a strict subset of what VS Code's nested-discovery setting does. Several users have already expressed surprise that the CLI does not match VS Code here.
- Related: #2735 (nested discovery is loading `copilot-instructions.md` more aggressively than expected — argues for clear scoping rules whichever direction this goes).
- Related: #2504 / #1859 / #2245 (analogous gap for `.github/agents/*.agent.md` agent profiles).
- Workarounds today (symlinks from `.github/instructions/`, `applyTo:` frontmatter in `instructions.md` files, parent-AGENTS.md instructing the agent to read children) are brittle and inconsistent — see the workarounds section of #1655.
- Behavior parity between VS Code Chat and the CLI is valuable: teams document `AGENTS.md` once and expect both surfaces to honor it equivalently.

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.