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).
--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 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). 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 — .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

agentsmesh init

Launches the wizard: import detected configs, pick targets, toggle lessons, optionally generate.

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.

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:

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

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

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.

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

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