https://github.com/hangboss1761/rule-link
A CLI tool to manage AI programming tool rule files through symlinks
https://github.com/hangboss1761/rule-link
agents claude-code cline cursor-rules gemini-cli roocode
Last synced: 20 days ago
JSON representation
A CLI tool to manage AI programming tool rule files through symlinks
- Host: GitHub
- URL: https://github.com/hangboss1761/rule-link
- Owner: hangboss1761
- License: mit
- Created: 2025-08-18T11:51:11.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2025-09-11T15:36:20.000Z (24 days ago)
- Last Synced: 2025-09-11T18:34:23.693Z (24 days ago)
- Topics: agents, claude-code, cline, cursor-rules, gemini-cli, roocode
- Language: TypeScript
- Homepage:
- Size: 70.3 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# rule-link
[](https://www.npmjs.com/package/rule-link)
[](https://opensource.org/licenses/MIT)
[](https://github.com/hangboss1761/rule-link/actions/workflows/test.yml)
**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`](https://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
```bash
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.
```bash
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.
```bash
# 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.
```bash
# 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.
```bash
# 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 ` 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:
```bash
rule-link create --custom ".vscode/rules.md,enterprise.md,.ai-tools/custom-rules.md"
```
## Recommended Workflow
### Initial Project Setup
1. **Run the command**:
```bash
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.
```bash
# 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 `: Specify the path to the source rule file. (Default: `AGENTS.md`)
- `-l, --list `: Provide a space-separated list of AI tools to link, skipping the interactive menu.
- `-c, --custom `: 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 `: 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:**
```bash
# 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.