Full documentation: samplexbro.github.io/agentsmesh

Why developers use AgentsMesh

• Unify AI coding rules across Claude Code, Cursor, Copilot, Gemini CLI, Windsurf, Codex CLI, and mixed-tool teams.
• Adopt existing projects safely with bidirectional import and generate instead of rewriting every tool config by hand.
• Sync personal global config from ~/.agentsmesh/ to user-level assistant folders such as ~/.claude/, ~/.cursor/, and ~/.codex/.
• Standardize MCP, hooks, permissions, skills, and agents where tools support them natively, with metadata-backed projections where they do not.
• Catch config drift in CI with lock-file checks, diffs, linting, and merge recovery built for team workflows.
• Share and extend configuration with community packs, remote extends, runtime plugins, and a typed programmatic API.

Install

Requires Node.js 20+. Supported platforms: Linux, macOS, and Windows (native, not WSL).

npm install -D agentsmesh       # or: pnpm add -D / yarn add -D
npx agentsmesh --help           # run without installing

CLI aliases: agentsmesh and amsh.

Windows notes: All paths are normalized internally so generated configs and installs.yaml are portable across platforms. Watch mode uses polling on Windows because ReadDirectoryChangesW can miss just-created files in tmpdirs. CI runs the full test suite on Linux, macOS, and Windows.

Quick start

New project

agentsmesh init                 # scaffold .agentsmesh/
# edit .agentsmesh/rules/_root.md
agentsmesh generate             # produce configs for every enabled tool

Existing project — adopt with one import

agentsmesh import --from cursor       # or claude-code, copilot, codex-cli, ...
agentsmesh generate

Personal global config

agentsmesh init --global
agentsmesh import --global --from claude-code
agentsmesh generate --global          # writes to ~/.claude/, ~/.cursor/, etc.

High-demand features

AI coding config sync for every tool

AgentsMesh generates native configuration for every major AI coding assistant. Each tool's files are produced from a single .agentsmesh/ directory with support for rules, commands, agents, skills, MCP servers, hooks, ignore patterns, and permissions:

When a tool lacks native support for a feature, AgentsMesh embeds it with round-trip metadata — no data loss on re-import. See the supported tools matrix for per-tool native vs. embedded breakdown.

Bidirectional import and lossless generate

Use agentsmesh import --from <tool> to migrate existing AI tool configs into canonical .agentsmesh/ files, then agentsmesh generate to project them back out. Managed embedding, reference rewriting, and lock metadata preserve projected features so commands, agents, and skills can round-trip even when a target stores them differently.

Global mode for personal AI assistant config

.agentsmesh/ at the project level is for teams. ~/.agentsmesh/ at the home level is for personal setup across every repo you touch:

agentsmesh init --global
agentsmesh import --global --from claude-code
agentsmesh generate --global   # writes ~/.claude/CLAUDE.md, ~/.cursor/, ~/.codex/, ~/.windsurf/, etc.

Every built-in target and every plugin supports global mode. Every CLI command (diff, lint, watch, check, merge, matrix) accepts --global. Global mode paths per tool →

Plugins for new AI coding tools

Ship new target support as a standalone npm package — no fork, no core PR:

agentsmesh plugin add agentsmesh-target-my-tool
agentsmesh generate            # plugin targets run alongside built-ins
agentsmesh generate --global   # global mode works for plugins too

Plugins have full parity with built-in targets: project + global layouts, feature conversions, scoped settings, per-feature lint hooks, and hook post-processing. Build a plugin →

Team-safe collaboration & CI drift detection

• agentsmesh check — CI gate that exits 1 if generated files drifted from the lock
• agentsmesh diff — preview what the next generate would change
• agentsmesh lint — validate canonical config against target-specific constraints
• agentsmesh watch — regenerate target files on save during local editing
• agentsmesh merge — recover from three-way .lock conflicts after git merge
• Collaboration config — lock_features and strategy prevent accidental overrides

Community packs and shared config

Install shared skills, rules, agents, and commands from any git repo:

agentsmesh install github:org/shared-config@v1.0.0
agentsmesh install --path rules --as rules github:team/standards
agentsmesh install --sync       # restore all packs after clone

Packs live in .agentsmesh/packs/, track in installs.yaml, and merge into canonical config on every generate.

What to commit and what to gitignore

agentsmesh init writes a .gitignore that follows the recommended convention. The defaults are deliberate:

Why generated configs stay committed: the same reason package-lock.json does. They're deterministic build output that downstream consumers (in this case, the AI tool itself) read directly. Gitignoring them breaks fresh-clone UX and makes agentsmesh check meaningless. PR reviewers also benefit from seeing the projected diff in the format Claude/Cursor/Copilot will actually consume.

If your team has a strong reason to gitignore generated configs (e.g., monorepo size concerns, regenerate-on-checkout hooks), add the target-specific entries manually — but expect to wire agentsmesh generate into your post-checkout flow.

Extending AgentsMesh

• agentsmesh target scaffold foo-ide — generate a built-in target skeleton (10 files: descriptor, generators, importer, linter, tests, fixtures) with global mode, conversion support, and lint hooks pre-wired. The catalog is auto-discovered at build time (pnpm catalog:generate) — no manual edits to target-ids.ts, builtin-targets.ts, or the import-map barrel.
• agentsmesh plugin add <pkg> — load third-party npm packages as runtime targets with full built-in parity. Supports agentsmesh plugin list, info, and remove.

Extending guide → · Building plugins →

Schema-validated configs (IDE autocomplete)

Every config file ships with a generated JSON Schema, so VS Code, JetBrains, and other editors give you autocomplete and validation out of the box:

agentsmesh init writes the appropriate # yaml-language-server: $schema=... directive (or $schema field for JSON) into each canonical file, so editors pick up validation immediately.

Supported tools — feature matrix

Project scope (agentsmesh generate)

Global scope (agentsmesh generate --global)

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

Programmatic API

AgentsMesh is also importable as a typed ESM library, so you can drive every CLI capability — generate, import, lint, diff, check — from scripts, IDE extensions, MCP servers, or CI without spawning the CLI. Public entrypoints: agentsmesh (full surface), agentsmesh/engine, agentsmesh/canonical, agentsmesh/targets.

loadProjectContext() mirrors what the CLI does on startup: resolves config, applies local overrides, loads plugins, materializes extends and installed packs, and reads the canonical directory. The result is a single context value you can pass to generate, lint, or diff — the same surface the CLI uses.

import {
  loadProjectContext,
  generate,
  lint,
  diff,
  check,
  importFrom,
  registerTargetDescriptor,
  type GenerateResult,
  type LintResult,
  type LockSyncReport,
  type TargetDescriptor,
} from 'agentsmesh';

// CLI-parity generate pattern: config, plugins, extends, packs, then generation.
const project = await loadProjectContext(process.cwd());
const results: GenerateResult[] = await generate(project);

// Lint — pure, returns structured diagnostics + hasErrors.
const lintResult: LintResult = await lint(project);

// Diff — runs generate internally, returns unified diffs + summary.
const { diffs, summary } = await diff(project);

// Check — lock-file vs current canonical drift report.
const drift: LockSyncReport = await check({
  config: project.config,
  configDir: project.configDir,
  canonicalDir: project.canonicalDir,
});

// Import a built-in or registered plugin target back into canonical form.
await importFrom('claude-code', { root: process.cwd() });

// Register a custom target descriptor at runtime (same shape plugins ship).
const myDescriptor: TargetDescriptor = /* ... */;
registerTargetDescriptor(myDescriptor);

Subpath imports are available when you want narrower bundles:

import { generate, lint, diff, check, loadProjectContext } from 'agentsmesh/engine';
import { loadCanonical, loadCanonicalFiles } from 'agentsmesh/canonical';
import { getAllDescriptors } from 'agentsmesh/targets';

Every public symbol resolves to a real .d.ts under strict TypeScript. Full reference in the programmatic API docs — entrypoint table, every function signature, the typed error taxonomy, and the canonical/target type lists. ESM-only; requires Node.js 20+.

Documentation

• Getting Started — installation, quick start
• Canonical Config — rules, commands, agents, skills, MCP, hooks, ignore, permissions
• CLI Reference — init, generate, import, install, diff, lint, watch, check, merge, matrix, plugin, target
• Configuration — agentsmesh.yaml, local overrides, extends, collaboration, conversions
• Guides — adopting in existing projects · multi-tool teams · sharing config · CI drift detection · community packs · building plugins
• Reference — supported tools matrix · generation pipeline · managed embedding

Contributing

Contributions welcome. Keep changes small, test them, and prefer editing canonical .agentsmesh/ sources over generated files.

pnpm install
pnpm build
pnpm test
pnpm lint
pnpm typecheck

License

MIT