Skip to content

Make CLAUDE.md point to AGENTS.md instead of duplicating content #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lmajano merged 2 commits into from
Mar 27, 2026
Merged

Make CLAUDE.md point to AGENTS.md instead of duplicating content #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f71d36d
Initial plan
Copilot Mar 27, 2026
8d9e4e1
Make CLAUDE.md point to AGENTS.md via @AGENTS.md directive
Copilot Mar 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions AI_INTEGRATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,10 +202,10 @@ graph LR

Additionally, agent configuration files are created for you (paths defined in `AgentRegistry.cfc`):

* `CLAUDE.md` - Claude Desktop/Code assistant
* `CLAUDE.md` - Claude Desktop/Code assistant (points to `AGENTS.md` via `@AGENTS.md`)
* `.github/copilot-instructions.md` - GitHub Copilot
* `.cursorrules` - Cursor IDE
* `AGENTS.md` - Codex & OpenCode (shared file)
* `AGENTS.md` - Codex, OpenCode & Claude (shared file)
* `GEMINI.md` - Gemini CLI

### Keeping Resources Updated
Expand Down Expand Up @@ -894,7 +894,7 @@ ColdBox AI Integration supports **6 major AI agents** with automatic configurati

| Agent | Config File | Description |
| ------------------ | --------------------------------- | ------------------------------ |
| **Claude** | `CLAUDE.md` | Claude Desktop and Claude Code |
| **Claude** | `CLAUDE.md` → `AGENTS.md` | Claude Desktop and Claude Code |
| **GitHub Copilot** | `.github/copilot-instructions.md` | VS Code Copilot integration |
| **Cursor** | `.cursorrules` | Cursor IDE rules |
| **Codex** | `AGENTS.md` (shared) | Codex AI assistant |
Expand Down
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -546,7 +546,7 @@ coldbox ai agents remove cursor # Remove an agent
coldbox ai agents refresh # Regenerate all configurations
```

**Supported Agents**: Claude (CLAUDE.md), GitHub Copilot (.github/copilot-instructions.md), Cursor (.cursorrules), Codex (AGENTS.md), Gemini (GEMINI.md), OpenCode (AGENTS.md)
**Supported Agents**: Claude (CLAUDE.md → AGENTS.md), GitHub Copilot (.github/copilot-instructions.md), Cursor (.cursorrules), Codex (AGENTS.md), Gemini (GEMINI.md), OpenCode (AGENTS.md)

#### Guidelines

Expand Down
2 changes: 2 additions & 0 deletions changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

- `CLAUDE.md` now contains `@AGENTS.md` to point Claude to the shared `AGENTS.md` file, avoiding duplicate content

## [8.8.0] - 2026-03-12

- Fix invalid aliases
Expand Down
8 changes: 8 additions & 0 deletions models/AgentRegistry.cfc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,14 @@ component singleton {
directoryCreate( configDir )
}

// For Claude, write the full content to AGENTS.md and make CLAUDE.md point to it
if ( arguments.agent == "claude" ) {
var agentsFilePath = getDirectoryFromPath( configPath ) & "AGENTS.md"
fileWrite( agentsFilePath, content )
fileWrite( configPath, "@AGENTS.md" )
Comment on lines +156 to +160
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This block hardcodes both the shared filename (AGENTS.md) and recomputes the directory via getDirectoryFromPath( configPath ) even though configDir is already available. Consider deriving the shared path from the existing agent-path mapping (e.g., via getAgentConfigPath(directory, "codex") or static.AGENT_FILES) and using configDir to avoid future divergence if agent filenames/locations change.

Suggested change
// For Claude, write the full content to AGENTS.md and make CLAUDE.md point to it
if ( arguments.agent == "claude" ) {
var agentsFilePath = getDirectoryFromPath( configPath ) & "AGENTS.md"
fileWrite( agentsFilePath, content )
fileWrite( configPath, "@AGENTS.md" )
// For Claude, write the full content to the shared agent file (e.g. AGENTS.md)
if ( arguments.agent == "claude" ) {
var sharedAgentFileName = static.AGENT_FILES[ "codex" ]
var agentsFilePath = configDir & sharedAgentFileName
fileWrite( agentsFilePath, content )
fileWrite( configPath, "@" & sharedAgentFileName )

Copilot uses AI. Check for mistakes.
return
Comment on lines +156 to +161
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

configureAgent() now makes Claude depend on a shared AGENTS.md, but the rest of the system still treats Claude as having only CLAUDE.md. This can leave the install in a broken state without detection (e.g., ai doctor/AgentRegistry.diagnose() won’t warn if AGENTS.md is missing, and removing codex/opencode will delete AGENTS.md even if claude is still configured, leaving CLAUDE.md pointing at a non-existent file). Update the agent health/removal logic to model AGENTS.md as a shared dependency and only delete it when no configured agents require it, and ensure diagnostics validate both files for Claude.

Copilot uses AI. Check for mistakes.
}

// Write agent config file
fileWrite( configPath, content )
}
Expand Down
Loading