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

> Customize agent color in the Claude CLI for instant visual distinction. Add a color field to agent YAML front-matter to easily track multi-agent orchestration output.

- Repository: [Shayan Rais/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice)
- Tags: how-to-guide
- Published: 2026-03-12

---

**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:

```yaml
---
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:

```text
[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:

```diff
---
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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/agents/weather-agent.md) – the weather orchestrator agent | `green` | [L6](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/agents/weather-agent.md#L6) |
| [`.claude/agents/workflows/best-practice/workflow-concepts-agent.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/agents/workflows/best-practice/workflow-concepts-agent.md) – concepts-focused agent | `green` | [L5](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/agents/workflows/best-practice/workflow-concepts-agent.md#L5) |
| [`.claude/agents/workflows/best-practice/workflow-claude-subagents-agent.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/agents/workflows/best-practice/workflow-claude-subagents-agent.md) – sub-agent manager | `blue` | [L5](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/agents/workflows/best-practice/workflow-claude-subagents-agent.md#L5) |
| [`.claude/agents/workflows/best-practice/workflow-claude-settings-agent.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/agents/workflows/best-practice/workflow-claude-settings-agent.md) – settings manager | `yellow` | [L5](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/agents/workflows/best-practice/workflow-claude-settings-agent.md#L5) |
| [`.claude/agents/presentation-curator.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/agents/presentation-curator.md) – presentation orchestrator | `magenta` | [L6](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/agents/presentation-curator.md#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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/CLAUDE.md)** (line 72) lists `color` among the supported front-matter options in the top-level reference guide.
- **[`implementation/claude-subagents-implementation.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/best-practice/claude-subagents.md) at line 34 and referenced in [`CLAUDE.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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.