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

# Labels

> Organize sessions with additive, colored, optionally-typed tags arranged in a nested tree.

Labels are additive, colored tags you attach to sessions. Where a [status](/statuses/overview) answers "what stage is this session in?" and allows exactly one per session, labels answer "what is this session about?" — and a session can carry zero, one, or many of them. Synti stores a session's labels as a simple list in its metadata.

Labels can also nest into a tree, and they can carry a typed value, which turns a plain tag like `priority` into structured data like `priority::3`.

## Labels vs. statuses

| Aspect      | Labels                          | Statuses      |
| ----------- | ------------------------------- | ------------- |
| Per session | Many                            | Exactly one   |
| Defaults    | None — you define them          | Five built-in |
| Appearance  | Colored dot                     | Icon + color  |
| Structure   | Nested tree (up to 5 levels)    | Flat list     |
| Values      | Optional typed values           | None          |
| Filtering   | Intersection of multiple labels | By status     |

New workspaces start with **no labels** — you add exactly the ones your work needs.

## Typed values

A label can hold a value using the `::` separator, for example `due::2026-01-30`. A label's `valueType` acts as a display hint for how that value renders; Synti infers the actual type when it reads the raw string, trying an ISO date first, then a number, then falling back to text.

| `valueType` | Format                           | Example           |
| ----------- | -------------------------------- | ----------------- |
| `string`    | Arbitrary text (default)         | `topic::billing`  |
| `number`    | Integer or decimal               | `priority::3`     |
| `date`      | ISO `YYYY-MM-DD`                 | `due::2026-01-30` |
| `link`      | URL rendered as a clickable chip | `spec::https://…` |

Values pair naturally with [auto-apply rules](/labels/auto-rules), which extract values from your messages and attach them for you.

## The label tree

Labels form a hierarchy through a `children` array, up to **five levels** deep. Position within an array sets display order. Filtering on a parent includes every session tagged with any of its descendants, so a broad label like `area` can gather everything beneath it.

<Warning>
  Label `id`s must be globally unique across the entire tree, not just within their parent. Use lowercase slugs — alphanumeric characters and hyphens only.
</Warning>

## Colors

Each label renders as a colored dot. Set its `color` to a [system token](/customisation/colors), a token with opacity, or a custom light/dark pair. A label with no color renders as a muted foreground dot.

```json theme={null}
{
  "id": "bug",
  "name": "Bug",
  "color": "destructive"
}
```

```json theme={null}
{
  "id": "feature",
  "name": "Feature",
  "color": { "light": "#6366F1", "dark": "#818CF8" }
}
```

Common conventions: `destructive` for bugs, `accent` for features, `success` for finished work, `info` for metadata, and `foreground/60` for neutral tags. See [Colors](/customisation/colors) for the full palette and opacity rules.

## Configuration

The fastest way to create a label is to ask the agent — for example, "create a red Bug label." To edit by hand, open your workspace's label config:

```text theme={null}
~/.synti/workspaces/{workspace-id}/labels/config.json
```

Each label supports these fields:

| Field       | Required | Purpose                                                               |
| ----------- | -------- | --------------------------------------------------------------------- |
| `id`        | Yes      | Globally unique slug                                                  |
| `name`      | Yes      | Display name                                                          |
| `color`     | No       | System token or custom color                                          |
| `valueType` | No       | Value display hint (`string`, `number`, `date`, `link`)               |
| `children`  | No       | Nested labels                                                         |
| `autoRules` | No       | Regex rules that auto-apply the label ([details](/labels/auto-rules)) |

```json theme={null}
{
  "version": 1,
  "labels": [
    {
      "id": "area",
      "name": "Area",
      "children": [
        { "id": "billing", "name": "Billing", "color": "info" },
        { "id": "auth", "name": "Auth", "color": "accent" }
      ]
    }
  ]
}
```

<Note>
  After editing the file, validate it with `config_validate({ target: "labels" })`. Synti checks the JSON, confirms IDs are unique and correctly slugged, and enforces the five-level nesting limit.
</Note>

## In the app

Labels appear in the left sidebar as a multi-level, expandable section. Click one to filter the session list to matching sessions; clicking a parent includes everything beneath it. Selecting more than one label narrows to sessions that carry all of them — an intersection filter — which makes it easy to answer questions like "billing sessions that are also high priority."

<CardGroup cols={2}>
  <Card title="Auto-apply rules" icon="wand-magic-sparkles" href="/labels/auto-rules">
    Attach labels automatically from patterns in your messages.
  </Card>

  <Card title="Statuses" icon="list-check" href="/statuses/overview">
    The one-per-session workflow state that complements labels.
  </Card>
</CardGroup>