Local Development Overrides

agentsmesh.local.yaml is gitignored and lets you customize your local development setup without affecting the shared agentsmesh.yaml the rest of the team uses.

Creating the file

# Create your local overrides file
touch agentsmesh.local.yaml

agentsmesh init creates this file automatically and adds it to .gitignore.

Common patterns

Only generate for your tool

agentsmesh.local.yaml

targets:
  - claude-code   # I only use Claude Code

Running agentsmesh generate locally only writes .claude/. CI still generates for all configured targets.

Skip features you don’t need

agentsmesh.local.yaml

targets:
  - claude-code

features:
  - rules
  - commands
  - agents
  - skills
  - mcp
  # omitting: hooks, ignore, permissions

Speed up watch mode

agentsmesh.local.yaml

targets:
  - claude-code   # only regenerate one target during watch

With a single target, agentsmesh watch regenerates significantly faster.

Merge behavior

When AgentsMesh loads config it first reads agentsmesh.yaml, then applies agentsmesh.local.yaml on top. Each field merges differently:

Field	Local merge behavior
targets	Replaces the project list when non-empty
features	Replaces the project list when non-empty
extends	Appended to the project’s extends
conversions	Deep-merged over the project’s conversions
overrides	Deep-merged over the project’s overrides
collaboration	Ignored (cannot be set locally)

Because targets and features replace rather than intersect, a local list does not have to be a subset of agentsmesh.yaml. The common use is to narrow scope (generate for fewer tools/features locally), but a local file can also add a target or feature the shared config omits — it will be generated on your machine only. The local file is gitignored, so anything it adds affects your checkout and not your teammates or CI.

Caution

Because a local file can expand scope, keep it minimal — list only the targets/features you actually want locally. If a teammate reports config you don’t see, check whether your agentsmesh.local.yaml is adding something the shared config doesn’t define.

Team onboarding note

When onboarding a new developer, suggest they create agentsmesh.local.yaml with just their tool:

echo "targets:\n  - claude-code" > agentsmesh.local.yaml

This keeps their local generation fast and focused while still letting CI generate for all targets.