One AGENTS.md, every tool.
Sync your AI coding instructions across every tool on your machine — with zero magic, just symlinks.
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 file and every linked path holds the same text; each tool still decides when it rereads it.
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.
Layer when needed
If one tool needs extra guidance, keep its wrapper real, import the shared source, and omit that wrapper from Agentlink. Identical aliases stay linked; tool-specific layers stay explicit.
Zero codegen
No templates, no transforms, no surprise diffs. Symlinks are a 50-year-old OS feature. Edit the source and every alias changes with it, byte for byte.
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/. Each agentlink sync selects one scope: the current project config when present, otherwise the global config. Use sync --global to explicitly select global scope.
Idempotent
Re-run safely. Missing aliases are created; replacement of broken or misdirected links requires explicit --force. 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.
Scope is deliberately narrow: instruction files only. No MCP config, no chain configs. Simple on purpose.
Supported platforms and AI tools
Release binaries support macOS and Linux, each on ARM64 and x86-64 (AMD64). Git and zsh hooks work on both systems; launchd is macOS-only. Native Windows is not a supported release target. WSL uses the Linux binary, but is not a separate tested platform.
Agentlink v0.6.0, September 5, 2026. This listing describes the released registry, including vendor references and client caveats.
Native means the client reads AGENTS.md at the stated scope. Configurable and import modes require setup in that tool. Symlink means Agentlink creates an alias at the listed project path. Global paths are separate instruction scopes, not settings files. Detection is a heuristic, not proof that a tool loaded the instructions.
The complete listing is generated from the registry, with vendor references and version caveats. Native readers need no project alias. Read integration and nested-scan guidance.
| Tool / mode | Instruction paths | Requirements and evidence |
|---|---|---|
| Aider configurable | Project: AGENTS.mdGlobal: Not listed | Use aider --read AGENTS.md or set read: AGENTS.md in .aider.conf.yml; no automatic loading claim. Vendor reference for Aider (reviewed 2026-09-05). |
| Amp native | Project: AGENTS.mdGlobal: ~/.config/AGENTS.md | Also loads ~/.config/amp/AGENTS.md; avoid duplicating the same instructions in both global paths. Vendor reference for Amp (reviewed 2026-09-05). |
| Antigravity native | Project: AGENTS.mdGlobal: ~/.gemini/GEMINI.md | Current CLI reads root AGENTS.md or GEMINI.md; older IDE installations use rules settings. Vendor reference for Antigravity (reviewed 2026-09-05). |
| Autohand native | Project: AGENTS.mdGlobal: Not listed | Project instructions load at conversation start. Vendor reference for Autohand (reviewed 2026-09-05). |
| Claude Code import | Project: CLAUDE.mdGlobal: ~/.claude/CLAUDE.md | Keep a real CLAUDE.md with @AGENTS.md when adding Claude-only instructions. Vendor reference for Claude Code (reviewed 2026-09-05). |
| Cline native | Project: AGENTS.mdGlobal: ~/.agents/AGENTS.md | Root and shared global AGENTS.md are supported; rules can be toggled in Cline. Vendor reference for Cline (reviewed 2026-09-05). |
| Codex CLI native | Project: AGENTS.mdGlobal: ~/.codex/AGENTS.md | CODEX_HOME can override the global directory; AGENTS.override.md takes precedence. Vendor reference for Codex CLI (reviewed 2026-09-05). |
| Continue symlink | Project: .continue/rules/AGENTS.mdGlobal: Not listed | Create a local Markdown rule in .continue/rules; model/provider config.yaml is not an instruction alias. Vendor reference for Continue (reviewed 2026-09-05). |
| Crush native | Project: AGENTS.mdGlobal: ~/.config/AGENTS.md | Shared global context is ~/.config/AGENTS.md; Crush-specific context can use ~/.config/crush/CRUSH.md. Vendor reference for Crush (reviewed 2026-09-05). |
| Cursor native | Project: AGENTS.mdGlobal: Not listed | Root and nested AGENTS.md apply to Agent; global User Rules are configured in the editor. Vendor reference for Cursor (reviewed 2026-09-05). |
| Factory (Droid) native | Project: AGENTS.mdGlobal: ~/.factory/AGENTS.md | Droid reads repository guidance; detection uses the droid command. Vendor reference for Factory (Droid) (reviewed 2026-09-05). |
| Gemini CLI configurable | Project: GEMINI.mdGlobal: ~/.gemini/GEMINI.md | Set context.fileName to AGENTS.md in Gemini settings to avoid an alias. Vendor reference for Gemini CLI (reviewed 2026-09-05). |
| GitHub Copilot native | Project: .github/copilot-instructions.mdGlobal: ~/.copilot/copilot-instructions.md | Native AGENTS.md in CLI and supported agent clients; .github/copilot-instructions.md remains the cross-feature alias. IDE support varies. Vendor reference for GitHub Copilot (reviewed 2026-09-05). |
| Goose native | Project: AGENTS.mdGlobal: ~/.config/goose/.goosehints | Developer extension required. Defaults load AGENTS.md and .goosehints; avoid duplicate instructions. CONTEXT_FILE_NAMES overrides discovery. Vendor reference for Goose (reviewed 2026-09-05). |
| Junie native | Project: AGENTS.mdGlobal: Not listed | Root AGENTS.md is read unless .junie/AGENTS.md or an explicit Guidelines path overrides it. Vendor reference for Junie (reviewed 2026-09-05). |
| Kilo Code native | Project: AGENTS.mdGlobal: Not listed | Root and per-directory AGENTS.md supported; uppercase filename required. Vendor reference for Kilo Code (reviewed 2026-09-05). |
| Kiro native | Project: AGENTS.mdGlobal: ~/.kiro/steering/AGENTS.md | Default agents load AGENTS.md; custom agents must explicitly include steering resources. Vendor reference for Kiro (reviewed 2026-09-05). |
| OpenClaw native | Project: Not listed Global: ~/.openclaw/workspace/AGENTS.md | Workspace instructions, not arbitrary repository discovery. Sandbox seeding rejects aliases outside the workspace. Vendor reference for OpenClaw (reviewed 2026-09-05). |
| OpenCode native | Project: AGENTS.mdGlobal: ~/.config/opencode/AGENTS.md | Global path honors XDG_CONFIG_HOME. V2 reads AGENTS.md; older fallback rules differ. Vendor reference for OpenCode (reviewed 2026-09-05). |
| Qwen Code native | Project: AGENTS.mdGlobal: ~/.qwen/QWEN.md | Current Qwen also reads AGENTS.md; QWEN.md remains supported. Avoid loading duplicate copies. Vendor reference for Qwen Code (reviewed 2026-09-05). |
| RooCode symlink | Project: .roo/rules/rules.mdGlobal: ~/.roo/rules/AGENTS.md | An explicit .md file in .roo/rules supplies shared rules; no root AGENTS.md autodiscovery claim. Vendor reference for RooCode (reviewed 2026-09-05). |
| Windsurf native | Project: AGENTS.mdGlobal: Not listed | Cascade supports root and nested AGENTS.md; documentation now lives under Devin Desktop. Vendor reference for Windsurf (reviewed 2026-09-05). |
| Zed native | Project: AGENTS.mdGlobal: ~/.config/zed/AGENTS.md | Zed Agent uses the first matching project instruction file; external agents use their own loaders. Vendor reference for Zed (reviewed 2026-09-05). |
Practical instruction-file guides
Choose a topology before creating links. These guides explain when one shared file is enough, when a real wrapper is safer, and how Agentlink treats nested repositories and tool-specific integrations.
AGENTS.md symlinks
Build one-source, many-alias instruction files without code generation or duplicate content drift.
CLAUDE.md and AGENTS.md
Decide between a byte-identical symlink and a real Claude-specific wrapper that imports shared guidance.
Monorepo instruction files
Use root defaults, intentional nested scopes, and documented discovery behavior without accidental propagation.
Supported tools reference
Understand integration modes, source versions, and nested discovery.
Install
Pre-built binaries for macOS and Linux are on the v0.6.0 release page. Or install directly with Go 1.23+.
Homebrew (macOS and Linux)
brew install snapsynapse/tap/agentlink # Verify agentlink --version
Go install
go install github.com/snapsynapse/agentlink/cmd/agentlink@latest # Verify agentlink --help
Source builds require Go 1.23 or newer. CI verifies Go 1.23.12, 1.26.8, and 1.27.1, with Go 1.27.1 also covered on macOS.
Pre-built binary
# macOS (Apple Silicon) curl -L -o agentlink https://github.com/snapsynapse/agentlink/releases/download/v0.6.0/agentlink-darwin-arm64 curl -L -o SHA256SUMS.txt https://github.com/snapsynapse/agentlink/releases/download/v0.6.0/SHA256SUMS.txt grep ' agentlink-darwin-arm64$' SHA256SUMS.txt | sed 's/agentlink-darwin-arm64/agentlink/' | shasum -a 256 -c - chmod +x agentlink && mv agentlink /usr/local/bin/ # macOS (Intel) / Linux # Replace darwin-arm64 with darwin-amd64, linux-amd64, or linux-arm64
Checksums in SHA256SUMS.txt on the release page.
AI-assisted (GuideCheck)
Ask Claude, ChatGPT, or another tool-using assistant to install Agentlink by following the published assistant guide — a GuideCheck Human-Verifiable Assistant Guide with approval-gated, checksum-verified install actions.
Verify https://agentlink.run/.well-known/assistant-guide.txt with https://guidecheck.org/verify, then follow its install actions. Show me each action block before running it.
Verify the guide, read it in full, and approve each action. Install places one binary only; it creates no symlinks until you separately direct a sync.
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
From the project directory:
agentlink sync --dry-run 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
From a directory without a project config, run agentlink sync. Use explicit global selection from any directory:
agentlink sync --global --dry-run agentlink sync --global
Layered Claude wrapper
# Keep CLAUDE.md out of .agentlink.yaml. # CLAUDE.md remains a real committed file. @AGENTS.md ## Claude-specific guidance Use plan mode under src/billing/.
Agentlink does not generate or rewrite wrappers. Import expansion and nested precedence remain the consuming tool’s responsibility. Limited Edition Jonathan’s AGENTS.md guide for the CEO of Shopify explains the nested symlink workaround behind the “symlink by default, real wrapper at exception points” recommendation.
Detect installed tools
# Scan the system for AI tool installs # and report what's found. agentlink detect # Prefer native/config/import guidance. agentlink detect --generate --prefer-native # Walk a directory tree and wire up # symlinks in every repo with AGENTS.md. agentlink scan ~/Git # Also link beside nested AGENTS.md files # in repos without .agentlink.yaml. agentlink scan ~/Git --nested
An explicit .agentlink.yaml is authoritative. Automatic scanning preserves existing real wrappers unless --force is supplied. Nested mode creates only aliases with documented nested discovery; unknown tools remain root-only. Deterministic integration tests verify exact topology, idempotence, and byte-preserving dry runs.
Automatic triggers
# Install git/zsh hooks (plus launchd on macOS) so # sync runs without you thinking about it. agentlink hooks install --all # Relative global core.hooksPath values # are refused; use an absolute path. # Remove cleanly. agentlink hooks remove --all
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 or conflicting links. agentlink sync --force
Directories and special files are never replaced recursively.