---
draft: false
title: Local Overrides
description: agentsmesh.local.yaml is gitignored and lets individual developers customize their local setup without affecting the shared team config.
---

`agentsmesh.local.yaml` is gitignored and allows individual developers to customize their local setup without affecting the shared `agentsmesh.yaml` that the rest of the team uses.

## How merging works

`targets` and `features` from the local file **replace** the project values when present, so the common use is to **narrow** scope locally. Because it is a replace (not an intersection), a local file **can also add** a target or feature the shared config omits — it will generate on your machine only. See [Merge behavior](#merge-behavior) for the full per-field rules.

## Common use cases

### Only generate for the tools you use

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

If your team uses both Cursor and Claude Code but you only use Claude Code, this prevents generating `.cursor/` files on your machine.

### Skip features you don't need locally

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

features:
  - rules
  - commands
  - skills
  - mcp
```

Omitting `hooks` and `permissions` means they won't be generated locally (but they still generate in CI and for teammates who don't have this file).

### Faster watch mode

```yaml
# agentsmesh.local.yaml
targets:
  - claude-code  # only regenerate Claude Code during watch
```

With a single target, `agentsmesh watch` regenerates faster.

## gitignore

`agentsmesh init` adds `agentsmesh.local.yaml` to `.gitignore` automatically. If you need to add it manually:

```txt
agentsmesh.local.yaml
```

## Merge behavior

When AgentsMesh loads config it merges local overrides on top of the project config, per field:

| 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 (always comes from `agentsmesh.yaml`) |

Because `targets`/`features` replace and `extends`/`conversions` merge, a local file can change what is generated on your machine beyond a strict subset of `agentsmesh.yaml`. Keep it minimal and remember it only affects your gitignored checkout — not teammates or CI.
