xiantong Docs
Statuses

Customizing Statuses

Add custom statuses and modify existing ones

Just ask your agent. The easiest way to customize statuses is to describe what you need:

  • “Add a Blocked status with a red color”
  • “Create a Waiting status for conversations on hold”
  • “Add an In Review status between In Progress and Done”

The agent handles the configuration automatically.

You can also customize statuses manually by editing the workspace’s status configuration file.

Configuration File#

Status configuration is stored at:

~/.xiantong/workspaces/{workspace-id}/statuses/config.json

Config Schema#

The configuration file has the following structure:

{
"version": 1,
"statuses": [
{
"id": "todo",
"label": "Todo",
"category": "open",
"isFixed": true,
"isDefault": false,
"order": 0
}
],
"defaultStatusId": "todo"
}

Status Properties#

Each status object supports these properties:

PropertyTypeRequiredDescription
idstringYesUnique identifier (lowercase, hyphens only)
labelstringYesDisplay name shown in the UI
category"open" | "closed"YesDetermines inbox vs archive placement
isFixedbooleanYesIf true, cannot be deleted or have label changed
isDefaultbooleanYesIf true, cannot be deleted but can be modified
ordernumberYesDisplay order (lower numbers appear first)
colorstringNoHex color (e.g., "#EF4444") or Tailwind class
iconstringNoEmoji (e.g., "🔥") or URL to icon file

When color is omitted, the design system default is used. When icon is omitted, the app looks for an auto-discovered file at statuses/icons/{id}.{ext} (supports .svg, .png, .jpg, .jpeg).

Adding Custom Statuses#

To add a custom status like “Blocked” or “Waiting”, add a new object to the statuses array:

{
"id": "blocked",
"label": "Blocked",
"color": "#EF4444",
"icon": "🚫",
"category": "open",
"isFixed": false,
"isDefault": false,
"order": 3
}

Make sure to adjust the order values of other statuses if needed to position your new status correctly.

Example: Adding Multiple Custom Statuses#

{
"version": 1,
"statuses": [
{
"id": "backlog",
"label": "Backlog",
"category": "open",
"isFixed": false,
"isDefault": true,
"order": 0
},
{
"id": "todo",
"label": "Todo",
"category": "open",
"isFixed": true,
"isDefault": false,
"order": 1
},
{
"id": "in-progress",
"label": "In Progress",
"icon": "🔄",
"category": "open",
"isFixed": false,
"isDefault": false,
"order": 2
},
{
"id": "blocked",
"label": "Blocked",
"color": "#EF4444",
"icon": "🚫",
"category": "open",
"isFixed": false,
"isDefault": false,
"order": 3
},
{
"id": "waiting",
"label": "Waiting",
"icon": "⏳",
"category": "open",
"isFixed": false,
"isDefault": false,
"order": 4
},
{
"id": "needs-review",
"label": "Needs Review",
"category": "open",
"isFixed": false,
"isDefault": true,
"order": 5
},
{
"id": "done",
"label": "Done",
"category": "closed",
"isFixed": true,
"isDefault": false,
"order": 6
},
{
"id": "cancelled",
"label": "Cancelled",
"category": "closed",
"isFixed": true,
"isDefault": false,
"order": 7
}
],
"defaultStatusId": "todo"
}

Customizing Icons#

Icons can be configured in several ways:

File-based icons (recommended)

Place an SVG file in the statuses/icons/ directory named after the status ID:

statuses/icons/blocked.svg
statuses/icons/waiting.svg

These are auto-discovered - no config needed.

Emoji icons

Set the icon property to an emoji:

"icon": "🔥"

Quick and easy, works everywhere.

URL icons

Provide a URL to an icon file:

"icon": "https://example.com/icon.svg"

The icon is automatically downloaded and cached locally.

SVG Icon Guidelines#

When creating custom SVG icons:

  • Size: 24x24 pixels
  • Use currentColor for stroke/fill to support theming
  • stroke-width: 2
  • stroke-linecap: round
  • stroke-linejoin: round

Changing Colors#

Set the color property to customize a status’s appearance:

{
"id": "blocked",
"label": "Blocked",
"color": "#EF4444",
...
}

You can use:

  • Hex colors: "#EF4444", "#22C55E"
  • Tailwind classes: "text-red-500", "text-green-500"

Fixed Statuses#

The following statuses cannot be deleted or renamed:

IDWhy It’s Fixed
todoDefault status for new conversations
doneRequired closed state for completed work
cancelledRequired closed state for abandoned work

You can still customize their color and icon properties.

Validation#

Always validate your configuration after making changes.

After editing the config file, validate it to catch errors before they cause issues:

config_validate({ target: "statuses" })

The validator checks:

  • Required fixed statuses exist (todo, done, cancelled)
  • No duplicate status IDs
  • defaultStatusId references an existing status
  • At least one status in each category (open and closed)
  • Icon files exist when referenced

Invalid configurations fall back to defaults at runtime, but validation helps catch issues early.

PreviousStatuses