symlegion 0.3.1

Keep AI instruction files in sync using symlinks

Symlegion

Keep your AI instruction files in sync with zero magic — just symlinks.

Credit: Symlegion is a Python port of the original agentlink tool by Martin Mose Hansen.

Different tools want different files at project root: AGENTS.md (OpenAI/Codex, OpenCode), CLAUDE.md (Claude Code), GEMINI.md, etc. There's no standard, and I'm not waiting for one. Symlegion solves the basic need: keep your personal instruction files (in ~) and your project instruction files in sync without generators. Edit one, they all reflect it.

Creating instruction files is easy with /init commands, but keeping them up to date is the hard part — and expensive too. Good instruction files are often crucial and make a huge difference when using agentic tools. Since they're so important, these files are typically generated with expensive models. Why pay repeatedly to regenerate similar content across different tools?

Future-proof by design: We don't know what tomorrow brings in the AI tooling space, but symlegion is ready. New tool expects .newtool/ai-config.md? Just add it to your config. Complex nested structure like workspace/ai/tools/newframework/instructions.md? No problem. Symlegion automatically creates the directories and symlinks without any code changes needed.

Scope: instruction files only. No MCP .mcp.json or chain configs. Simple on purpose.

---

Why Symlegion?

• One real file, many aliases — pick a source (CLAUDE.md or AGENTS.md or whatever), symlink the rest.
• No codegen — no templates, no transforms, no surprise diffs.
• Project + global — works in repos and under ~/.config/….
• Idempotent — re-run safely; it fixes broken/misdirected links.
• Portable — works on macOS and Linux.
• Future-ready — handles any directory structure, automatically creates paths. Tomorrow's AI tool? Just add its path.

---

How it works

You tell Symlegion which file or folder is the source, and which other paths should link to it. Symlegion creates/fixes symlinks accordingly.

• mode: direct is the original behavior and the default.
• mode: recursive searches multiple roots for matching projects and creates links inside each match.

# .symlegion.yaml (in project root)
- source: CLAUDE.md
  links:
    - AGENTS.md                          # OpenCode, Codex
    - .github/copilot-instructions.md    # GitHub Copilot
    - .cursorrules                       # Cursor AI
    - GEMINI.md                          # Gemini CLI
- source: prompts/shared
  links:
    - .ai/prompts                        # Folder symlink

Result:

./CLAUDE.md                           # real file you edit
./AGENTS.md                           -> CLAUDE.md          (symlink)
./.github/copilot-instructions.md     -> ../CLAUDE.md       (symlink)
./.cursorrules                        -> CLAUDE.md          (symlink)
./GEMINI.md                           -> CLAUDE.md          (symlink)
./.ai/prompts                         -> ../prompts/shared  (symlink dir)

Global mode (in HOME) is the same idea:

# ~/.config/symlegion/config.yaml
- source: ~/.config/claude/CLAUDE.md
  links:
    - ~/.config/opencode/AGENTS.md
    - ~/.config/some-tool/INSTRUCTIONS.md

---

Install

uv tool install symlegion

Or run without installing:

uv run symlegion.py --help

---

Usage

Getting started

# Initialize in your project
symlegion init

# Edit the created .symlegion.yaml to match your needs
# Create your source file (e.g., CLAUDE.md)

# Sync to create symlinks
symlegion sync

init creates a starter .symlegion.yaml with both direct and recursive examples.

The starter config assumes OpenCode as the source of truth and includes mappings for:

• rules: AGENTS.md -> CLAUDE.md, .claude/CLAUDE.md, .goosehints.
• commands/prompts/recipes: .opencode/commands/ -> .claude/commands/, .pi/prompts/, .goose/recipes/.

Commands

symlegion init
symlegion sync
symlegion check
symlegion clean
symlegion doctor

Command behavior

• init creates a starter YAML file. By default it writes .symlegion.yaml in the current directory. With --config, it writes to the provided path.
• sync validates each source and creates or repairs the configured links.
• check reports source and link status without changing anything.
• clean removes only links managed by the selected config file. It never removes source files or folders.
• doctor checks symlink support, binary availability, and default config locations.

Helpful flags

symlegion sync --dry-run
symlegion sync --force
symlegion --verbose sync
symlegion --config ~/somewhere/project.yaml sync

• --config chooses a specific YAML file.
• --dry-run previews changes without writing anything.
• --force allows Symlegion to replace wrong targets, replace existing non-symlink paths during sync, and accept a symlink as the source.
• --verbose prints each source and link as it is processed.

Without init (auto-config)

symlegion sync

What it does:

• If --config is provided, Symlegion uses that file.
• Otherwise it reads .symlegion.yaml in the current directory.
• It creates or fixes symlinks listed under each group so they point to that group's source.

If there's no .symlegion.yaml in CWD:

• Falls back to ~/.config/symlegion/config.yaml (global).
• If missing, it auto-creates a sane default and tells you.

Config file path resolution

• symlegion sync / check / clean:
  • use --config <file> when provided.
  • otherwise use .symlegion.yaml in the current working directory.
  • otherwise fall back to ~/.config/symlegion/config.yaml.
• symlegion init:
  • creates .symlegion.yaml in the current working directory by default.
  • creates the file passed through --config when provided.

---

Config

Project config (recommended)

Place a single file at repo root:

.symlegion.yaml

- source: CLAUDE.md
  links:
    - AGENTS.md
    - OPENCODE.md
- source: prompts/shared
  links:
    - .ai/prompts

Notes:

• Omitting mode is the same as mode: direct.
• Each source can be a real file or a real folder, but not a symlink unless you use --force.
• A config file is a YAML list of groups. Each group has one source, one or more links, and optional recursive fields.

Direct mode

direct is the default mode and matches the original Symlegion behavior.

- mode: direct
  source: CLAUDE.md
  links:
    - AGENTS.md
    - OPENCODE.md

• source can be absolute or relative.
• Relative source and links are resolved from the folder that contains the YAML config file.
• Absolute source values stay absolute.
• ~ expands to $HOME.
• Direct mode is best when one repo or one config file explicitly manages known paths.

Recursive mode

Use recursive when you want Symlegion to scan one or more parent folders, find matching projects, and create the same symlink layout inside each one.

- mode: recursive
  source: .opencode/commands/
  links:
    - .claude/commands/
    - .pi/prompts/
  search:
    - ~/koofr/workspace/
    - ~/code/
  depth: 3

• In recursive mode, source and every entry in links must be relative paths.
• search entries may be absolute or relative.
• Relative search entries are resolved from the folder that contains the YAML config file.
• ~ in search entries expands to $HOME.
• If depth is omitted, Symlegion uses 5.
• Symlegion walks each search root down to depth levels, looking for source in each candidate folder.
• When it finds a match, it creates every link in links relative to that matched folder root.
• If one or more search paths do not exist, Symlegion prints a warning and continues.
• Recursive mode is best when one config file manages many repos that share the same layout.

How recursive matching works

Given this config:

- mode: recursive
  source: .opencode/commands/
  links:
    - .claude/commands/
    - .pi/prompts/
    - .goose/recipes/
  search:
    - ~/code/
    - ../workspace/
  depth: 3

• Symlegion scans every folder under each search root until depth 3.
• When it finds a folder containing .opencode/commands/, that folder becomes the matched project root.
• It then creates:
  • .claude/commands/ -> .opencode/commands/.
  • .pi/prompts/ -> .opencode/commands/.
  • .goose/recipes/ -> .opencode/commands/.
• If ~/code/client-a/project-x matches, all links are created inside ~/code/client-a/project-x.

Selected config examples

Starter config generated by init:

- mode: direct
  source: AGENTS.md
  links:
    - CLAUDE.md
    - .claude/CLAUDE.md
    - .goosehints

- mode: direct
  source: .opencode/commands/
  links:
    - .claude/commands/
    - .pi/prompts/
    - .goose/recipes/

# - mode: recursive
#   source: .opencode/commands/
#   links:
#     - .claude/commands/
#     - .pi/prompts/
#     - .goose/recipes/
#   search:
#     - ~/koofr/workspace/
#     - ~/code/
#   depth: 3

Global config

~/.config/symlegion/config.yaml

- source: ~/.config/claude/CLAUDE.md
  links:
    - ~/.config/opencode/AGENTS.md

---

Platform notes

• macOS + Linux: standard POSIX symlinks (ln -s) — works the same.
• Git: symlinks are stored as links (not file copies). That's fine; teams who dislike that can add them to .gitignore.

Gitignore patterns

Since symlegion creates multiple instruction files but only one is the real source, you can gitignore all AI instruction files except your chosen source:

# Ignore all AI instruction files
AGENTS.md
CLAUDE.md  
GEMINI.md
OPENCODE.md
.cursorrules
.github/copilot-instructions.md

# But track your chosen source file (example: tracking CLAUDE.md)
!CLAUDE.md

This keeps your repository clean while ensuring your source file is version controlled. Symlegion will create the source file if it doesn't exist when running sync.

• Editors/IDEs: most follow symlinks transparently.

---

FAQ

Why not templates or generators?
Because 90% of the time the files should be identical. When they're not, this tool isn't the right fit (or add a second source and stop linking that one).

What if my source differs per project?
Perfect—put a .symlegion.yaml in each repo and choose the source you actually edit there.

Can the source be AGENTS.md instead of CLAUDE.md?
Yes. The source is whatever you want to edit. The others link to it.

What happens when a new AI tool comes out?
Just add its expected path to your config. If "SuperCoder AI" expects .supercoder/prompts/main.md, add that path and run symlegion sync. Directories are created automatically, and the symlink points to your chosen file or folder source. Zero code changes, zero updates needed.

MCP / .mcp.json?
Out of scope. Formats differ between tools; symlinking a single JSON to multiple consumers usually doesn't make sense.