agentsmesh generate

Generate target-specific config files from the canonical .agentsmesh/ directory. This is the primary command you run after editing canonical files.

Usage

agentsmesh generate [flags]

Flags

Flag	Description
--targets <csv>	Comma-separated list of target IDs to generate for. Defaults to all configured targets. If the canonical sources changed, the enabled targets the run left out are recorded in the lock as stale_targets, and agentsmesh check fails until each of them is generated again.
--global	Generate user-level config from ~/.agentsmesh/ instead of project-local config (e.g. claude-code, antigravity, codex-cli; Cursor writes full ~/.cursor/ global surfaces including rules/, AGENTS.md, hooks, ignore, MCP, skills, agents, commands).
--dry-run	Preview changes without writing any files.
--check	Verify sync status only. Exit code 1 if out of sync, or if the project’s lessons graph cannot be read.
--force	Bypass collaboration lock violations.
--refresh-cache	Re-fetch remote extends sources before generating.
--no-cache	Alias for --refresh-cache.

Examples

Generate for all configured targets

agentsmesh generate

Reads agentsmesh.yaml, loads all canonical sources, and writes output for each enabled target.

Generate for specific targets only

agentsmesh generate --targets claude-code,cursor

Only generates .claude/ and .cursor/ output, ignoring other configured targets.

Generate global user-level config

agentsmesh init --global
agentsmesh generate --global --targets claude-code,antigravity,codex-cli,cursor

Reads canonical files from ~/.agentsmesh/ and writes user-level outputs per target (for example Claude Code under ~/.claude/ including settings.json — which carries hooks, since Claude Code has no standalone hooks.json — plus ~/.claudeignore, skills under ~/.claude/skills/ and mirrored to ~/.agents/skills/ only when Codex is not also a global target, optional output-styles/ when outputStyle: true, plus ~/.claude.json for MCP; Antigravity under ~/.gemini/ (rules in ~/.gemini/GEMINI.md, skills in ~/.gemini/config/skills/, commands in ~/.gemini/antigravity/global_workflows/, MCP at ~/.gemini/config/mcp_config.json); Codex CLI under ~/.codex/ plus ~/.agents/skills/; and Cursor under ~/.cursor/ with rules/*.mdc, aggregated AGENTS.md, MCP, hooks, cursorignore, skills, agents, and commands). See the supported tools matrix for the full global-mode map.

The rest of the maintenance commands (install, diff, lint, watch, check, merge, and matrix) also accept --global and operate on the same ~/.agentsmesh/ canonical root.

Preview changes without writing

agentsmesh generate --dry-run

Prints one status line per file — [dry-run] <status> <path> (<target>) — without writing anything. Useful before committing or during debugging. For the actual unified patches, use agentsmesh diff.

CI check mode

agentsmesh generate --check

Exits 0 if generated files match the lock file. Exits 1 if drift is detected. Use this in CI pipelines instead of agentsmesh check when you want the full generation path to be verified. A run that would produce no files still counts a leftover generated file (for example, after the last pack was uninstalled) as drift.

Force through locks

agentsmesh generate --force

Bypasses collaboration.lock_features restrictions. Use when you intentionally need to update locked features like mcp or permissions.

Refresh remote extends

agentsmesh generate --refresh-cache
agentsmesh generate --no-cache   # alias

Forces a re-fetch of all remote extends sources. Without this flag, AgentsMesh uses the local cache at ~/.agentsmesh/cache/.

What generate does

1. Load config — parse agentsmesh.yaml, merge agentsmesh.local.yaml, validate schema.
2. Load canonical sources — read .agentsmesh/ (or ~/.agentsmesh/ with --global), resolve extends (cache or remote), load installed packs, merge everything.
3. Generate per target — for each enabled target, run target-specific generators for rules, commands, agents, skills, MCP, hooks, ignore, and permissions.
4. Rewrite references — internal .agentsmesh/ file paths are rewritten to target-relative paths.
5. Resolve collisions — detect overlapping output paths, prefer native over embedded.
6. Write output — create target directories, write all files, update the lock file (canonical-source checksums plus an outputs map of every generated file’s checksum, so agentsmesh check can later detect direct edits to generated files). Filtered runs (--targets) merge outputs per-path into the existing map; a full run replaces it. A filtered run after a canonical change records the enabled targets it left out as stale_targets, because they were not regenerated from the new sources. The lock is rewritten only when this content changes: a run that changes nothing leaves .agentsmesh/.lock untouched, so the git tree stays clean.
7. Clean stale files — remove previously generated files no longer in the output set. This also runs when a full run produces no files at all, so uninstalling the last pack removes its generated outputs and resets the lock’s outputs map.

Lessons upkeep

In project scope, when the project uses lessons, generate also does a little upkeep for every clone, so a team stays healthy without anyone re-running init --lessons:

• Merge driver. On a normal run it sets this clone’s merge.agentsmesh-lessons.* git config (local config) when .gitattributes binds lessons.json to the driver, and prints what it did. It skips the setup when git could not start the driver later (see Team workflow for the rule), and keeps a driver you configured yourself.
• Unreadable graph. When lessons.json has merge conflict markers, is corrupt, does not match the schema, or was written by a newer agentsmesh, a normal run warns and carries on, and generate --check fails with exit code 1. The same happens while git still holds lessons.json unmerged and the file is missing lessons from the other branch: run agentsmesh lessons resolve before git add.
• Team hint. When the recall hook is wired but the project’s package.json does not list agentsmesh as a dependency, it warns that teammates without a global install will not get lesson recall, and suggests adding agentsmesh as a devDependency and re-running agentsmesh init --lessons.

The recall hook entries themselves are filtered per target: each target keeps them only on the hook events whose output reaches its model. See Hook mode.

Output locations

For Claude Code, explicitly empty canonical configuration clears previously generated entries: allow: [], deny: [], and ask: [] remove permission rules; hooks.yaml containing {} removes hooks; and mcp.json containing {"mcpServers": {}} removes servers. Unrelated settings remain intact. Missing canonical files leave the corresponding user settings alone.

Output directories must resolve inside the project, or inside the home directory with --global. Before writing anything, and under --dry-run too, generation checks every output path and every managed directory of the active targets, and rejects a directory that escapes the boundary through a symlink. The whole run stops with exit code 1 and nothing is written; the error names the path, where it resolves to, and the boundary it escapes. Stale-file cleanup enforces the same rule. Symlinks to directories within the boundary remain supported.

Each target writes to its own native directory (e.g. claude-code → .claude/, cursor → .cursor/, copilot → .github/). The shared AGENTS.md at the project root is emitted by every target that uses it as a root-instruction surface. See the supported tools matrix for the exact project-scope and global-scope paths for every target.

Global mode path resolution

When --global is used, AgentsMesh sets the project root to the user’s home directory (homedir()). All target path constants — such as .cursor/rules/, .claude/skills/, or .cline/data/settings/rules/ — are relative to that root, so they resolve to the expected ~/-prefixed locations (e.g. ~/.cursor/rules/, ~/.claude/skills/).

If ~/.agentsmesh/agentsmesh.yaml does not exist, --global commands fail with a scope-aware error pointing at the missing path and suggesting agentsmesh init --global (or dropping the flag to operate on the current project). The check applies uniformly to generate, import, lint, check, diff, watch, and matrix.

Exit codes

Code	Meaning
0	Success — all files generated.
1	Error, or drift or an unreadable lessons graph detected (with --check).