Skip to main content
Synti’s five built-in statuses 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

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.

​
Status fields

​
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 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 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.
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 ids, or a bad defaultStatusId), Synti falls back to the built-in defaults.

​
Validating changes

After a manual edit, check the file with:
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.
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.