---
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). |
| `--lessons` | Scaffold the project-level lessons recall + capture subsystem: inject the always-on trigger into `_root.md`, seed the `lessons` skill manual under `skills/lessons/`, and wire a `PostToolUse` recall hook into `hooks.yaml` so [hook mode](../lessons/#hook-mode-deterministic-recall) is deterministic on hook-capable targets. Cannot be combined with `--global`. |

## Interactive wizard

On an interactive terminal, `agentsmesh init` runs a short wizard:

1. **Targets** — multi-select which tools to generate for. Nothing is pre-selected, so you must pick at least one; the recommended tools are listed first.
2. **Import** — if existing tool configs are detected (Cursor, Claude Code, …), asks whether to import them all into `.agentsmesh/`.
3. **Lessons** — enable the shared recall/capture memory (default **yes**).
4. **Generate** — optionally run `generate` right away.

Every step after the first offers a **↩ Back** choice to return to the previous step and change an answer (your earlier selections are kept). Nothing is written until the end, so **Ctrl-C cancels cleanly** — no partial files.

| Scope | Wizard behavior |
|-------|-----------------|
| project | All four steps above. |
| `--global` | Target list limited to global-capable tools; the **Lessons step is omitted** (lessons is project-only). |

The wizard is **skipped** — and the original non-interactive behavior runs — with `--yes`, `--json`, or in a non-TTY/CI shell. Scripted and CI usage is unchanged.

## Already initialized

Once `agentsmesh.yaml` exists, init is protective:

- `agentsmesh init` (or `--global`) → stops with **`Already initialized. agentsmesh.yaml exists. Remove it first to re-init.`** Nothing changes; the wizard never starts.
- `agentsmesh init --lessons` → **adds the lessons subsystem retroactively** without touching your config or scaffold (see [Enable lessons recall](#enable-lessons-recall)). Idempotent — safe to re-run.

To start fresh, delete `agentsmesh.yaml` (and `.agentsmesh/` for a clean slate) and run `init` again.

## 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
  lessons/                # Created only with --lessons
    lessons.json          # Canonical recall/capture graph
  skills/
    lessons/              # Tier-2 manual, seeded with --lessons
      SKILL.md            # Full recall/capture operating manual
.gitignore                # Updated: agentsmesh.local.yaml (+ lessons/recall-log.jsonl with --lessons)
```

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. The wizard offers to import everything it finds (a single yes/no); `--yes` imports all of them non-interactively.

## Examples

### Interactive mode

```bash
agentsmesh init
```

Launches the [wizard](#interactive-wizard): import detected configs, pick targets, toggle lessons, optionally generate.

### 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.

### Enable lessons recall

`--lessons` works on a **fresh or already-initialized** project — it's how you add lessons later if you skipped them during init:

```bash
agentsmesh init --lessons   # fresh, or retroactively on an existing project
agentsmesh generate
```

It scaffolds the recall/capture graph (`.agentsmesh/lessons/lessons.json`), injects a tool-agnostic **trigger** into `.agentsmesh/rules/_root.md`, and seeds the full operating manual as a `lessons` skill. After `generate`, every target gets the always-on trigger (rules are native everywhere) and skill-capable targets also get the on-demand manual — agents query the graph before edits/commands and capture failures after.

On an existing project it leaves your config and canonical files untouched and is idempotent; it also adds `.agentsmesh/lessons/recall-log.jsonl` to `.gitignore` so opt-in telemetry never dirties the worktree. Cannot be combined with `--global` (lessons is project-only).

### 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 the project is already initialized (`agentsmesh.yaml` exists), `init` stops with an "already initialized" error instead of overwriting anything. Use `agentsmesh init --lessons` to add lessons to an existing project, or remove `agentsmesh.yaml` to re-init. See [Already initialized](#already-initialized).
</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`
