AgentsMesh — One .agentsmesh/ Directory for Every AI Coding Tool

Every AI coding assistant has its own config format — CLAUDE.md, AGENTS.md, .cursor/rules/*.mdc, .github/copilot-instructions.md, and more. Keeping the same rules, prompts, MCP servers, hooks, and permissions in sync across all of them by hand is tedious, and they drift apart fast.

AgentsMesh is one canonical source for all of it. Write your rules, commands, agents, skills, MCP servers, hooks, ignore patterns, and permissions once in .agentsmesh/, run agentsmesh generate, and every tool gets its native config — with cross-file links automatically rebased to each tool's paths. agentsmesh import pulls existing configs back into the one source, agentsmesh convert migrates straight from one tool to another, and agentsmesh check fails CI when anything drifts.

And your agents learn from your repo. With lessons, an agent saves a short rule whenever something goes wrong — a failing test, a review comment, a wrong assumption — and recalls it automatically before it touches the same files again. One shared memory, read and written by every AI tool you use.

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

Install

Every install method ships the same CLI (agentsmesh, plus the shorter amsh alias) and the same TypeScript library.

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

# Standalone binary (Linux / macOS / Windows) — no Node.js required
curl -fsSL https://github.com/sampleXbro/agentsmesh/releases/latest/download/install.sh | sh

# npm / pnpm / yarn — requires Node.js 20+
npm install -g agentsmesh     # or: pnpm add -g agentsmesh / yarn global add agentsmesh
npm install -D agentsmesh     # pin per-repo as a dev dependency (run with npx)
npx agentsmesh --help         # run once without installing

Standalone binaries are also on GitHub Releases. The Node install additionally exposes the typed programmatic API.

60-second quickstart

Works on Linux, macOS, and Windows. After installing:

agentsmesh init       # scaffold .agentsmesh/ + agentsmesh.yaml
agentsmesh generate   # write native configs for every enabled tool
agentsmesh check      # CI-friendly drift gate against .agentsmesh/.lock

On an interactive terminal, init runs a short wizard — nothing is written until you finish, so Ctrl-C cancels cleanly:

1. Targets — multi-select which tools to generate for (recommended ones first; nothing is pre-selected).
2. Import — if it detects existing configs (.cursor/, .claude/, .github/copilot-instructions.md, …), it offers to import them all into .agentsmesh/.
3. Lessons — enable the shared agent memory (default yes).
4. Generate — optionally run generate right away.

--global runs the same wizard for user-level config (global-capable targets only, no Lessons step). Pass --yes, --json, or run in a non-TTY/CI shell to skip the wizard and keep the scripted behavior. init also seeds the self-serve MCP server into mcp.json.

• generate writes CLAUDE.md, AGENTS.md, .cursor/, .github/copilot-instructions.md, and the rest — rewriting canonical file references to each tool's native paths so cross-file links keep working.
• check exits non-zero when generated files drift from .agentsmesh/.lock — drop it into CI.

Skipped lessons during setup? Add them later (on a fresh or existing repo) with agentsmesh init --lessons. Installed as a dev dependency? Prefix each command with npx.

Before / After

Before — fragmented, assistant-native config in one repo:

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 (+ 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 recall/capture memory

Edit canonical sources, run agentsmesh generate, and every native file above is (re)written for you — always in sync. Alongside the directory, agentsmesh.yaml selects which targets and features are enabled, agentsmesh.local.yaml holds per-developer overrides (gitignored), and .agentsmesh/.lock records the checksums that agentsmesh check enforces.

Teach your agents: lessons

Lessons give your AI agents a memory of past mistakes — read before they touch anything, written after something goes wrong, so the same mistake doesn't happen twice in any tool.

The memory is one git-tracked file, .agentsmesh/lessons/lessons.json, and every agent talks to it through two commands:

• Recall — before an edit or a state-changing command, the agent runs agentsmesh lessons query --file <path> --cmd <command> and follows the rules that match.
• Capture — right after a failure (red test, lint error, review comment, wrong assumption), it saves the rule with agentsmesh lessons add "<rule>" --topic <id> --trigger-file <glob>.

agentsmesh init --lessons && agentsmesh generate   # wire the recall/capture loop once

init --lessons drops a small always-on rule into .agentsmesh/rules/_root.md (so every target gets the habit), seeds the full operating manual as a lessons skill where supported, and wires a recall hook (a PreToolUse first-touch guard plus a PostToolUse fallback) on hook-capable tools; agents without shell access use the matching MCP tools (lessons_query / lessons_add). Because the graph is a normal git-tracked file, a lesson one agent learns today helps every teammate's agent tomorrow, and every change is reviewable like any other diff.

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

Why developers use AgentsMesh

• Bidirectional and loss-free — import reads existing tool configs into .agentsmesh/; generate projects them back out. When a tool has no native slot for a feature, AgentsMesh embeds it with round-trip metadata instead of dropping it, so re-import restores the original canonical files. Managed embedding →
• Automatic link rebasing — canonical references like .agentsmesh/skills/api-gen/template.hbs are rewritten to each tool's native path (.claude/skills/api-gen/template.hbs, .cursor/skills/api-gen/template.hbs, …) in every generated file, so cross-file links stay valid; literal prose and embedded payloads are left untouched. Generation pipeline →
• Agents that learn — the optional lessons memory recalls past-mistake rules before each edit and captures new ones after each failure, shared across every tool and teammate.
• Safe adoption — already have .cursor/, .claude/, or .github/copilot-instructions.md? Run import → diff → generate → check; nothing is overwritten blind. Existing-project guide →
• Migrate between tools — convert --from <a> --to <b> rewrites one tool's config directly into another's native format. convert →
• Global mode — ~/.agentsmesh/ syncs your personal config to ~/.claude/, ~/.cursor/, ~/.codex/, and more. Every command accepts --global. Global paths →
• Team-safe and CI-ready — check is a drift gate against .agentsmesh/.lock, diff previews changes, merge rebuilds the lock after a 3-way Git conflict, and lock_features + per-feature strategy prevent accidental overrides. lint adds cross-target warnings (silent-drop-guard, hook-script-references, rule-scope-inversion) for content a tool would silently mishandle. check → · lint →
• Community packs and extends — install shared rules, skills, agents, and commands from any git repo (install, --sync, refresh, remote extends); a multi-signal classifier auto-detects Anthropic-style skill packs. Elevated artifacts (hooks, permissions, MCP) from remote sources are stripped unless you opt in with --accept-*. Install reference →
• Plugins — ship support for a new tool as a standalone npm package, with full parity to built-in targets (project + global, conversions, lint hooks, hook post-processing). Build a plugin →
• Schema-validated configs — each config ships a JSON Schema, so editors give you autocomplete and validation out of the box. JSON schemas →
• Typed programmatic API — drive generate / import / lint / diff / check from scripts or CI via agentsmesh, /engine, /canonical, /targets, /lessons. API reference →
• Self-serve MCP server — agentsmesh mcp (seeded by init) exposes canonical config as MCP tools so agents can introspect rules, commands, and skills and trigger generate in-conversation. MCP server →
• Scriptable everywhere — every command speaks --json, emitting a single { success, command, data?, error? } envelope for CI and tooling.

[!TIP] Commit both .agentsmesh/ and the generated tool files, the same way you commit package-lock.json: they're deterministic build output that the AI tools read directly, and agentsmesh check guards the two from drifting.

Why not just AGENTS.md?

AGENTS.md is a great shared instruction file, and AgentsMesh emits it natively wherever a tool supports it. But a single markdown file isn't enough on its own: most assistants expose configuration beyond it — Cursor's .cursor/rules/*.mdc and MCP config, Claude Code's agents/skills/commands/hooks/permissions, Copilot's .github/instructions/, Gemini's .gemini/settings.json, and so on — and those surfaces don't overlap. AgentsMesh canonicalizes all of them so you never have to pick one tool's surface as the lowest common denominator.

Commands

| Command | What it does | |---|---| | init | Scaffold .agentsmesh/ + 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/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 (recall / capture) | | mcp | Start the AgentsMesh MCP server (stdio) |

Every command accepts --global (operate on ~/.agentsmesh/) and --json (machine-readable output). 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 you can ship as standalone npm packages. Native vs. embedded support per feature is tracked in the supported-tools matrix.

• CLI agents: Aider, Amp, Claude Code, Codex CLI, Crush, Deep Agents CLI, Gemini CLI, Goose, OpenCode, 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 | Codex CLI | Continue | GitHub Copilot | Crush | Cursor | Deep Agents CLI | Factory Droid | Gemini CLI | Goose | Jules | Junie | Kilo Code | Kiro | OpenCode | 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 | | Additional Rules | Embedded | Native | Embedded | Native | Native | Native | Native | Native | Native | Native | Embedded | Native | Embedded | Embedded | Embedded | Embedded | Embedded | Native | Native | Native | Native | Embedded | Native | Embedded | Native | Embedded | Native | Embedded | Native | Embedded | | Commands | — | — | Native | Partial (workflows) | Native | Native | Native (workflows) | Embedded | Native | Native | — | Native | — | Native | Native | — | — | Native | Native | Embedded | Native | Native | Native | — | Native | — | Native | — | Native (workflows) | — | | Agents | — | Native | — | — | Native | Native | Native | Native | — | Native | — | Native | — | Native | Native | — | — | Native | Native | Native | Native | — | Native | — | 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 | | MCP Servers | — | Native | Native | — | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | — | — | Native | Native | Native | Native | — | Native | — | Native | Native | Native | Native | Partial | Native | | Hooks | — | — | Native | Native | Native | Native | Native | Native | — | Native | Native | Native | Native | Native | Partial | Native | — | — | — | Native | — | — | Native | — | — | — | — | — | Native | — | | Ignore | Native | — | — | — | Native | Native | Native | — | — | — | Native | Native | — | — | Native (settings-embedded) | Native | — | Native | Native | Native | — | — | Native | — | Native | — | Native | — | Native | — | | Permissions | — | — | Native | Partial | — | Native | — | — | — | — | Partial | Partial | — | — | Partial | — | — | — | Native | — | Native | — | Native | — | Partial | — | — | Partial | — | — |

Global scope (agentsmesh generate --global)

| Feature | Aider | Amazon Q Developer | Amp | Antigravity | Augment Code | Claude Code | Cline | Codex CLI | Continue | GitHub Copilot | Crush | Cursor | Deep Agents CLI | Factory Droid | Gemini CLI | Goose | Jules | Junie | Kilo Code | Kiro | OpenCode | 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 | — | | Additional Rules | Embedded | — | Embedded | Embedded | Native | Native | Native | Embedded | Native | Native | Embedded | Native | Embedded | Embedded | Embedded | Embedded | — | Embedded | Native | Native | Native | Embedded | Embedded | — | Native | Embedded | Native | — | Partial | — | | Commands | — | — | Native | Partial (workflows) | Native | Native | Native (workflows) | Embedded | Native | Native | — | Native | — | Native | Native | — | — | Native | Native | Embedded | Native | Native | Native | — | Native | — | Native | — | Native (workflows) | — | | Agents | — | Native | — | — | Native | Native | Native | Native | — | Native | — | Native | — | Native | Native | — | — | Native | Native | Native | Native | — | Native | — | Partial | — | — | — | 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 | — | | MCP Servers | — | Native | Native | Native | Native | Native | Native | Native | Native | — | Native | Native | Native | Native | Native | Native | — | Native | Native | Native | Native | — | Native | — | Native | Native | Native | — | Native | Native | | Hooks | — | — | Native | Native | — | Native | Native | Native | — | — | Native | Native | Native | Native | Partial | Native | — | — | — | — | — | — | Native | — | — | Native | — | — | Native | — | | Ignore | Native | — | — | — | — | Native | Native | — | — | — | — | Native | — | — | — | Native | — | — | Native | Native | — | — | — | — | Native | — | — | — | Native | — | | Permissions | — | — | Native | Partial | Native | Native | — | — | Native | — | — | — | — | — | Native | Native | — | Native | Native | — | Native | — | Native | — | Partial | Native | — | Partial | — | — |

See the full feature matrix for native vs. embedded details and per-tool global paths.

Documentation

• Getting Started — install and first run
• Canonical config — rules, commands, agents, skills, MCP, hooks, ignore, permissions
• CLI reference — every command and flag
• Guides — adopting in an existing repo · teaching agents with lessons · sharing config · building plugins
• Reference — supported tools · generation pipeline · managed embedding · programmatic API

Contributing

Contributions welcome — edit canonical .agentsmesh/ sources, never the generated files. See CONTRIBUTING.md to get set up.

License

MIT