Skip to main content
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: 
~/.craft-agent/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:
Set the icon property to an emoji:
"icon": "🔥"
Quick and easy, works everywhere.
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.