Agent Guidelines Manager CLI

A command-line tool to sync AI agent guideline files across project hierarchies. Maintain a single source of truth (AGENTS.md) and automatically create symlinks for different AI agents (Claude, Cursor, Copilot, Gemini, Qwen, and more).

Problem

Different AI coding assistants look for guidelines in different ways:

• Some look for CLAUDE.md in the project root
• Cursor looks for .cursor/rules/*.md files
• Others have their own conventions

Managing multiple guideline files manually across nested directories is error-prone and duplicates effort.

Solution

This tool treats AGENTS.md as the single source of truth and automatically creates symlinks for each agent type. One command syncs your entire project hierarchy.

Installation

Build from source

git clone https://github.com/alex-heritier/agents.git
cd agents
go build -o agents

This creates an agents binary.

Add to PATH

# Option 1: Install to /usr/local/bin
sudo cp agents /usr/local/bin/agents

# Option 2: Create a symlink
sudo ln -s "$PWD/agents" /usr/local/bin/agents

Then use agents from anywhere.

Usage

List guideline files

Discover all guideline files in your project:

agents list
agents list --verbose

Sync guideline files

Create symlinks for specified agents from all AGENTS.md files in your project:

# Create CLAUDE.md and .cursor/rules/agents.md symlinks
agents sync --claude --cursor

# Preview changes without applying
agents sync --claude --cursor --dry-run

# Verbose output showing each operation
  agents sync --claude --cursor --verbose

Remove guideline files

Delete guideline files for specific agents:

# Delete all CLAUDE.md files
agents rm --claude

# Delete multiple agents
agents rm --cursor --gemini --qwen

# Preview deletions
  agents rm --claude --dry-run --verbose

Supported Agents

• claude - Creates CLAUDE.md
• cursor - Creates .cursor/rules/agents.md
• copilot - Creates COPILOT.md
• gemini - Creates GEMINI.md
• qwen - Creates QWEN.md

Adding new agent types is simple: edit tools.json and add to the tools map.

Workflow

1. Create an AGENTS.md file in your project root with guidelines for your AI coding assistants
2. Create the same file in any nested directories (subdirectories with their own guidelines)
3. Run agents rule sync --claude --cursor (or any agents you use)
4. All agent-specific files are now symlinks pointing to the corresponding AGENTS.md

When you update AGENTS.md, all agent-specific files automatically reflect the changes since they're symlinks.

Safety Features

• Conflict detection: If a file already exists and differs from AGENTS.md, the tool prompts you before overwriting
• Dry-run mode: Preview all changes with --dry-run before applying
• Verbose logging: Use --verbose to see detailed operations

Examples

Project structure before

myproject/
├── AGENTS.md
├── src/
│   └── AGENTS.md
└── docs/
    └── AGENTS.md

Create guidelines for Claude and Cursor

agents sync --claude --cursor

Project structure after

myproject/
├── AGENTS.md
├── CLAUDE.md -> AGENTS.md (symlink)
├── .cursor/rules/
│   └── agents.md -> ../../AGENTS.md (symlink)
├── src/
│   ├── AGENTS.md
│   ├── CLAUDE.md -> AGENTS.md (symlink)
│   └── .cursor/rules/
│       └── agents.md -> ../../../AGENTS.md (symlink)
└── docs/
    ├── AGENTS.md
    ├── CLAUDE.md -> AGENTS.md (symlink)
    └── .cursor/rules/
        └── agents.md -> ../../../AGENTS.md (symlink)

Help

agents help
agents rule list --help
agents rule sync --help
agents rule rm --help

Tech Stack

• Language: Go
• Dependencies: None (standard library only)
• Platforms: macOS, Linux, Windows

Contributing

Contributions welcome! To add a new agent type:

1. Edit tools.json and add to the tools map
2. Run go build (and tests if added)
3. Submit a PR

Agent Configuration Reference

For comprehensive information about how different AI agents use guideline files, see agents-conventions.md. This document covers:

• Configuration options for Claude, Cursor, Copilot, Gemini, Qwen, and other agents
• Hierarchical placement and precedence rules
• Auto-generation and external file referencing
• Best practices for cross-agent compatibility

Tool Configuration

Tool definitions live in tools.json (file names, directories, and source file names). You can extend or override these definitions by creating an optional file at:

$XDG_CONFIG_HOME/agents/tools.json

If XDG_CONFIG_HOME is not set, the tool falls back to ~/.config/agents/tools.json.

License

MIT