Codex App: support custom icons and visual identities for subagents

What variant of Codex are you using?

Codex App

What feature would you like to see?

Codex App should allow users to configure a visual identity for custom-agent profiles and spawned subagents.

The core capability should be a user-defined icon. Colors and shapes are useful supporting attributes, but geometric markers alone are too restrictive for users who maintain specialized agents for exploration, implementation, review, monitoring, security, databases, frontend work, deployments, and other recurring workflows.

Proposed configuration

A custom-agent profile could select a built-in semantic icon:

name = "explorer"

[visual]
icon = "lucide:compass"
color = "blue"
shape = "circle"

It could also reference a user-provided local asset:

name = "database-reviewer"

[visual]
icon = "./assets/database-reviewer.svg"
color = "violet"
shape = "diamond"

Codex could support three icon sources:

1. Built-in icons, using stable names such as compass, code, shield, database, or activity.
2. Namespaced icons from supported open-source packs, such as lucide:compass.
3. Safe local SVG or PNG files stored next to the agent profile or inside an agent/plugin package.

Colors could support either named theme tokens or explicit values:

[visual]
icon = "phosphor:magnifying-glass"
color = "cyan"
shape = "circle"

[visual]
icon = "./assets/security-audit.png"
color = "#8b5cf6"
shape = "hexagon"

Shapes should be optional backgrounds or frames rather than replacements for custom icons. A small standard set would be sufficient:

circle
rounded-square
square
diamond
hexagon
ring

A profile could define its default visual identity, while an individual spawn could optionally override it for a specific workstream.

Suggested precedence:

per-spawn visual override
> custom-agent profile
> built-in role default
> generic Codex subagent icon

For example, all Explorer agents could inherit a blue compass, while one security-focused exploration task temporarily uses a shield icon and violet hexagon.

The resolved visual identity should be stored with the child thread and remain stable across:

• subagent chips and cards;
• the Subagents panel;
• notifications;
• completed tasks;
• App restart;
• task resume and history replay.

Runtime status should remain separate from visual identity. A blue Explorer should keep its identity when it becomes blocked or fails; status can be shown using a border, badge, symbol, or text label.

Custom asset handling

Custom icons should remain local by default. Codex should not silently upload or fetch them from the network.

SVG files should be sanitized and prevented from executing scripts, embedding HTML, or loading remote resources. Invalid or missing files should fall back to the configured role icon without preventing the subagent from running.

When an icon is included in a shared agent or plugin package, the package should be able to preserve optional source, license, and attribution metadata.

Color should not be the only identifier. The icon, shape, display name, role label, tooltip, and accessible name should remain available.

Additional information

This complements #26112: caller-defined display names provide semantic text labels, while custom icons provide fast visual recognition in multi-agent workflows.

A possible default theme could still provide familiar starting points:

• Explorer: compass or search icon
• Worker: code or tools icon
• Reviewer: shield or scale icon
• Monitor: pulse or clock icon

These should be defaults only. Users should remain free to assign their own icons, colors, and shapes.