How to Configure Agent Color for Visual Distinction in the Claude CLI

TLDR: Add a color field to your agent's YAML front-matter in .claude/agents/*.md files to apply distinct ANSI color codes to each agent's CLI output, enabling instant visual tracking during multi-agent orchestration.

The Claude Code CLI provides a powerful multi-agent orchestration system where specialized sub-agents handle distinct tasks simultaneously. In the shanraisshan/claude-code-best-practice repository, developers configure agent color through simple front-matter metadata to create immediate visual distinction between different agents' console output, making it easy to identify which sub-agent is active during complex workflows.

How Agent Color Works in the Claude CLI

The agent color system operates through three distinct stages:

1. Front-matter definition – Inside each agent's markdown file, the color key is added to the YAML front-matter block at the top of the file.
2. CLI rendering – When the agent is invoked, the Claude runtime reads the front-matter, extracts the color value, and applies the corresponding ANSI color code to all logs emitted by that agent.
3. Visual distinction – In multi-agent orchestration scenarios, each participant's logs appear in a distinct hue, allowing users to quickly identify which step produced a given message without reading the agent name labels.

Although the field is fully functional, it is currently documented only in informal quick-start notes within the repository rather than in the official front-matter specification tables.

Configuring the Color Field

Front-Matter Syntax

Define the agent color by adding the color key to the YAML front-matter of any agent definition file located in .claude/agents/ or its subdirectories:

---
name: custom-insight-agent
description: Generates concise insights from raw data.
model: haiku
color: cyan        # ← this line sets the CLI colour

tools: fetch, summarize
---

The color field accepts simple string values such as green, blue, magenta, yellow, cyan, or teal. When the agent runs, all output prefixed with the agent identifier renders in the specified color:

[custom-insight-agent] > Starting analysis…   ← printed in cyan
[custom-insight-agent] > Insight: Data processing complete.

Modifying Existing Agents

To change an existing agent's color, edit the front-matter of the target file and update the value:

---
name: weather-agent
description: Orchestrates weather data collection.
model: sonnet
- color: green
+ color: teal
tools: fetch_weather, summarize
---

After saving the file, the Claude CLI immediately applies the new color to all subsequent output from that agent without requiring a restart of the CLI session.

Reference Implementation in the Repository

The shanraisshan/claude-code-best-practice repository demonstrates practical agent color assignments across multiple workflow agents. The following table maps specific agent files to their configured color values and exact line locations:

Agent File	Color Value	Line Reference
.claude/agents/weather-agent.md – the weather orchestrator agent	green	L6
.claude/agents/workflows/best-practice/workflow-concepts-agent.md – concepts-focused agent	green	L5
.claude/agents/workflows/best-practice/workflow-claude-subagents-agent.md – sub-agent manager	blue	L5
.claude/agents/workflows/best-practice/workflow-claude-settings-agent.md – settings manager	yellow	L5
.claude/agents/presentation-curator.md – presentation orchestrator	magenta	L6

This color distribution creates a clear visual hierarchy: orchestrators use warm colors (green, magenta) while specialized workflow managers use cooler tones (blue, yellow).

Documentation and Source References

The agent color functionality is referenced across several key documentation files in the repository:

• best-practice/claude-subagents.md (line 34) describes the field as "CLI output color for visual distinction", providing the primary informal documentation for the feature.
• CLAUDE.md (line 72) lists color among the supported front-matter options in the top-level reference guide.
• implementation/claude-subagents-implementation.md contains working examples showing color: green in production agent definitions.

These files confirm that while the feature is not yet formally documented in specification tables, it is fully implemented and stable in the current Claude CLI runtime.

Summary

• Agent color is configured via the color key in YAML front-matter of markdown files stored under .claude/agents/.
• The Claude CLI translates color names (e.g., blue, magenta, cyan) into ANSI color codes for terminal output.
• Visual distinction helps developers track multi-agent orchestration flows in real-time without parsing text labels.
• Color assignments are demonstrated in the shanraisshan/claude-code-best-practice repository across orchestrator and workflow-specific agent files.

Frequently Asked Questions

What color values does the Claude CLI support?

The Claude CLI accepts standard ANSI color names as strings, including green, blue, magenta, yellow, cyan, and teal. The runtime maps these strings to standard terminal color codes. Hex codes or RGB values are not currently supported; you must use named colors.

Is the color field required for all agents?

No, the color field is optional. If omitted, the Claude CLI renders agent output in the default terminal color. However, for multi-agent workflows, omitting the color eliminates the visual distinction benefits that make orchestration output readable.

Where is the agent color feature documented?

According to the source analysis, the color field is documented informally in best-practice/claude-subagents.md at line 34 and referenced in CLAUDE.md at line 72. It does not appear in the formal front-matter specification tables, though the implementation in the CLI is fully functional.

How does agent color behave in single-agent mode?

Even when running a single agent, the specified agent color still applies to all output. While the visual distinction benefit is most apparent in multi-agent scenarios, maintaining consistent colors across all agent files ensures predictable CLI output formatting regardless of execution mode.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}