Does a symlink copy my instructions?

No. It points to another file. Reading through a working link reaches that file, so there is one source to maintain. A copied file becomes a separate document that can drift.

Can I put Claude-only instructions after a symlink?

A symlink has no separate document body. Put Claude-only additions in an ordinary CLAUDE.md that imports your shared file, keeping the shared rules in their source.

Why does my teammate see only AGENTS.md inside CLAUDE.md?

Git may have checked out the link as an ordinary text file because symbolic links were disabled or unsupported. Inspect the actual file type and Git configuration, then use a tested link or a regular import file.

Does this share Claude’s chat history or automatic memory?

No. It shares the text in the linked file. Chat history, automatic memory, current task progress, and access to outside tools are separate concerns.

CLAUDE.md Symlink Setup: Share One Instruction File

A CLAUDE.md symlink can point Claude Code at one shared instruction file. Here is how to create it, check that it loads, and avoid broken links on another computer.

July 27, 2026Updated October 21, 20265 min read

A CLAUDE.md symlink is a file-system link that lets Claude Code read instructions from another file, such as AGENTS.md, without maintaining two copies. Use a relative link inside the repository, then test both the link and Claude’s instruction loading; on Windows, an import is often easier to share.

The link solves duplicate instruction text, not project memory. Tools like fenbs keep approved decisions and current task progress outside a local checkout, so the next assistant can pick up the work as well as the rules.

How do you set up a CLAUDE.md symlink?

Choose one real source file, such as AGENTS.md at the repository root. Review its contents and merge any instructions you still need from an existing CLAUDE.md.
Preserve the existing CLAUDE.md before replacing it. Create the link only when that path is available; the commands below deliberately do not force an overwrite.
From the directory containing AGENTS.md, create CLAUDE.md as a relative link to it using the command for your system.
Open CLAUDE.md and confirm that you see the instruction text. Start a fresh Claude Code session in the project and inspect its loaded memory files.
Repeat the check in a separate checkout and on the operating systems your team uses before making the pattern a team convention.

macOS or Linux: example run from the repository root

ln -s AGENTS.md CLAUDE.md
ls -l CLAUDE.md
cat CLAUDE.md

PowerShell: example run beside AGENTS.md

New-Item -ItemType SymbolicLink -Path .\CLAUDE.md -Target .\AGENTS.md
Get-Item -LiteralPath .\CLAUDE.md | Select-Object LinkType, Target
Get-Content -LiteralPath .\CLAUDE.md

Microsoft documents the relative-target syntax and Windows privilege requirements for PowerShell symbolic links (opens in a new tab). Windows may require an administrator session or Developer Mode; if your environment does not permit links, use the import option below.

What does the link actually share?

A symbolic link is a named path that points to another path. Here, CLAUDE.md is the link and AGENTS.md is the real file. When a program follows the link to read it, it reaches the source text. You edit that source rather than keeping two documents synchronized.

The source file should contain instructions that make sense to every tool reading it: the package manager, useful checks, important directories, and boundaries on changes. A link shares those words. It does not make another assistant understand Claude-specific commands or load files by Claude’s rules.

Use the CLAUDE.md examples for possible content. If your only reason for adding the link is compatibility with another filename, check whether Claude Code reads AGENTS.md directly before adding a workaround you may not need.

When is an import the better choice?

Use a regular CLAUDE.md containing @AGENTS.md when you need a portable text file or a place for Claude-specific additions. An import tells Claude Code to include another file; it does not depend on the operating system representing a symbolic link correctly.

Alternative: contents of an ordinary CLAUDE.md file

@AGENTS.md

## Claude-specific instructions
Explain the planned change before editing authentication code.

Anthropic’s guide to sharing one instruction file (opens in a new tab) documents both approaches and recommends the import for Windows collaborators. It also says Claude’s Edit and Write tools refuse to write through a symlink: changes belong in the target file instead.

Choose by the team’s actual workflow. A repository used on several operating systems usually benefits from the ordinary import file. A local project with a tested link setup may need nothing more. The separate guide on where to put CLAUDE.md covers placement; the choice here is how two paths share text.

How do you know Claude loaded the linked file?

Test discovery separately from behavior. Opening CLAUDE.md in a terminal proves the operating system can resolve the link. It does not prove the Claude Code session started in the expected project or included that file as instructions.

Start a fresh session in the intended directory and run /context. Check the Memory files entry for CLAUDE.md. Then give Claude a harmless task with an observable requirement from your source file, such as explaining the required validation command before proposing a change.

Inspect the answer and any proposed action. A file appearing in context establishes loading; following a particular instruction is a second check. If the source cannot be read, fix the path. If loading fails despite a working link, use the CLAUDE.md troubleshooting guide instead of adding more copies.

Will it survive another computer or worktree?

A relative target inside the repository is easier to move than an absolute path to your home directory. Keeping the target in the same checkout also means a branch’s instructions travel with that branch. A link into another checkout can accidentally share instructions between unrelated versions of the project.

Git’s core.symlinks documentation (opens in a new tab) explains an important failure: when that setting is false, checkout creates a small ordinary file containing the target path. A CLAUDE.md that contains only the words AGENTS.md is not the same as a working link or an @AGENTS.md import.

Read-only Git checks for a tracked link

git config --show-origin --get core.symlinks
git ls-files -s -- CLAUDE.md

A tracked symbolic link uses Git mode 120000. Inspect the actual file as well as the index; the index records what Git tracks, while the working directory shows what your tools can read. Do not assume changing a setting fixes an already-created file. Retest the link or choose the import.

What belongs outside the linked file?

Keep stable repository instructions in the source file. Keep changing work state in a project record: which task is in progress, what a person approved, what failed, and where the next session should start. Otherwise the shared file becomes a growing transcript that is hard to review.

For example, “run the relevant tests before finishing” is a reusable instruction. “The checkout test failed after the address change; delivery still needs checking” is a handoff. Connected assistants can read that changing record through fenbs integrations, independently of whether the local instructions use a link or an import.

How fenbs helps

Share the instructions behind the next session

Save reusable working prompts in Skills and prompts, and keep approved project rules in Decisions and rules. Ask each connected assistant to read the project context before it works and save Where we left off afterward. Your local instruction file can stay short while the work record stays current.

Create a free account

Free for one person · No credit card · Works with Claude, ChatGPT, Cursor and more

How to do this with fenbs

Create a free account, then add the project whose assistants need the same starting point.
Record the working rules a person has approved in Decisions and rules. Save a reusable session-start prompt in Skills and prompts.
Connect your supported AI apps and ask each to read the project’s Rules and Where we left off before beginning a task.
Before stopping, save the task’s result, what was checked, and the next step. Check that a fresh session can explain where to continue.

fenbs does not create local symlinks or repair a Git checkout. If you only need two filenames to expose the same static instructions, a repository file may be enough. Use the switching-models guides when your next problem is carrying ongoing work between assistants.