Icons

Icons show up next to every source in the sidebar, every status badge on a session, and every tool in a tool-result card. Setting them is mostly a "drop a file or a URL in the right place and it just works" affair.

Formats supported

Every icon slot in Fabric Agents accepts the same three formats:

Two formats that are not supported: inline SVG (<svg>...</svg>) and relative filesystem paths (./icons/foo.svg). The icon value must be an emoji, a bare filename, or an absolute URL.

Sources

Each source's config.json has an optional icon field:

{
  "name": "Linear",
  "slug": "linear",
  "type": "mcp",
  "icon": "https://linear.app/favicon.ico"
}

Resolution order:

1. Emoji in config.icon — rendered as text.
2. URL in config.icon — downloaded on first use, cached locally.
3. Auto-discovered icon.svg in the source folder.
4. Auto-discovered icon.png / .jpg / .webp / .gif / .ico in the source folder.

If you drop an icon.svg into ~/.fabric-agent/workspaces/{ws}/sources/{slug}/, you don't need to set icon at all — it'll be found automatically.

Downloaded URL icons save to the source's folder so they work offline after first load. The cache invalidates automatically if the file on disk is older than the source itself.

Statuses

Status icons work the same way. Each entry in {workspace}/statuses/config.json:

{
  "id": "in-progress",
  "name": "In Progress",
  "icon": "in-progress.svg",
  "color": "success"
}

Resolution order:

1. Emoji in the icon field.
2. Explicit local filename — loaded from {workspace}/statuses/icons/{filename}.
3. Auto-discovered SVG at {workspace}/statuses/icons/{status-id}.svg.
4. URL — downloaded to {workspace}/statuses/icons/{id}.{ext}.

Fabric Agents ships default SVG icons for the built-in statuses (backlog, todo, in-progress, needs-review, done, cancelled). They're created in statuses/icons/ on first launch if missing and you can overwrite them at any time.

Tool icons

Tool icons — the little glyphs next to git, npm, docker, python, etc. in tool-result cards — come from a separate registry:

~/.fabric-agent/tool-icons/
├── tool-icons.json
├── git.ico
├── npm.ico
├── python.svg
└── ...

tool-icons.json maps command names to files:

{
  "schema": 1,
  "icons": [
    { "id": "git", "displayName": "Git", "icon": "git.ico", "commands": ["git"] },
    { "id": "npm", "displayName": "npm", "icon": "npm.ico", "commands": ["npm", "npx"] },
    { "id": "python", "displayName": "Python", "icon": "python.svg", "commands": ["python", "python3"] }
  ]
}

When a Bash tool call starts with a command in a commands array, the matching icon shows up on the result card. To add a new tool icon, drop the file in the folder and add an entry to tool-icons.json — the registry reloads on app restart.

Fabric Agents ships a starter registry with common dev tools. Your edits survive app upgrades.

Emoji vs SVG vs raster

• Emoji are rendered as text by the OS, so they match the system emoji font. Cross-platform but visually inconsistent (Apple vs Google vs Microsoft glyphs differ).
• SVG is the preferred format for custom icons: resolution-independent, tiny file size, and the app can tint them to match theme colours when appropriate.
• PNG / JPG / GIF / WebP / ICO also work. For raster, Fabric Agents generates a 32×32 thumbnail at {original}.thumb.png the first time it reads the icon, and uses that thumbnail thereafter for performance. The thumbnail invalidates automatically if the source file changes.

Icons larger than 50 KB on disk aren't inlined into the session storage — the app uses the thumbnail instead. Keep SVGs small (they usually are) and raster images reasonable.

Troubleshooting

Icon doesn't show up

• Make sure the file is in the right directory for the entity type (see the tables above).
• For emoji, check it's actually an emoji character, not text like :wrench: — Fabric Agents doesn't expand emoji shortcodes.
• For URLs, hit the URL in a browser to confirm it returns an image with a proper Content-Type header.

Icon is stale after editing

• Raster thumbnails cache. If you edit icon.png and the old one still shows, delete icon.thumb.png in the same folder and restart the app.

Downloaded URL icon won't refresh

• Delete the cached file in the entity's folder and let Fabric Agents re-download on next session open.

Related

• Colors — EntityColor, the colour counterpart of icons.
• Tool Icons — deeper reference for the tool-icons.json registry.
• Sources — where source icons apply.
• Statuses — where status icons apply.