# Agentlink

Sync one AGENTS.md to every AI coding tool on your machine, with zero magic, just symlinks.

## Summary

Agentlink is a small Go CLI that keeps AI coding assistant instruction files in sync across every tool on a machine by declaring one real source file and symlinking tool-specific aliases to it. Tools expect different filenames (AGENTS.md for Codex, Cursor, OpenCode, Crush, and Kiro; CLAUDE.md for Claude Code; GEMINI.md for Gemini CLI; .github/copilot-instructions.md for GitHub Copilot) and different global paths (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.openclaw/workspace/AGENTS.md). Agentlink fixes identical-file drift without code generation. When a tool needs additional guidance, its real wrapper can import the shared source and remain intentionally unmanaged while Agentlink manages the other aliases. The registry covers 23 tools and records each tool's preferred native, configurable, import, symlink, or unsupported integration.

Install: brew install snapsynapse/tap/agentlink, or go install github.com/snapsynapse/agentlink/cmd/agentlink@latest. 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 binaries are linked from README.md.
Current release: v0.6.0.
Version 0.6.0 includes safety fixes, refreshed registry, and --global for sync/check/clean.
Complete support listing: https://agentlink.run/#supported-tools (generated from registry with dated vendor references).
OS support: macOS and Linux, ARM64 and AMD64; launchd only on macOS. Native Windows is unsupported.

Scope is deliberately narrow: instruction files only. No MCP servers, no chain configs, no templating.

Agentlink does not define instruction precedence. Claude Code expands @ imports and applies its own CLAUDE.md hierarchy. AGENTS.md-aware tools apply their documented directory scoping. Agentlink only manages filesystem relationships.

## Website guides

- AGENTS.md symlinks: https://agentlink.run/guides/agents-md-symlinks/
- CLAUDE.md and AGENTS.md: https://agentlink.run/guides/claude-md-and-agents-md/
- Monorepo instruction files: https://agentlink.run/guides/monorepo-instruction-files/
- Supported tools and instruction-file paths: https://agentlink.run/reference/supported-tools/

These pages are canonical HTML explanations for people. robots.txt, sitemap.xml, llms.txt, the favicon, and /.well-known/* remain crawlable machine surfaces but are not sitemap HTML targets.

## Key concepts

- source: the one real instruction file you edit (e.g. AGENTS.md)
- links: tool-specific aliases that become symlinks pointing at the source
- layered wrapper: a real tool-specific file that imports the source and adds tool-only guidance; omit it from links
- project config: .agentlink.yaml at repo root, scoped to that project
- global config: ~/.config/agentlink/config.yaml, scoped to the user's home directory
- detect: scan the system for installed AI tools and report what was found
- scan: respect each repo's explicit .agentlink.yaml; otherwise wire root aliases while preserving existing real wrappers
- nested scan: opt-in --nested mode links only documented nested-capable aliases beside nested AGENTS.md files in unconfigured repos; unknown tools fail closed at root
- integration preference: detect --generate --prefer-native recommends native, configurable, or import options before symlinks
- nested symlink reference: Limited Edition Jonathan's AGENTS.md guide explains the practical monorepo workaround: https://limitededitionjonathan.substack.com/p/i-wrote-this-agentsmd-guide-for-the
- hooks: install git, shell, and launchd triggers so sync runs automatically
- idempotent: re-running is safe; broken or misdirected links require explicit --force
- dry-run: hard preview mode; no symlinks, removals, or backups are written
- replacement safety: backup authorizes regular files only; force also authorizes conflicting symlinks. Directories and special files are refused.
- deterministic scan contracts: compiled-CLI fixtures verify exact topology, relative targets, explicit-config authority, wrapper preservation, root-only unknown integrations, idempotence, and byte-preserving dry runs
- registry governance: nested discovery requires a public documentation reference, and the README supported-tools table is checked against the registry
- git hook safety: global core.hooksPath must be absolute for install, remove, and status
- assistant guide: https://agentlink.run/.well-known/assistant-guide.txt
- AI posture: https://agentlink.run/.well-known/aiposture
- guidecheck conformance target: Level 4; release anchor must be independently verified
- assistant guide use: verify it, read it in full, and approve the reported level before assistant action

## Key files in the repository

- README.md: full install and usage docs
- docs/.well-known/assistant-guide.txt: GuideCheck assistant guide
- docs/.well-known/assistant-guide-manifest.txt: GuideCheck sidecar manifest
- cmd/agentlink/: Go CLI entry point
- internal/: sync logic, detect, scan, hooks, backup
- examples/project.agentlink.yaml: copyable project configuration
- examples/global.agentlink.yaml: copyable global configuration
- CHANGELOG.md: version history
- LICENSE: MIT

## Lineage

- Canonical landing: https://agentlink.run/
- Assistant Guide: https://agentlink.run/.well-known/assistant-guide.txt
- AI Posture: https://agentlink.run/.well-known/aiposture
- This project (Snap Synapse maintained continuation): https://github.com/snapsynapse/agentlink
- Upstream original by Martin Mose Facondini: https://github.com/martinmose/agentlink
- Historical replacement PR after standalone repository conversion: https://github.com/martinmose/agentlink/pull/3

This repository is the canonical home for current Agentlink project direction, issues, releases, and documentation. It preserves upstream MIT attribution while carrying the Snap Synapse continuation: detect, scan, hooks, automatic backup, global-config support, integration tests, and release distribution. Full attribution and the PR #2 to #3 lineage note are in NOTICE.

Last updated: 2026-09-05

## Related projects from the same author

- HardGuard25: https://hardguard25.com/
- Graceful Boundaries: https://gracefulboundaries.dev/
- Skill Provenance: https://skillprovenance.dev/
- Knowledge as Code: https://knowledge-as-code.com/