---
title: "Chat Labels"
id: "1703"
type: "page"
slug: "chat-labels"
published_at: "2026-09-20T20:15:33+00:00"
modified_at: "2026-11-14T11:01:10+00:00"
url: "https://xedant.com/agents/agent/docs/chat-labels/"
markdown_url: "https://xedant.com/agents/agent/docs/chat-labels.md"
excerpt: "Chat labels are colored icons with short names that help you keep your chat list…"
---

# Chat Labels

[https://xedant.com/agents/agent/docs/chat-labels/.md](https://xedant.com/agents/agent/docs/chat-labels/.md)

**Chat labels are colored icons with short names that help you keep your chat list under control.** Every chat can carry one label — for example, “starred” or “question”. The label shows next to the chat name, so one glance at the list tells you where a question is waiting for your reply, where something failed, and what is worth opening first. You can assign a label or take it off at any moment.

## What labels look like

The label’s icon is drawn in its color **before the chat name**. In the chat list the icon is bigger — it catches the eye at once; on the open chat’s page the same label appears smaller, in the breadcrumbs above the title — so you always know which conversation is open. A chat without a label shows a muted gray circle before its name — and that circle is also the button you click to assign one.

While a chat is working, a spinning indicator takes the place of the label icon in the list — so you can instantly see which conversations are busy. The button to the right of such a chat stops its work.

A label has no separate icon of its own — but next to the chat’s name you can see which application created it (Portal, CRM, News, and so on): a chat opened by another product on the same agent is marked with that product’s name, while chats you created yourself show nothing. The chat list search finds a chat by that name too — type “Portal” and see every conversation it started.

A label is assigned from a menu: click the label icon next to the chat in the list, or on the same label chip in the breadcrumbs of the open conversation — the list of labels opens. The first item of the menu is **“No label”**: it takes the label off the chat, if there was one. The label currently in use is marked with a checkmark. At the bottom of the menu there is an **“Edit labels”** item that opens full label management (see below).

## Filtering the chat list by label

The chat list’s header has a label filter. It lets you leave only the conversations you need in the list:

- **All** — the usual list, no filter;
- **With labels** — only chats that have a label;
- **Without labels** — chats with no label;
- **A specific label** (for example, “starred” or “question”) — only chats carrying that label.

The filter’s own icon takes on the color of the selected label, so you can see what the list is filtered by. The label filter works together with text search: the search looks at the chat title, the label name, and the text of the messages — your prompts and the agent’s answers. Service data (tool calls, their results, the model’s reasoning) never enters the search — only what you and the agent wrote to each other is searched. This way you can find every conversation labeled “question”, and every chat where the word you need appears in the title or in the conversation itself.

## Default labels

On first start, if you don’t have a labels file of your own yet, the agent creates five default labels:

| Label | Icon | Color |
| --- | --- | --- |
| starred | star | amber |
| warning | warning (a triangle with an exclamation mark) | yellow |
| error | error (a circle with a cross) | red |
| success | check_circle (a check mark in a circle) | green |
| question | help (a question mark in a circle) | blue |

The default labels are not a mandatory set: you can delete them, rename them, and add your own. Two of them — question and error — the agent uses for automatic labeling of chats (see the auto labels section below): if you delete the question label, questions simply stop being marked automatically.

## Managing labels

All labels are gathered in one place: the settings hub (the gear icon in the header) → the **General** group → the **Chat Labels** card. The window with the list of labels also opens through the “Edit labels” item in the label menu of any chat.

In the window, labels are shown in their display order, each with its icon and color. Here you can add a new label or change an existing one. A label has three properties:

- **Name** — 1 to 50 characters; label names must be unique (case-insensitive, so “Starred” and “starred” are the same thing);
- **Icon** — picked from the built-in icon library: start typing a name and matching options appear; an empty field shows the popular icons;
- **Color** — any color from the palette.

Changes apply immediately: a label with a new name, icon, or color updates in every chat and on every connected device.

**Deleting a label** does not delete chats. Before deletion the agent asks for confirmation: if the label is carried by chats, you see the message “N chats will be unlabeled”, and after the deletion all those chats become unlabeled. If no chat uses the label, the message reads “No chats use this label.”

## The labels.yml file

Labels are stored in the `labels.yml` file in the `.xedant` folder at the project root — next to `skills.yml` and the other service files. The order of entries in the file is the order labels appear in menus and in the filter. Every change made in the “Chat Labels” window rewrites the file at once, so you can open it and see the current state:

```
labels:
  version: "1.0"
  items:
    - name: starred
      icon: star
      color: "#f59e0b"
    - name: question
      icon: help
      color: "#3b82f6"
```

Each label has three fields: `name` (the label’s name), `icon` (an icon from the library), and `color` (a color in the #RRGGBB format).

The file is protected from conflicts. If another process changes labels at the same time (for example, the same app in another browser tab), the agent shows the message “Labels changed elsewhere, reloaded — try again.” — and reloads the list of labels, so you don’t overwrite someone else’s edit.

## Auto labels: question and error

The agent labels some chats on its own, so the important things don’t get lost. Marking happens automatically, without your involvement:

- **“question”** — the chat received an answer that waits for your action: at the end of the answer the agent showed a form to fill in, or a button. Such a conversation is an open question worth coming back to;
- **“error”** — the chat ended in a failure. The label is assigned both when a message about an error appeared in the chat and when the answer was cut short by a failure at the AI provider — there may be no separate error line in that case, but the chat still gets the label. The harness reports such a failure at the end of the turn, so the label does not depend on the provider writing its own error;

An auto label comes off as soon as you return to the chat: you sent a message, clicked a button in a reply, or resumed the conversation. The “error” label holds while the error is the last thing that happened in the chat: tool-progress lines after the error do not clear it — they are the errored turn’s own epilogue — and it comes off when you reply in the chat or the work continues. A hand-picked label always wins over an automatic one: if you labeled the chat yourself, the auto label will not overwrite it. An auto label appears only when a label with that name exists in `labels.yml` — for example, the default question label exists out of the box, and once you delete it, questions stop being marked automatically.

## Related sections

- [Settings](/agents/agent/docs/settings) — where label management lives (the General group);
- [Chat](/agents/agent/docs/chat) — how the chat list that shows labels and the filter is built.

**← Back:** [Chat](/agents/agent/docs/chat)

**Next:** [Settings](/agents/agent/docs/settings)
 →