{"slug": "agentstow-canonical-configs-fanned-out-to-all-your-ai-coding-agents", "title": "Agentstow: Canonical configs, fanned out to all your AI coding agents", "summary": "Agentstow, a new open-source tool, lets developers manage a single canonical store of AI coding agent configs—skills, MCP servers, instructions, and more—at ~/.agents/ and sync them across ten agents like Claude Code, Codex, Cursor, and pi via symlinks or key-merges, with no state file. The tool prunes dangling links, preserves foreign or variant configs, and uses exit codes 0, 1, and 2 to signal clean, error, and attention states.", "body_md": "# Canonical configs (skills, MCP, memory, etc.), fanned out to all your AI coding agents.\n\n**One Store at ~/.agents/ holds the single real\ncopy of every config you share** — skills, instructions, MCP servers, slash\ncommands, subagents, hooks.\n\n`agentstow sync`\n\nfans it out to all ten agents\nyou have installed: symlinks where the bytes can be identical, a rendered key-merge\nwhere they can't. There is no state file, and there never will be.\n\n```\n# the Store — one real copy of everything you share\n~/.agents/\n├── skills/          research/  tdd/  code-review/\n├── commands/        ship.md  triage.md\n├── subagents/       reviewer.md\n├── AGENTS.md        your instructions, once\n├── mcp.json         standard mcpServers shape\n└── hooks/           SessionStart.toml  PreToolUse.toml\n```\n\nFan-out\n\n## Edit one file. Every agent sees it.\n\n``` php\n$ ls -l ~/.claude/skills/\nresearch    -> ../../.agents/skills/research\ntdd         -> ../../.agents/skills/tdd\ncode-review -> ../../.agents/skills/code-review\n\n$ ls -l ~/.codex/skills/\nresearch    -> ../../.agents/skills/research\ntdd         -> ../../.agents/skills/tdd\ncode-review -> ../../.agents/skills/code-review\n```\n\nA skill added to the Store appears in Claude Code, Codex, Cursor and pi as a relative symlink — computed, not hand-typed, so the tree survives being moved or restored somewhere else.\n\nopencode and oh-my-pi already read `~/.agents/`\n\nthemselves, so\nagentstow deliberately writes nothing for them. A link of ours that dangles gets\npruned; a link pointing anywhere else is Foreign and is left alone.\n\nTwo mechanisms\n\n## Symlinked where it can be, rendered where it can't.\n\nSkills, instructions, commands and subagents can be byte-identical everywhere, so they are one file seen from ten places — drift is impossible by construction. MCP servers and hooks live inside files the agent also owns, in formats no two agents share, so those are rendered and key-merged: your other keys are preserved, and only the entries named in the Store are rewritten.\n\n```\n# ~/.agents/mcp.json — you write this once\n{\n  \"mcpServers\": {\n    \"serena\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"serena-agent\", \"serena\"]\n    }\n  }\n}\n# ~/.codex/config.toml — merged, not replaced\nmodel = \"gpt-5.3-codex\"        # untouched\n\n[mcp_servers.serena]\ncommand = \"uvx\"\nargs = [\"--from\", \"serena-agent\", \"serena\"]\n\n[projects.\"/Users/you/work\"]   # untouched\ntrust_level = \"trusted\"\n```\n\nNo state\n\n## The filesystem is the state.\n\nOther tools in this space copy, render, and remember what they own in a record beside your configs. When that record disagrees with the disk, your hand-edits lose. agentstow keeps no record at all, because ownership is legible from the disk itself.\n\n- Link identity\n- A symlink that resolves into the Store is ours. It gets canonicalised, and pruned when it dangles.\n- Name identity\n- An MCP server, or a hook whose command appears in the Store, is ours. Every other name in the same file is Foreign and survives untouched.\n- Marker identity\n- A wholly generated file carries one comment line saying so. Marked is ours; unmarked was written by somebody else.\n\nRestraint\n\n## Variants are a feature, not a conflict.\n\n``` bash\n$ agentstow status\nclaude (.claude/skills)  12 linked\n  variant           plannotator — left alone\n  variant-identical old-notes — identical to the\n                    Store, could be re-linked\n  foreign           vendor-thing — not ours\n\nmcp (mcp.json)\n  managed           serena → claude\n  foreign           xapi → claude — not in the\n                    Store — left alone\n\n2 items need attention — run `agentstow sync`.\n```\n\nA real directory shadowing a Store entry is a **Variant**:\ndeliberate, preserved forever, and flagged only when its contents are identical\nto the Store copy, so you can dedupe on purpose rather than by accident.\n\nAnything agentstow did not write is Foreign — reported, never modified. Exit\ncodes are the contract: `0`\n\nclean, `1`\n\nerror,\n`2`\n\nsomething to do.\n\nCoverage\n\n## Ten agents, six families.\n\n| Agent | Skills | Instructions | MCP | Commands | Subagents | Hooks |\n|---|---|---|---|---|---|---|\n| Claude Code | fan-out | import-line | key-merge | fan-out | fan-out | key-merge |\n| Codex | fan-out | symlink | key-merge (TOML) | fan-out | none | key-merge |\n| opencode | native | symlink | key-merge | fan-out | fan-out | none |\n| pi | fan-out | symlink | none | none | none | none |\n| oh-my-pi | native | symlink | native | native | none | none |\n| Gemini CLI | none | symlink | key-merge | render | none | key-merge |\n| Cursor | fan-out | none | key-merge | fan-out | none | none |\n| Windsurf | none | symlink | key-merge | fan-out | none | none |\n| Roo | none | rules-dir link | none | fan-out | none | none |\n| Cline | none | none | key-merge | none | none | none |\n\n*none*means that agent has no such config surface — not that agentstow skipped it.\n\n*native*means the agent reads the Store itself, so writing anything would only duplicate it.\n\nSafety\n\n## Safe to run before you trust it.\n\n``` bash\n$ agentstow sync --dry-run\ndry run — no changes will be made\n\nclaude (.claude/skills)\n  missing   research\n  missing   tdd\nmcp (mcp.json)\n  missing   serena → codex — not in this agent's config yet\n\n3 changes would be made.\n```\n\n- A second sync is a no-op\n- Run it twice and the second run reports\n*Everything is up to date*with the files byte-identical. - Every write is atomic\n- A private temp file, fsync, then an atomic rename — resolved through a symlinked destination, so dotfiles wiring survives.\n- Secrets stay out of the Store and out of your terminal\n`${env:VAR}`\n\nis resolved at sync and redacted from every line of output, so the Store stays committable.- It reports to CI\n`status --json`\n\nand`mcp list --json`\n\n, with exit code`2`\n\nreserved for “there is something to do”.\n\nInstall\n\n## macOS and Linux.\n\n```\n# prebuilt binary — no toolchain, no postinstall script\nnpm install -g agentstow\n\n# or from source, needs Rust 1.97+\ncargo install agentstow\n\n# then, on a machine you have already been using\nagentstow init\n```\n\n`init`\n\ncreates the Store and then tells you what of your existing\nconfig it could take over — per family, with the command that would do it.\n\nLimits\n\n## What it does not do.\n\n**No cross-machine sync.** The Store is an ordinary directory —\nversion it with git or chezmoi. Building sync would mean building conflict\nresolution, and git already won that.\n\n**No memory sync.** Agent memory is not a defined artifact, and\nagentstow will not pretend otherwise.\n\n**No Windows**, no GUI, no daemon, no file watcher. It does not\ninstall skills — it fans out whatever is in the Store, whoever put it there. There\nis no `mcp add`\n\n, because adding a server is editing a documented\nstandard file.", "url": "https://wpnews.pro/news/agentstow-canonical-configs-fanned-out-to-all-your-ai-coding-agents", "canonical_source": "https://agentstow.dev/", "published_at": "2026-08-14 02:20:16+00:00", "updated_at": "2026-08-14 02:40:48.437698+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["Agentstow", "Claude Code", "Codex", "Cursor", "pi", "opencode", "oh-my-pi"], "alternates": {"html": "https://wpnews.pro/news/agentstow-canonical-configs-fanned-out-to-all-your-ai-coding-agents", "markdown": "https://wpnews.pro/news/agentstow-canonical-configs-fanned-out-to-all-your-ai-coding-agents.md", "text": "https://wpnews.pro/news/agentstow-canonical-configs-fanned-out-to-all-your-ai-coding-agents.txt", "jsonld": "https://wpnews.pro/news/agentstow-canonical-configs-fanned-out-to-all-your-ai-coding-agents.jsonld"}}