---
draft: false
title: agentsmesh init
description: Scaffold the canonical .agentsmesh/ directory and agentsmesh.yaml. Detects existing AI tool configs and offers to import them.
---

import { Aside } from '@astrojs/starlight/components';

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

## Usage

```bash
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](/reference/supported-tools/) — `.claude/`, `.cursor/`, `.github/copilot-instructions.md`, and the rest. For each one found, it prompts you to import.

## Examples

### Interactive mode

```bash
agentsmesh init
```

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

### Auto-import everything

```bash
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

```bash
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](../reference/supported-tools#global-mode).

### New project (no existing configs)

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

agentsmesh generate
```

<Aside type="note">
  If `.agentsmesh/` already exists, `init` will not overwrite it. It only creates files that don't exist yet.
</Aside>

## Generated agentsmesh.yaml

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

```yaml
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](/reference/mcp-server/).

## Next steps

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