Skip to content

[FEATURE]: Support .local.md variants for instruction files (AGENTS.local.md, CLAUDE.local.md) #16110

@clansty

Description

@clansty

Verify there is no existing issue for this

  • I have searched the existing issues

Is your feature request related to a problem?

When working in a shared repository, AGENTS.md is committed to git and shared across the team. However, individual developers often want personal instructions (local environment notes, personal coding preferences, machine-specific paths) that should not be committed to the shared repo.

Currently there is no built-in way to have per-user instruction files that are gitignored.

Describe the solution you'd like

Support .local.md variants alongside each instruction file:

  • AGENTS.local.md loaded alongside AGENTS.md
  • CLAUDE.local.md loaded alongside CLAUDE.md

These files would be loaded additively — both the base file and the .local.md variant are included when present. Users can then add *.local.md to .gitignore for personal instructions.

This follows the same pattern that Claude Code uses with CLAUDE.local.md.

Describe alternatives you've considered

Using the instructions config field to point to a custom file path works, but requires manual configuration per project and the config file itself may be committed.

Related: #11454 proposes .opencode/AGENTS.md for environment-specific instructions — a different approach to a similar problem. This PR uses the .local.md convention which is already established by Claude Code.

Additional context

I have a PR ready: #16108

Metadata

Metadata

Assignees

Labels

coreAnything pertaining to core functionality of the application (opencode server stuff)

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions