rule-link

rule-link is a command-line tool designed to help developers unify the management of configuration rule files for multiple AI programming tools. By creating symbolic links to a single, centralized rule file (e.g., AGENTS.md), you can maintain consistency across different AI assistants (like Cursor, Windsurf, Claude Code, etc.) without duplicating and manually synchronizing multiple files.

⭐ New in this version: Default source file changed to AGENTS.md for better compatibility with AI tools that natively support this standard.

The Problem It Solves

Developers on a project often use different AI programming assistants. Each tool often requires its own project-specific rule file (e.g., CLAUDE.md, GEMINI.md, AGENTS.md) to understand context and coding conventions. Managing these separate files leads to duplication and inconsistency, as developers must manually synchronize changes.

rule-link solves this by creating symbolic links from a single source of truth (e.g., AGENTS.md) to the configuration files of various AI tools. This ensures all assistants work from the same set of rules.

Furthermore, with the growing adoption of AGENTS.md as a standard, tools like Cursor and Gemini CLI can read it natively. This reduces the number of symbolic links needed, simplifying configuration even more. rule-link bridges the gap by managing symlinks for tools that don't yet support the standard while leveraging native support where available.

Installation

npm install -g rule-link

Usage

The primary command is rule-link create. You can run it in interactive mode or with command-line flags.

Interactive Mode

For a guided experience, simply run the command without any options. The tool will prompt you to select the desired AI tools and confirm the paths.

rule-link create
# or use npx without global installing
npx rule-link create

Command-Line Mode

For scripting or quick use, you can pass arguments directly.

1. Specify AI tools directly:

Use the --list flag to provide a space-separated list of tool names.

# Create links for Augment and Windsurf (tools that need symlinks)
rule-link create --list Augment Windsurf

2. Specify a different source file:

By default, rule-link uses AGENTS.md as the source of truth (changed from rule.md for better AI tool compatibility). You can specify a different file with the --file flag.

# Use my-rules.md as the source file
rule-link create --file my-rules.md --list Augment

3. Link custom file paths:

If you need to link to a file not officially supported, use the --custom flag with a comma-separated list of paths.

# Link two custom files
rule-link create --custom ".custom/coding-standards.md,docs/project-rules.md"

Built-in AI Tools

rule-link comes with built-in support for the following popular AI tools:

| Tool Name | File Path | Native AGENTS.md Support | | ----------- | ------------------------------------- | ------------------------ | | Cursor | AGENTS.md ⭐ | ✅ Yes (recommended) | | Augment | .augment/rules/coding-standards.md | ❌ No (symlink needed) | | Windsurf | .windsurf/rules/coding-standards.md | ❌ No (symlink needed) | | Claude Code | CLAUDE.md | ❌ No (symlink needed) | | Gemini CLI | AGENTS.md ⭐ | ✅ Yes (recommended) | | Cline | .clinerules/coding-standards.md | ❌ No (symlink needed) | | Roo Code | AGENTS.md ⭐ | ✅ Yes (recommended) |

Custom AI Tools

While rule-link provides built-in support for popular tools, you can create symbolic links for any AI tool using the --custom <paths> flag. This allows you to:

• Link to tools not officially supported
• Use custom file paths for your specific workflow
• Support enterprise or internal AI tools
• Maintain consistency across any number of AI assistants

Simply provide a comma-separated list of custom file paths:

rule-link create --custom ".vscode/rules.md,enterprise.md,.ai-tools/custom-rules.md"

Recommended Workflow

Initial Project Setup

1. Run the command:

   rule-link create

2. Follow the prompts to select your preferred AI tools and create the AGENTS.md source file and all the necessary symbolic links.
3. Commit the source file: Commit the AGENTS.md and all the necessary symbolic links to your Git repository.

Onboarding a New Developer

When new developers clone the project, the symbolic links may not exist, or they may be using a different operating system (Windows, macOS, or Linux), where symbolic links are implemented differently. They need to run the rule-link create command once to generate these symbolic links locally.

# After git clone
git clone project-url
cd project

# Generate local rule file links
rule-link create

Command Reference

rule-link create

Creates symbolic links for AI tool rule files.

Options:

• -f, --file <path>: Specify the path to the source rule file. (Default: AGENTS.md)
• -l, --list <tools...>: Provide a space-separated list of AI tools to link, skipping the interactive menu.
• -c, --custom <paths>: Provide a comma-separated list of custom file paths to link.
• -F, --force: Force overwrite existing files without prompting (non-interactive mode only).
• -v, --version: Display the version number.
• -h, --help: Display help information.

Advanced Options:

• -t, --target <name>: Specify the target file name for AI tools. (Default: coding-standards.md)

  Note: This only affects tools that support custom file names (Cursor, Augment, Windsurf, Cline, Roo Code). Tools like Claude Code and Gemini CLI use fixed file names and will ignore this parameter.

Examples:

# Interactive mode
$ rule-link create

# Specify a different source file
$ rule-link create --file my-awesome-rules.md

# Link specific tools directly (tools that need symlinks)
$ rule-link create --list Augment Windsurf "Claude Code"

# Force overwrite existing files
$ rule-link create --list Augment --force

# Link custom files
$ rule-link create --custom ".vscode/rules.md,enterprise.md"

# Combine flags with force overwrite
$ rule-link create --file project-rules.md --list Augment --custom "docs/guidelines.md" --force

License

This project is licensed under the MIT License.