---
draft: false
title: Local Development Overrides
description: Use agentsmesh.local.yaml to customize your personal AgentsMesh setup without affecting teammates. Narrow targets, skip features, or tune watch mode.
---

`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

```bash
# 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

```yaml
# 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

```yaml
# agentsmesh.local.yaml
targets:
  - claude-code

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

### Speed up watch mode

```yaml
# 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:

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

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