> ## 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.

# Customizing Statuses

> Add, edit, reorder, and restyle workflow statuses for a workspace, by asking the agent or editing config directly.

Synti's five [built-in statuses](/statuses/overview) cover most workflows, but you can add your own, restyle the ones that ship, and control the order they appear in. There are two ways to do it: ask the agent in plain language, or edit the workspace status config by hand.

## Two ways to customize

<Tabs>
  <Tab title="Ask the agent">
    The simplest path. Describe what you want and let the agent write the config:

    * "Add a Blocked status with a red color."
    * "Create a Waiting status for sessions that are on hold."

    The agent edits the right file, picks a sensible `order`, and validates the result.
  </Tab>

  <Tab title="Edit config">
    Statuses live in a per-workspace JSON file:

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

    Add an object to the `statuses` array for each status you want. See the fields and example below.
  </Tab>
</Tabs>

## Status fields

| Field       | Required | Purpose                                                                               |
| ----------- | -------- | ------------------------------------------------------------------------------------- |
| `id`        | Yes      | Unique lowercase identifier, hyphens allowed                                          |
| `label`     | Yes      | Display name shown in the UI                                                          |
| `category`  | Yes      | `open` (inbox) or `closed` (archive)                                                  |
| `isFixed`   | Yes      | When `true`, the status can't be deleted or renamed                                   |
| `isDefault` | Yes      | When `true`, the status can't be deleted but stays editable                           |
| `order`     | Yes      | Number controlling display sequence                                                   |
| `color`     | No       | A [color](/customisation/colors) — system token, custom value, hex, or Tailwind class |
| `icon`      | No       | An emoji, an SVG file, or a URL to an icon                                            |

```json theme={null}
{
  "version": 1,
  "defaultStatusId": "todo",
  "statuses": [
    {
      "id": "blocked",
      "label": "Blocked",
      "category": "open",
      "isFixed": false,
      "isDefault": false,
      "order": 25,
      "color": "#EF4444",
      "icon": "🚧"
    }
  ]
}
```

## Reordering

The `order` value sets the display sequence, low to high. When you insert a new status, adjust the `order` of surrounding statuses so it lands where you expect — leaving gaps between numbers (10, 20, 30…) makes future insertions painless.

## The default status

`defaultStatusId` names the status applied to every new session. It must reference a status that exists in the file, and it points at `todo` by default. You can repoint it, but `todo` itself can't be deleted.

## Colors

A status `color` accepts the same values as anywhere else in Synti — a [system token](/customisation/colors) like `success`, a custom light/dark object, a hex string like `"#22C55E"`, or a Tailwind class like `"text-green-500"`. Omit it to fall back to the design-system default for that status.

## Icons

Statuses can carry an icon three ways — see [Icons](/customisation/icons) for the full behavior:

* **File.** Drop an SVG named after the status ID (for example `blocked.svg`) in `statuses/icons/`. Synti discovers it automatically. Author it at 24×24 with `currentColor`, stroke width 2, and rounded caps and joins so it tracks your theme.
* **Emoji.** Set `icon` to any emoji directly in the JSON.
* **URL.** Point `icon` at a remote icon file; Synti downloads and caches it locally.

## Protected statuses

Three statuses can never be deleted, because Synti's workflow relies on them:

* `todo` — the starting status for new sessions.
* `done` — the closed state for completed work.
* `cancelled` — the closed state for abandoned work.

You can still recolor and re-icon all three; you just can't remove or rename them.

<Warning>
  Every configuration must keep at least one status in each category — one `open` and one `closed`. If the config is invalid at runtime (a missing required status, duplicate `id`s, or a bad `defaultStatusId`), Synti falls back to the built-in defaults.
</Warning>

## Validating changes

After a manual edit, check the file with:

```text theme={null}
config_validate({ target: "statuses" })
```

The validator confirms the required statuses are present, IDs are unique, `defaultStatusId` resolves to a real status, each category has at least one status, and any referenced icon files exist.

<Note>
  Prefer editing through the agent when you can — it keeps `order` values coherent and runs validation for you, so a typo never silently reverts your workflow to defaults.
</Note>