[FEATURE]: Ability to ignore AGENTS.md

Feature hasn't been suggested before.

I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Now it is able to add custom files that will be attached to the context, but there is no way to disable AGENTS.md.
In the repository some users use Codex and some Opencode. We need to have different files for them because OpenCode supports subagents and other differences from Codex. For example, ClaudeCode uses CLAUDE.md and we can add specific instructions only related to the Claude.

@NaikSoftware

@NaikSoftware do u think "instructions": [...] should allow for exclusions? Just trying to think in terms of settings we already have in opencode.json

Yes, I think instructions can override default behaviour. By default read agents.md, claude.md. Settings can override this list by my own

Right now they are append so we'd need to distinguish them, (some people use them to add their cursor rules for example)

Users could specify any list of files they want. cursor and agents.md or any list. It is much flexible than hardcoded some files inside core and ability only to expand list of files.

@rekram1-node

Right now they are append so we'd need to distinguish them, (some people use them to add their cursor rules for example)

@rekram1-node not sure if you want to track this as a separate docs issue....

Documentation:

instructions are appended (to what...?):
- https://opencode.ai/docs/config/#instructions (See https://opencode.ai/docs/rules/#custom-instructions)
- the AGENTS.md is automatically included in the system prompt ([FEATURE]:Display warning when agents.md is not accessible #3603 (comment))
Instructions vs Rules (terminology): Pick one (instructions 👍), or elaborate on the distinction

yeah having consistent terminology makes sense idek why it is different that's a good point

This is certainly a very good idea, many AIs read AGENTS.md(codex, opencode, cursor...) , yet we have no way to differentiate between it, which is certainly frustrating

@rekram1-node

@rekram1-node I think I have a working solution for this based on the discussion here. It adds support for excluding default rule files by prefixing them with ! in the instructions array:

{
  instructions: ["!AGENTS.md", "AGENTS.local.md"]
}

For context, this was built with AI using OpenCode. I'm a professional senior software engineer but not familiar with this codebase or TypeScript, so feedback is welcome.

The code changes follow the contribution guidelines to the best of my knowledge. Let me know if you'd like me to push it up for review.

@rekram1-node

@rekram1-node have you had a chance to review my comment regarding a fix for this?

Yes, please! Sometimes the AGENT.md files committed in the repo takes up too much context. Instead of manually deleting them (which creates a Git changes), ignoring it at the OpenCode level would be very convenient and more “pro-user” friendly.

@DavidBK

@DavidBK i think rewrite Opencode from scratch to the new TUI is much simple for the maintainers then adding two lines of code for devs who can't use OpenCode without this feature 😔

@NaikSoftware

Would it be possible to re-open the issue? @NaikSoftware
It's currently very important to me, and I need to handle it by removing files locally and using Git to disregard the changes, which is rather inconvenient.

@vuon9

@vuon9 I created many issues like this (critical for many peoples) and none of them was done. Only "it's good idea we will think about it". Instead of it I see major updates not so critical (TUI, web interface) was implemented. Because of it I think team has it's own roadmap/plan for the project. Such a simple and usable things like this not so interesting. We can discuss this issue infinitely but it not reasonable. Just use Claude Code if you want good UX and all needed features.

The OC team's prioritization is unclear to me, but the concern is totally valid.
Latecomers will read and form their opinions on the ongoing discussion, then they will probably decide to work on it.

@vuon9 I created many issues like this (critical for many peoples) and none of them was done. Only "it's good idea we will think about it". Instead of it I see major updates not so critical (TUI, web interface) was implemented. Because of it I think team has it's own roadmap/plan for the project. Such a simple and usable things like this not so interesting. We can discuss this issue infinitely but it not reasonable. Just use Claude Code if you want good UX and all needed features.

I had the same experience, and drew the same conclusion. As I disentangle from OC, I've offered this encouragement, to consider rewarding implementation excellence:

In the spirit of calling out excellent engineering and design....

I've found that the Pi Coding Agent is more robust and, for me has none of the issues that I've encountered in OC, or has an elegant way to resolve them.... I'm dropping out of OC issues:

[Pi Coding Agent](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent)
[Overview](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/)
[Example development session](https://www.youtube.com/watch?v=ANQ1IYsFM2s)

Temporary workaround for anyone blocked by this:

Our repo has a committed AGENTS.md, but I want to use my own local version. Keep your preferred file anywhere outside the repo, then run:

cp /path/to/your/AGENTS.md ./AGENTS.md
git update-index --skip-worktree AGENTS.md

I also added Git hooks to rerun this after checkout, pull, merge, or rebase. Not ideal, but it works for now.

Temporary workaround for anyone blocked by this:

Our repo has a committed AGENTS.md, but I want to use my own local version. Keep your preferred file anywhere outside the repo, then run:

cp /path/to/your/AGENTS.md ./AGENTS.md
git update-index --skip-worktree AGENTS.md
I also added Git hooks to rerun this after checkout, pull, merge, or rebase. Not ideal, but it works for now.

and dont forget to copy in every git worktree)

Navigation Menu

Repository navigation

[FEATURE]: Ability to ignore AGENTS.md #4035

Feature hasn't been suggested before.

Describe the enhancement you want to request

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[FEATURE]: Ability to ignore AGENTS.md #4035

Description

Feature hasn't been suggested before.

Describe the enhancement you want to request

Activity

rekram1-node commented on Nov 7, 2025

NaikSoftware commented on Nov 7, 2025

rekram1-node commented on Nov 7, 2025

NaikSoftware commented on Nov 7, 2025

taqtiqa-mark commented on Nov 11, 2025

rekram1-node commented on Nov 12, 2025

WAY29 commented on Dec 8, 2025

jordanjones-sq commented on Jan 17, 2026

jordanjones-sq commented on Jan 23, 2026

DavidBK commented on Mar 10, 2026

NaikSoftware commented on Mar 10, 2026

vuon9 commented on Mar 10, 2026

NaikSoftware commented on Mar 10, 2026

vuon9 commented on Mar 10, 2026

taqtiqa-mark commented on Mar 12, 2026

EatMyLunch commented on Jul 18, 2026

NaikSoftware commented on Aug 9, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions