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

Research direction

Start by tracing the existing CWD-to-root AGENTS.md resolution described in #1655 and review the scoping concerns in #2735. Define how recursive discovery, ignore handling, context exposure, configuration, and precedence fit together; done means nested AGENTS.md files are consistently discovered and covered by tests for the monorepo example.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, shell, vscode
Domain
cli, developer-experience, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.