> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# tag

> Catalog resource that defines a tenant-wide label — a name and a color — that you attach to agents for grouping and filtering in the dashboard.

A tag is a tenant-defined `{name, color}` label you attach to [agents](/concepts/agents) for grouping and filtering. The name is the tag's identifier; agents reference it by name. The color lives only on the tag, so every viewer sees the same chip and recoloring a tag is a single edit — no per-agent rewrite.

Attach tags at spawn time with [`murmur spawn --tag`](/cli/spawn) or the [`spawn`](/mcp-server/spawn) tool's `tags` parameter, and filter by them in the [dashboard](/guides/dashboard) sidebar. A tag named at spawn time that does not yet exist is created automatically with a default color.

## Fields

| Name       | Type   | Required | Description                                                                                                                                                                                             |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`     | string | yes      | The tag's identifier and catalog name. A DNS-label slug matching `[a-z0-9][a-z0-9-]{0,62}` (e.g. `release-blocker`). Immutable.                                                                         |
| `color`    | enum   | no       | Chip color from the shared palette. Values: `NOTE_COLOR_RED`, `NOTE_COLOR_YELLOW`, `NOTE_COLOR_GREEN`, `NOTE_COLOR_BLUE`, `NOTE_COLOR_GRAY`. Unset (`NOTE_COLOR_UNSPECIFIED`) renders the neutral chip. |
| `archived` | bool   | no       | When `true`, the tag is archived: hidden from the filter list and not attachable to new agents, but still rendered on agents that already carry it. Default: `false`.                                   |

## Tagging an agent

Tags attach to an agent by name, in three ways:

* **At spawn**, with [`murmur spawn --tag <name>`](/cli/spawn) (repeatable) or the [`spawn`](/mcp-server/spawn) tool's `tags` array.
* **On an existing agent**, by editing the [agent record's](/catalog/agent) `tags`.
* **From the dashboard**, via the agent's context menu.

An agent carries at most 8 tags. A name used at spawn time that matches no existing tag is created with a default color; on an existing-agent edit, a newly added name must reference a tag that already exists and is not archived.

## Examples

### Creating a tag

```bash theme={null}
cat <<'EOF' | murmur set tag release-blocker
color: NOTE_COLOR_RED
EOF
```

### Listing tags

```bash theme={null}
murmur get tag
```

```
release-blocker
needs-review
experiment
```

### Recoloring a tag

```bash theme={null}
murmur patch tag release-blocker --set color=NOTE_COLOR_YELLOW
```

Every agent carrying `release-blocker` updates to the new color — the color lives only on the tag.

### Archiving a tag

```bash theme={null}
murmur patch tag experiment --set archived=true
```

The tag disappears from the dashboard filter list and can no longer be attached to new agents, but agents that already carry it keep rendering it.

### Spawning with tags

```bash theme={null}
murmur spawn --tag release-blocker --tag backend fix-auth Fix the JWT expiry validation
```

## Errors

| Code                  | Meaning                                                                                                   | What to do                                                                                              |
| --------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `INVALID_ARGUMENT`    | `tag name must be a DNS-label slug matching ^[a-z0-9][a-z0-9-]{0,62}$`                                    | Use a lowercase name that starts with a letter or digit and contains only letters, digits, and hyphens. |
| `INVALID_ARGUMENT`    | `tag color <n> is not a valid color`                                                                      | Set `color` to one of the palette values, or leave it unset.                                            |
| `FAILED_PRECONDITION` | `tag "<name>" is attached to <n> live agent(s); archive it instead, or detach it from those agents first` | Archive the tag (`archived: true`) rather than deleting it, or remove it from the listed agents first.  |

## Related

* [`murmur spawn --tag`](/cli/spawn) — attach tags when spawning an agent
* [`spawn`](/mcp-server/spawn) — the MCP tool's `tags` parameter
* [agent](/catalog/agent) — the runtime record whose `tags` field carries attached tag names
* [Dashboard](/guides/dashboard) — filter the sidebar by tag
* [`murmur set`](/cli/set), [`murmur patch`](/cli/patch), [`murmur rm`](/cli/rm) — manage catalog resources