agentsmesh init — generate AGENTS.md and canonical config

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).
--targets <csv>	Enable exactly these target IDs, skipping detection entirely. An unknown ID stops the run.
--all-targets	Enable every target in the starter set, which is what init did by default before.
--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/, wire the recall hook (PreToolUse, UserPromptSubmit, PostToolUseFailure, SessionStart) into hooks.yaml so hook mode is deterministic on hook-capable targets, and set up the lessons.json merge driver. 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. The tools this project or your machine already uses are pre-selected (the same choice the non-interactive path would make); the recommended tools are listed first. You must keep at least one.
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 non-interactive behavior runs — with --yes, --json, or in a non-TTY/CI shell. Without --yes, a non-interactive init stops with exit code 1 when it finds existing config for a tool it would enable: it would not import that config, so the next agentsmesh generate would replace it (in --global mode, files in your home folder that git cannot restore). Run agentsmesh init --yes to import it first, or pass --targets to leave that tool out.

Already initialized

Once agentsmesh.yaml exists, init is protective:

• agentsmesh init (or --global) → stops with an already-initialized error naming the config file. 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.

Deleting agentsmesh.yaml and re-running init is not a reset. The scaffold only fills gaps: a canonical file that already exists in .agentsmesh/ is never replaced by a template, so your rules, MCP servers, hooks, permissions and ignore patterns survive. For a genuinely clean slate, delete .agentsmesh/ as well.

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
    config.json           # Recall tunables, every field at its default
  skills/
    lessons/              # Tier-2 manual, seeded with --lessons
      SKILL.md            # Full recall/capture operating manual
.gitignore                # Updated: agentsmesh.local.yaml, .agentsmeshcache,
                          # .agentsmesh/.lock.tmp, .agentsmesh/packs/
                          # (+ five lessons runtime entries with --lessons)
.gitattributes            # --lessons only: binds lessons.json to the merge driver

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.

The scaffolded permissions.yaml ships with its allow / deny / ask lists commented out, not scaffolded empty. An explicit allow: [] is a real instruction — “grant nothing” — and targets that project permissions into a shared config file apply it, which would clear permissions you already had. Absent keys mean “AgentsMesh manages nothing here yet”. Uncomment a list when you want to start managing it.

Running agentsmesh init --global creates the same canonical structure under ~/.agentsmesh/ — the same nine scaffolded artifacts, since the scaffolder is not scope-aware:

~/.agentsmesh/
  agentsmesh.yaml
  agentsmesh.local.yaml
  rules/
    _root.md
    _example.md
  commands/
    _example.md
  agents/
    _example.md
  skills/
    _example/
      SKILL.md
  mcp.json
  hooks.yaml
  permissions.yaml
  ignore

Only two init steps are project-only: the .gitignore update and the lessons scaffold (--lessons is rejected with --global).

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. In a script or CI shell without --yes, init refuses instead of enabling a tool whose config it did not import, so nothing is overwritten by accident.

When two tools have a rule, command or agent with the same name, the import keeps both texts. If the texts are the same, one canonical file is kept. If they differ, the first tool’s file keeps its name, and the later tool’s version is saved as <name>-<tool>.md (for example .agentsmesh/rules/typescript-cursor.md). Each file keeps only its own frontmatter, and init prints a warning for each copy. Review both, then merge or delete one before you run agentsmesh generate.

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:

• Wires the recall hook into .agentsmesh/hooks.yaml. When package.json lists agentsmesh as a dependency, the hook runs npx --no --offline agentsmesh lessons hook; otherwise the bare agentsmesh lessons hook. When a Node project does not depend on agentsmesh, init prints a hint: teammates without a global install will not get recall, so add agentsmesh as a devDependency and re-run init --lessons.
• Adds five entries to .gitignore: .agentsmesh/lessons/recall-log.jsonl, capture-log.jsonl and outcome-log.jsonl (all under .agentsmesh/lessons/), the .agentsmesh/lessons/.lessons.lock/ directory, and .agentsmesh/lessons/*.tmp, so runtime files never dirty the worktree.
• Adds .agentsmesh/lessons/lessons.json merge=agentsmesh-lessons to .gitattributes (commit it), and sets the per-clone merge.agentsmesh-lessons.* git config for your clone, then says so. It skips that step, with a warning, when git could not start the driver later: PATH folders from the npx cache (_npx) or from a package script (node_modules/.bin) do not count, and the npx form needs agentsmesh installed at the repository root (root package.json devDependencies) or globally. It leaves a merge driver you configured yourself alone. Teammates get the same setup the next time they run agentsmesh generate. See Team workflow.

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. Removing agentsmesh.yaml and re-running init restores the config file but keeps every canonical file already in .agentsmesh/. See Already initialized.

How init chooses targets

init enables the tools you actually use rather than every tool it supports, because each enabled target writes real files into your project. It takes the first rule that matches:

#	Rule	Result
1	--targets a,b	Exactly those IDs. An unknown ID stops the run.
2	--all-targets	The whole starter set.
3	Tool config in the project	Those tools, e.g. CLAUDE.md and .cursor/rules/ → claude-code, cursor.
4	Tools installed on your machine	Those tools, found from each target’s own home-directory paths (~/.claude/, ~/.cursor/, ~/.config/zed/, …). Nothing is imported from your home directory; it only informs the choice.
5	Nothing found	A minimal set: claude-code, cursor, copilot.

Unless you passed a flag, init prints what it picked and why:

Enabled 3 targets (no tool config or install found, so a minimal set was used):
claude-code, copilot, cursor. Edit agentsmesh.yaml or pass --targets a,b to change them.

A target that opts out of bulk scaffolding (codex-cli, whose root AGENTS.md index collides with the other AGENTS.md-first targets) is never enabled by rules 2 or 4. Rules 1 and 3 still honour it, because naming it or committing its config is explicit evidence.

Generated agentsmesh.yaml

version: 1
targets:
  - claude-code
  - copilot
  - cursor
features:
  - rules
  - commands
  - agents
  - skills
  - mcp
  - hooks
  - ignore
  - permissions

Add or remove target IDs to match your team’s actual tool usage before running generate, or re-run with --targets. See the supported targets for the full list.

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