Installation

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

Quick install

Homebrew (macOS / Linux)

No Node.js required.

brew tap samplexbro/agentsmesh
brew install agentsmesh

Standalone binary

No Node.js required. Linux, macOS, and Windows binaries are published with each release.

curl -fsSL https://github.com/sampleXbro/agentsmesh/releases/latest/download/install.sh | sh

Or download a binary directly from GitHub Releases.

npm / pnpm / yarn

Requires Node.js 20+. Recommended when AgentsMesh is part of a Node.js project’s dev tooling so it’s pinned per repo.

# Global install
npm install -g agentsmesh

# Or as a dev dependency
npm install -D agentsmesh        # npm
pnpm add -D agentsmesh           # pnpm
yarn add -D agentsmesh           # yarn

# Or run without installing
npx agentsmesh --help

Platform support

Linux, macOS, and Windows (native, not WSL).

Tip

Windows support is first-class for every install method: 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.

Which install method should I use?

Method	Requires Node.js	Best for
Homebrew	No	macOS / Linux engineers who want a single managed install
Standalone binary	No	CI runners without Node, locked-down environments, Windows users without npm
npm / pnpm / yarn (-D)	Yes	Node.js projects — pins AgentsMesh per repo so teammates and CI get the exact same version
npx	Yes	Trying it out, one-off commands in Node.js projects

Verify installation

agentsmesh --version
agentsmesh --help

Both agentsmesh and the shorter amsh alias resolve to the same CLI regardless of install method.

IDE autocomplete via JSON Schema

Every canonical 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 and agentsmesh install stamp the appropriate # yaml-language-server: $schema=... directive (or $schema field for JSON) into every file at write time. The URL is pinned to the running package version so the schema referenced always matches the format the file was written with.

Config file	Schema	Written by
agentsmesh.yaml / agentsmesh.local.yaml	schemas/agentsmesh.json	init
.agentsmesh/hooks.yaml	schemas/hooks.json	init
.agentsmesh/permissions.yaml	schemas/permissions.json	init
.agentsmesh/mcp.json	schemas/mcp.json	init
.agentsmesh/installs.yaml	schemas/installs.json	install / uninstall
.agentsmesh/packs/<name>/pack.yaml	schemas/pack.json	install
.agentsmesh/packs/<name>/.agentsmesh-install-manifest.json	schemas/install-manifest.json	install

All schemas resolve via the published https://unpkg.com/agentsmesh@<version>/schemas/<name>.json URLs (no extension required when AgentsMesh is in node_modules/). VS Code needs the Red Hat YAML extension; JetBrains IDEs honor the directive out of the box. See the JSON Schemas reference for the full breakdown, CI validation examples, and SchemaStore plans.

Use as a TypeScript / Node.js library

In addition to the CLI, AgentsMesh exports a typed programmatic API for scripts, IDE extensions, and CI tooling. This path requires Node.js 20+ and npm install agentsmesh (or pnpm/yarn equivalent).

import { generate, importFrom, loadCanonical } from 'agentsmesh';

See the programmatic API reference for the full entrypoint table.

Add scripts to package.json

If you installed via npm/pnpm/yarn, wire AgentsMesh into your project scripts:

{
  "scripts": {
    "sync": "agentsmesh generate",
    "sync:check": "agentsmesh check",
    "sync:watch": "agentsmesh watch"
  }
}

Next step

Continue to Quick Start to scaffold your first canonical config directory.