One AGENTS.md, every tool.

Sync your AI coding instructions across every tool on your machine — with zero magic, just symlinks.

By Sam Rogers, Snap Synapse Published v0.2.0 MIT

Different tools want different files at project root: AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules. There’s no standard, and waiting for one is expensive. Agentlink keeps them in sync through symlinks. Edit one, every tool sees the change.

Read the README View on GitHub

Why Agentlink?

Creating AI instruction files is cheap — keeping them in sync is the hard part. Good instruction files matter, and they’re often generated by expensive models. Agentlink fixes the sync problem the boring way: one real file, many aliases.

One real file, many aliases

Pick a source (AGENTS.md, CLAUDE.md, whatever). Every other tool file is a symlink to it. No duplicates, no drift.

Zero codegen

No templates, no transforms, no surprise diffs. Symlinks are a 50-year-old OS feature. Edit the source, every tool sees it instantly.

Future-proof

Tomorrow’s AI tool wants workspace/ai/newthing.md? Add it to the config. Agentlink creates the directories and wires the link.

Project and global

Works in repos and under ~/.config/. One agentlink sync keeps both scopes in shape.

Idempotent

Re-run safely. Broken or misdirected links get repaired. Real files are never silently overwritten; preview with dry-run, back up, or force only after inspection.

Automatic triggers

Built-in git hooks, shell hooks, and launchd integration keep things synced without you remembering to run it. Hook installs quote paths safely and refuse ambiguous relative Git hook paths.

Tools covered out of the box

ToolFile it expects
AiderAGENTS.md
AmpAGENTS.md
AntigravityAGENTS.md
AutohandAGENTS.md
Claude CodeCLAUDE.md
Codex CLIAGENTS.md
CursorAGENTS.md
Factory (Droid)AGENTS.md
Gemini CLIGEMINI.md
GitHub Copilot.github/copilot-instructions.md
Goose.goosehints
Junie.junie/AGENTS.md
Kilo CodeAGENTS.md
OpenCodeAGENTS.md
RooCode.roo/rules/rules.md
WindsurfAGENTS.md
ZedAGENTS.md
Anything else(add to config)

Full registry in internal/registry/tools.go. Tools without a project-root instruction file (e.g. Cline, Continue) still work in global scope via their own config paths.

Scope is deliberately narrow: instruction files only. No MCP config, no chain configs. Simple on purpose.

Install

Pre-built binaries for macOS and Linux are on the v0.2.0 release page. Or build from source with Go 1.23+.

From source

git clone https://github.com/snapsynapse/agentlink.git
cd agentlink
go install ./cmd/agentlink/

# Verify
agentlink --help

Pre-built binary

# macOS (Apple Silicon)
curl -L -o agentlink https://github.com/snapsynapse/agentlink/releases/download/v0.2.0/agentlink-darwin-arm64
chmod +x agentlink && mv agentlink /usr/local/bin/

# macOS (Intel) / Linux (amd64)
# Replace darwin-arm64 with darwin-amd64 or linux-amd64

Checksums in SHA256SUMS.txt on the release page.

Usage

Declare your source file and the aliases you want. Agentlink creates and repairs the symlinks.

Project config

# .agentlink.yaml (in project root)
source: AGENTS.md
links:
  - CLAUDE.md
  - GEMINI.md
  - .cursorrules
  - .github/copilot-instructions.md

# Then:
agentlink sync

Global config

# ~/.config/agentlink/config.yaml
source: ~/AGENTS.md
links:
  - ~/.claude/CLAUDE.md
  - ~/.codex/AGENTS.md
  - ~/.gemini/GEMINI.md
  - ~/.config/opencode/AGENTS.md

# Then (auto-detects global config):
agentlink sync

Detect installed tools

# Scan the system for AI tool installs
# and report what's found.
agentlink detect

# Walk a directory tree and wire up
# symlinks in every repo with AGENTS.md,
# including worktrees and submodule-style
# checkouts where .git is a file.
agentlink scan ~/Git

Automatic triggers

# Install git/shell/launchd hooks so
# sync runs without you thinking about it.
agentlink hooks install

# Relative global core.hooksPath values
# are refused; use an absolute path.

# Remove cleanly.
agentlink hooks remove

Safe replacement

# Preview without creating, removing,
# or backing up files.
agentlink sync --dry-run

# Back up regular files before replacing.
agentlink sync --backup

# Replace regular files only.
agentlink sync --force

Directories and special files are never replaced recursively.

Assistant guide. Agentlink publishes a GuideCheck Level 4 guide-file target for bounded local review, build, and test work at /.well-known/assistant-guide.txt. Verify it, read it in full, and approve the reported level before asking an assistant to act on it.