AgentsMesh MCP server

AgentsMesh

One config for every AI coding tool, with a shared memory that learns from your repo.

Every AI coding assistant reads its own config: CLAUDE.md, AGENTS.md, .cursor/rules/*.mdc, .github/copilot-instructions.md, .gemini/settings.json, and more. Keeping rules, prompts, MCP servers, hooks, and permissions the same across Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex CLI, and the rest by hand does not scale, and the copies drift.

AgentsMesh makes .agentsmesh/ the one source. Write rules, commands, agents, skills, MCP servers, hooks, ignore patterns, and permissions once. agentsmesh generate writes every tool's native files, agentsmesh import pulls existing configs back in without loss, and agentsmesh check fails CI when anything drifts.

Your agents learn from your repo. Lessons give every agent, in every tool, one git-tracked memory: capture a rule after a failure, recall it before the next edit. Same mistake, never twice. No other config-sync tool has this.

[!NOTE] Full documentation, guides, and the per-tool reference: samplexbro.github.io/agentsmesh

Install

Every method ships the same CLI (agentsmesh, alias amsh). The npm package also exposes the TypeScript API.

# Homebrew (macOS / Linux), no Node.js required
brew install samplexbro/agentsmesh/agentsmesh

# Standalone binary (Linux / macOS), no Node.js required
# Windows: download agentsmesh-windows-x64.exe from GitHub Releases
curl -fsSL https://github.com/sampleXbro/agentsmesh/releases/latest/download/install.sh | sh

# npm / pnpm / yarn, requires Node.js 20.19+
npm install -g agentsmesh     # or: pnpm add -g agentsmesh / yarn global add agentsmesh
npm install -D agentsmesh     # pin per repo as a dev dependency, then run with npx

Binaries with SHA-256 checksums are on GitHub Releases.

60-second quickstart

agentsmesh init       # detect the tools you use, import their configs, or scaffold fresh
agentsmesh generate   # write each tool's native config from the one source
agentsmesh check      # CI drift gate against .agentsmesh/.lock

On a terminal, init runs a short wizard: pick targets, import detected configs (.cursor/, .claude/, .github/copilot-instructions.md, and more), enable lessons, and optionally generate right away. Nothing is written until you finish. Use --yes for the non-interactive default (in a script, init without --yes stops when it finds existing tool config, so generate never replaces config you have not imported), --global for your user-level config under ~/.agentsmesh/, and npx agentsmesh if you installed it as a dev dependency.

init enables the tools you actually use, not all of them: whatever this project already has config for, else whatever is installed on your machine, else a minimal set of Claude Code, Cursor and Copilot. It prints what it picked. Pass --targets a,b to choose, or --all-targets for everything.

[!TIP] Commit both .agentsmesh/ and the generated tool files, like a lockfile: the tools read the generated files directly, and agentsmesh check keeps the two from drifting.

Before / After

# Before: one copy of the same intent per tool
CLAUDE.md
AGENTS.md
.cursor/rules/*.mdc
.github/copilot-instructions.md
.gemini/settings.json
.windsurf/rules/*.md
.codex/config.toml
.kiro/steering/*.md

# After: one canonical source, generated everywhere
.agentsmesh/
  rules/_root.md      # the root rule every tool projects
  commands/           # reusable slash-style prompts
  agents/             # agent definitions
  skills/             # composable skills with supporting files
  mcp.json            # MCP server definitions
  hooks.yaml          # pre/post tool hooks
  permissions.yaml    # allow/deny rules
  ignore              # paths the assistant must not touch
  lessons/            # optional shared agent memory

agentsmesh.yaml selects targets and features, agentsmesh.local.yaml holds per-developer overrides (gitignored), and .agentsmesh/.lock records the checksums that check enforces. Cross-file links are rewritten to each tool's own paths on the way out.

Teach your agents: lessons

Lessons are a memory of past mistakes that every agent reads before it acts and writes after something goes wrong, so a lesson one agent learns today helps every teammate's agent tomorrow, in any tool.

The memory is one git-tracked file, .agentsmesh/lessons/lessons.json, driven by two commands:

# After a failure, the agent writes the rule down with a trigger:
agentsmesh lessons add "Normalize CLI display paths to forward slashes" \
  --topic windows-paths --trigger-file "src/cli/**/*.ts"

# Before the next edit, any agent in any tool recalls it:
agentsmesh lessons query --file src/cli/output.ts --session auto
# -> "Normalize CLI display paths to forward slashes"

agentsmesh init --lessons wires the loop once: an always-on rule in _root.md, a lessons skill where supported, recall and capture hooks on hook-capable tools, and matching MCP tools (lessons_query, lessons_add) for agents without shell access. Rules can be scoped by file, command, or keyword, or always-on with --scope always. A git merge driver, set up by init --lessons and then by generate in every clone, combines lessons captured on two branches; agentsmesh lessons resolve repairs a conflict that slips through.

Want only the memory? Install the agentsmesh-lessons plugin in Claude Code or Codex, or add npx -y agentsmesh@latest mcp to any MCP client. Inside a git repository the lessons tools work with no init and no agentsmesh.yaml.

Full walkthrough: Teach your AI agents with lessons · agentsmesh lessons reference

How AgentsMesh compares

Ruler and rulesync both cover the common ground well, and rulesync supports more tools than AgentsMesh does. What is left to differentiate is what survives translation: links rewritten per target, a round-trip that loses nothing, a lockfile-backed drift gate, new tools addable without a core release, and a memory that learns.

Capability	AgentsMesh	Ruler	rulesync
Generate native config for many tools	✅	✅	✅
Tools supported (counted from source)	33	~31	~50
Import existing tool config back to source	✅	—	✅
Convert one tool's config directly to another	✅	—	✅
CI drift gate (non-zero exit on drift)	✅	partial	✅
Lint before a target silently drops content	✅	partial	partial
Self-serve MCP server (agent-operable config)	✅	—	✅
--json output + typed programmatic API	✅	—	✅
Lossless round-trip (re-import restores originals)	✅	—	partial
Cross-file links rewritten per target	✅	—	—
Lockfile-verified drift + git-merge recovery	✅	—	—
Target plugins: add a tool without a core release	✅	—	—
Lessons: a shared agent memory that learns	✅	—	—

Verified against each project's source and docs on 2026-09-19. Tool counts are counted from source, not marketing claims, and differ by how variants are tallied. Two newer projects solve adjacent problems rather than this one: capa is a package manager and MCP gateway, and Sentry's dotagents manages skill and MCP dependencies without emitting instruction files. Detail and sources in the alternatives guide; corrections welcome.

Built to be depended on: 12,000+ tests on Linux, macOS, and Windows CI, JSON-Schema-validated configs, npm releases with provenance, and a per-file coverage floor in the test gate.

Highlights

• Lossless two-way sync. When a tool has no native slot for a feature, it is embedded with round-trip metadata instead of dropped. Managed embedding
• Automatic link rebasing. .agentsmesh/skills/api-gen/template.hbs becomes .claude/skills/... or .cursor/skills/... in each generated file. Generation pipeline
• Safe adoption. import, then diff, then generate, then check; nothing is overwritten blind. When several tools have a root rule, they are merged into one _root.md rather than the last one winning, their permissions, ignore patterns and MCP servers add up instead of replacing each other, and init --yes keeps both versions of a same-name rule, command or agent. Existing-project guide
• Output directory safety. generate and convert reject output directories that resolve outside the project (or home directory with --global), checked before any write and under --dry-run too. Stale-file cleanup enforces the same boundary.
• Safe updates. Explicitly empty Claude permission, hook, and MCP configurations clear their generated entries. MCP edits preserve untouched server fields and reject malformed files; skill updates validate supporting files before writing. A permissions list you leave out of permissions.yaml stays as each tool has it. Permissions
• Migrate between tools. convert --from <a> --to <b> rewrites one tool's config directly into another's. convert
• Global mode. ~/.agentsmesh/ syncs personal config to ~/.claude/, ~/.cursor/, ~/.codex/, and more; config commands accept --global. Global paths
• CI-ready. check gates drift, diff previews, merge rebuilds the lock after a Git conflict, and lint warns about content a tool would mishandle. check · lint
• Community packs and extends. Install rules, skills, agents, and commands from any git repo; hooks, permissions, and MCP from remote sources stay off until you opt in, and their MCP servers, permission lists, hooks, and ignore patterns join only settings you manage, so a pack alone never replaces what is already in your tools. install
• Target plugins. Ship a new tool as an npm package with full parity to built-in targets. Build a plugin
• Schema-validated configs. Every config ships a JSON Schema for editor autocomplete. JSON schemas
• Scriptable. A typed API for generate, import, lint, diff, and check, --json envelopes on every command except watch, and an MCP server so agents can operate the config themselves. API · MCP server

Commands

Command	What it does
init	Scaffold .agentsmesh/ and config (interactive wizard on a TTY)
generate	Write native config for every enabled tool
check	Fail when generated files drift from .agentsmesh/.lock (CI gate)
diff	Preview what the next generate would change
import	Pull an existing tool's config into .agentsmesh/
convert	Convert one tool's config directly into another's
lint	Validate canonical config against target constraints
watch	Regenerate target files on save
merge	Rebuild .agentsmesh/.lock after a Git merge conflict
matrix	Print the feature and target support matrix
install · uninstall · installs	Add, remove, and list community packs
refresh	Re-fetch installed packs from their sources
plugin	Add, list, or remove plugin-provided targets
target	Scaffold a new target's source skeleton (for contributors)
lessons	Query and capture agent memory
mcp	Start the AgentsMesh MCP server (stdio)

Run agentsmesh <command> --help for flags, or see the CLI reference.

Supported tools

AgentsMesh generates native config for every major AI coding assistant, plus plugin targets. Native, embedded, and partial support per feature is tracked in the supported-tools matrix.

• CLI agents: Aider, Amp, Claude Code, Codebuff, Codex CLI, Crush, Deep Agents CLI, Gemini CLI, Goose, Kimi Code CLI, OpenCode, OpenHands, Pi Agent, Qwen Code, Rovo Dev, Warp.
• IDE integrations: Amazon Q Developer, Antigravity, Augment Code, Cline, Continue, GitHub Copilot, Cursor, Junie, Kilo Code, Kiro, Roo Code, Trae, Windsurf, Zed.
• Cloud agent platforms: Factory Droid, Jules, Replit Agent.

Project scope (agentsmesh generate)

Feature	Aider	Amazon Q Developer	Amp	Antigravity	Augment Code	Claude Code	Cline	Codebuff	Codex CLI	Continue	GitHub Copilot	Crush	Cursor	Deep Agents CLI	Factory Droid	Gemini CLI	Goose	Jules	Junie	Kilo Code	Kimi Code CLI	Kiro	OpenCode	OpenHands	Pi Agent	Qwen Code	Replit Agent	Roo Code	Rovo Dev	Trae	Warp	Windsurf	Zed
Rules	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native
Additional Rules	Embedded	Native	Embedded	Native	Native	Native	Native	Native	Native	Native	Native	Embedded	Native	Embedded	Embedded	Embedded	Embedded	Embedded	Native	Native	Embedded	Native	Native	Native	Embedded	Native	Embedded	Native	Embedded	Native	Embedded	Native	Embedded
Commands	—	Native	Embedded	Native (workflows)	Native	Native	Native (workflows)	Embedded	Embedded	Native	Native	Embedded	Native	Embedded	Native	Native	Embedded	Partial	Native	Native	Embedded	Embedded	Native	Native	Native	Native	Embedded	Native	Native	Native	Embedded	Native (workflows)	Embedded
Agents	—	Native	Embedded	Native	Native	Native	Native	Partial	Native	Native	Native	—	Native	Native	Native	Native	Embedded	—	Native	Native	Native	Native	Native	Native	—	Native	Embedded	Native	Embedded	Native	—	Embedded	—
Skills	Native	—	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	—	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native
MCP Servers	Partial	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Partial	Native	Native	Native	Native	Native	Native	—	Native	Partial	Native	Partial	Native	Native	Partial	Native
Hooks	Native	Embedded	Partial	Native	Native	Native	Native	Partial	Native	Native	Native	Native	Native	—	Native	Native	Native	Partial	Partial	Partial	Partial	Native	Partial	Native	Partial	Native	Partial	—	—	Native	Partial	Native	—
Ignore	Native	Embedded	Partial	Native	Native	Native	Native	Native	—	Native	—	Native	Native	Partial	Partial	Native (settings-embedded)	Native	Partial	Native	Native	—	Native	Embedded	—	Partial	Native	Partial	Native	Partial	Native	Native	Native	Embedded
Permissions	Partial	Embedded	Partial	Partial	Native	Native	Partial	Partial	Native	—	—	Native	Native	Partial	Native	Partial	Partial	Partial	Partial	Native	Partial	Embedded	Native	Partial	Native	Native	Partial	Native	—	—	Partial	Partial	—

Global scope (agentsmesh generate --global)

Feature	Aider	Amazon Q Developer	Amp	Antigravity	Augment Code	Claude Code	Cline	Codebuff	Codex CLI	Continue	GitHub Copilot	Crush	Cursor	Deep Agents CLI	Factory Droid	Gemini CLI	Goose	Jules	Junie	Kilo Code	Kimi Code CLI	Kiro	OpenCode	OpenHands	Pi Agent	Qwen Code	Replit Agent	Roo Code	Rovo Dev	Trae	Warp	Windsurf	Zed
Rules	Native	Embedded	Native	Native	Native	Native	—	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	—	Native	Native	Native	Native	Native	Native	Native	Native	—	Native	Native	Native	Native	Native	Native
Additional Rules	Embedded	Embedded	Embedded	Embedded	Native	Native	Native	Embedded	Embedded	Native	Embedded	Embedded	Native	Embedded	Embedded	Embedded	Embedded	—	Embedded	Native	Embedded	Native	Native	Native	Embedded	Native	—	Native	Embedded	Native	Embedded	Embedded	Embedded
Commands	—	Native	Embedded	Native (workflows)	Native	Native	Native (workflows)	Embedded	Embedded	Native	—	Embedded	Native	Embedded	Native	Native	Embedded	—	Native	Native	Embedded	Embedded	Native	Native	Native	Native	—	Native	Native	Native	Embedded	Native (workflows)	Embedded
Agents	—	Native	Embedded	Native	Native	Native	—	Partial	Native	Native	Native	—	Native	Native	Native	Native	Embedded	—	Native	Native	Native	Native	Native	Native	—	Native	—	Partial	Embedded	Native	—	Embedded	—
Skills	Native	—	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	—	Native	Native	Native	Native	Native	Native	Native	Native	—	Native	Native	Native	Native	Native	Native
MCP Servers	Partial	Native	Native	Native	Native	Native	—	Native	Native	Native	Native	Native	Native	Native	Native	Native	Native	—	Native	Native	Native	Native	Native	Native	—	Native	—	Partial	Native	Native	Native	Native	Native
Hooks	Native	Embedded	Partial	Native	Native	Native	Native	Partial	Native	Native	Native	Native	Native	Native	Native	Native	Native	—	Embedded	Partial	Native	Partial	Partial	Native	Partial	Native	—	—	Native	Native	Partial	Native	—
Ignore	Native	Embedded	Partial	—	—	Native	—	—	—	Native	—	Native	Native	Partial	Partial	—	Native	—	—	—	—	Native	Embedded	—	Partial	—	—	—	Partial	—	Partial	Native	Embedded
Permissions	Partial	Embedded	Partial	Native	Native	Native	Partial	Partial	Native	Native	Partial	Native	Native	Embedded	Native	Native	Native	—	Native	Native	Native	Native	Native	Partial	Native	Native	—	Partial	Native	Partial	Native	Partial	Native