智能代理网格

npm / pnpm / yarn (recommended for Node.js projects) — requires Node.js 20+

```bash npm install -g agentsmesh # global

or as a dev dependency, pinned per repo:

npm install -D agentsmesh # npm pnpm add -D agentsmesh # pnpm yarn add -D agentsmesh # yarn

Install

Pick whichever matches your environment — every install method ships the same CLI (agentsmesh and the amsh alias) and the same TypeScript library.

or run once without installing:

npx agentsmesh --help ```

The Node-based install also exposes the typed programmatic API for scripts and CI tooling.

---

60-second quickstart

Works on Linux, macOS, and Windows. Install via Homebrew, a standalone binary, or any Node.js package manager, then:

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

• init — creates agentsmesh.yaml, agentsmesh.local.yaml, and the canonical .agentsmesh/ directory.
• generate — writes CLAUDE.md, AGENTS.md, .cursor/, .github/copilot-instructions.md, etc. from canonical sources.
• check — exits non-zero if generated files have drifted from .agentsmesh/.lock. Drop into CI.

If you installed via npm install -D agentsmesh (also pnpm add -D / yarn add -D), prefix each command with npx. The CLI ships as both agentsmesh and the shorter alias amsh.

---

CLI usage

agentsmesh init [--global] [--yes]
agentsmesh generate [--global] [--targets <csv>] [--check] [--dry-run] [--force] [--refresh-cache]
agentsmesh import --from <target> [--global]
agentsmesh convert --from <target> --to <target> [--global] [--dry-run]
agentsmesh diff [--global] [--targets <csv>]
agentsmesh lint [--global] [--targets <csv>]
agentsmesh watch [--global] [--targets <csv>]
agentsmesh check [--global]
agentsmesh merge [--global]
agentsmesh matrix [--global] [--targets <csv>] [--verbose]
agentsmesh install <source> [--sync] [--path <dir>] [--target <id>] [--as <kind>] [--name <id>] [--extends] [--all] [--dry-run] [--global] [--force]
agentsmesh uninstall <name>[,<name>...] [--all] [--keep-pack] [--keep-generated] [--dry-run] [--global] [--force]
agentsmesh installs list [--global]
agentsmesh plugin add|list|remove|info [--version <v>] [--id <id>]
agentsmesh target scaffold <id> [--name <displayName>] [--force]

agentsmesh --help prints the same surface; agentsmesh <cmd> --help is also supported.

Demo

A quick sample of the canonical → native projection:

agentsmesh init
find .agentsmesh -maxdepth 2 -type f      # see the canonical scaffold
agentsmesh generate
agentsmesh diff                       # preview future changes
agentsmesh check                      # CI-style drift gate

On macOS/Linux you can also run tree .agentsmesh if you have tree installed.

---

Safe adoption in an existing repository

If your repo already has .cursor/, .claude/, .github/copilot-instructions.md, or other native files, you don't have to delete them. The recommended flow imports them into .agentsmesh/ first, lets you preview the projection, and only then trusts generate.

agentsmesh import --from cursor   # or claude-code, copilot, codex-cli, gemini-cli, windsurf, amp, zed, warp, ...
agentsmesh diff                   # patch-style preview of what generate would change
agentsmesh generate               # write native configs (back) from canonical
agentsmesh check                  # add to CI to detect drift

What this gets you:

• import reads existing tool configs and writes equivalent canonical files into .agentsmesh/ — round-trip metadata is preserved so re-import doesn't lose information.
• diff shows the unified patch every output file would receive, so you can review before any write.
• check reads .agentsmesh/.lock and fails the build if the canonical sources and the generated files disagree.

import --from accepts any built-in target ID listed in the Supported Tools matrix. Plugin targets are valid too.

---

Global mode (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 with a global layout supports global mode. Every CLI command (diff, lint, watch, check, merge, matrix) accepts --global. Global mode paths per tool →

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 github:team/prompts --path workflows --as commands --extends
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. install --extends records a linked extends: entry instead of materializing a pack; when paired with --as, the forced kind is persisted as extends[].as so flat markdown directories continue to load as commands, agents, rules, or skills during later generate runs. Anthropic-style skill packs (root skills/, agents/, references/, .claude/commands/, …) are auto-detected by a multi-signal classifier and imported as a bulk set in a single command — no --as needed. The discriminator is strict enough that legacy tool-native and canonical-agentsmesh repos still take their original code paths (verified by 5 backcompat fixtures).

List and remove installed packs:

agentsmesh installs list                       # NAME / SOURCE / FEATURES / INSTALLED table
agentsmesh uninstall <name>                    # rm pack dir, drop installs.yaml/extends entry, clean generated outputs
agentsmesh uninstall --all                     # sweep every install in this scope
agentsmesh uninstall <name> --keep-pack        # only drop yaml entries; leave .agentsmesh/packs/<name>/ on disk
agentsmesh uninstall <name> --keep-generated   # skip the final generate; emit a warning about stale target files
agentsmesh uninstall <name> --dry-run          # preview; no writes

Each install writes .agentsmesh-install-manifest.json next to the pack with per-file sha256 hashes; uninstall compares current contents against that manifest and prompts before deleting locally-modified files. --force accepts the documented defaults (bulk = accept all, broken-link = leave-with-warnings, modified = delete-anyway). .agentsmesh/.install.lock serialises install/uninstall so concurrent runs on the same project fail fast rather than racing on disk.

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.

Environment variables

---

TypeScript / 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+.

---

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. By default a failed plugin import logs a warning and is skipped; set strict: true on the plugin entry or run AGENTSMESH_STRICT_PLUGINS=1 agentsmesh generate to fail the build instead — useful in CI where a missing target is a real regression. Build a plugin →