agentsmesh init

Scaffold the canonical config directory. Creates agentsmesh.yaml, agentsmesh.local.yaml, and .agentsmesh/ with a starter root rule.

Usage

agentsmesh init [flags]

Flags

Flag	Description
`--global`	Initialize canonical home config under `~/.agentsmesh/`.
`--yes`	Auto-import all detected tool configs, then add starter examples only under empty canonical folders (skip categories import already filled).

What init creates

Running agentsmesh init in a project root creates:

agentsmesh.yaml           # Project configuration (committed)
agentsmesh.local.yaml     # Local overrides (gitignored)
.agentsmesh/
  rules/
    _root.md              # Starter root rule (included in generation)
    _example.md           # Example rule template (excluded from generation)
  commands/
    _example.md           # Example command template (excluded from generation)
  agents/
    _example.md           # Example agent template (excluded from generation)
  skills/
    _example/
      SKILL.md            # Example skill template (excluded from generation)
  mcp.json
  hooks.yaml
  permissions.yaml
  ignore
.gitignore                # Updated to exclude agentsmesh.local.yaml

Files and directories prefixed with _ are excluded from generation — they exist only as reference templates. The sole exception is _root.md, which is always included as the project-wide root rule.

Running agentsmesh init --global creates the same canonical structure under ~/.agentsmesh/:

~/.agentsmesh/
  agentsmesh.yaml
  agentsmesh.local.yaml
  rules/
    _root.md

Auto-detection

During init, AgentsMesh scans the project for existing AI tool configs from every supported target — .claude/, .cursor/, .github/copilot-instructions.md, and the rest. For each one found, it prompts you to import.

Examples

Interactive mode

agentsmesh init

Prompts for each detected config. You can accept or skip each one individually.

Auto-import everything

agentsmesh init --yes

Imports all detected configs without prompting, then writes the same starter files as a plain init only where a canonical folder is still empty (for example commands/_example.md if nothing was imported under commands/). Useful for scripted setups or when you want to migrate everything at once without losing starter templates for unused features.

Initialize global config

agentsmesh init --global
agentsmesh import --global --from claude-code
agentsmesh generate --global

Global init uses ~/.agentsmesh/ as the canonical home-level source of truth. Choose targets in agentsmesh.yaml that support global mode (for example claude-code, antigravity, codex-cli, cursor); see the supported tools matrix.

New project (no existing configs)

agentsmesh init
# No existing configs detected.
# Created agentsmesh.yaml
# Created .agentsmesh/rules/_root.md
# Updated .gitignore

agentsmesh generate

Generated agentsmesh.yaml

The starter config enables every supported target (except codex-cli, whose root AGENTS.md would collide with the other AGENTS.md-first targets) plus all features:

version: 1
targets:
  # Every built-in target except codex-cli — see /reference/supported-tools/ for the full list.
  - aider
  - amazon-q
  - amp
  # ...
  - windsurf
  - zed
features:
  - rules
  - commands
  - agents
  - skills
  - mcp
  - hooks
  - ignore
  - permissions

Remove any target IDs you don’t use. Add codex-cli only if you’ve disabled the other AGENTS.md-first targets.

codex-cli is supported, but not enabled by default in the starter config because its generated AGENTS.md rule index can conflict with the shared AGENTS.md mirrors emitted by other default targets. Add it manually when your project needs Codex output.

Edit this to match your team’s actual tool usage before running generate.

MCP server

init seeds the AgentsMesh self-serve MCP server entry into .agentsmesh/mcp.json. After running agentsmesh generate, the entry is projected into each target’s native MCP config so AI agents can introspect and mutate canonical configuration directly. See MCP Server.

Next steps

Edit agentsmesh.yaml to configure your targets
Edit .agentsmesh/rules/_root.md with your project guidelines
Run agentsmesh generate