# Phase 4: Agent Identity & Coloring — Specification

**Priority:** P3 · **Effort:** 0.5 days · **Dependencies:** None  
**Reference:** `claude-code-main/src/tools/AgentTool/agentColorManager.ts`

---

## 1. Problem Statement

In Claude Code, each agent gets an assigned color for the status line and UI elements. This provides quick visual differentiation when multiple agents are running in parallel. Agents can optionally specify a preferred color in frontmatter.

pi-subagents has a monochrome agent widget. When multiple agents run in parallel, there's no visual way to distinguish them at a glance.

---

## 2. Design

### 2.1. Color Palette

A set of 8 distinguishable colors (terminal-safe ANSI):

```typescript
const AGENT_COLORS = [
  "blue",      // Default
  "green",
  "yellow",
  "magenta",
  "cyan",
  "red",
  "white",
  "dim",
] as const;
```

### 2.2. Assignment Strategy

1. If the agent definition specifies a `color` in frontmatter, use that
2. Otherwise, assign the next color from the palette in round-robin order
3. Colors are assigned by agent ID (deterministic — same ID, same color across sessions)

### 2.3. Display

The color appears in:
- Agent widget: colored status indicator (e.g., `●` in agent color)
- Agent details: `AgentDetails.color` field
- Completion notifications: colored icon

### 2.4. Frontmatter

```yaml
---
name: my-agent
description: My custom agent
color: green
---
```

Supported color names: `"blue"`, `"green"`, `"yellow"`, `"magenta"`, `"cyan"`, `"red"`, `"white"`, `"dim"`.

---

## 3. API Changes

### 3.1. `AgentConfig` — New Field

```typescript
export interface AgentConfig {
  // ...existing fields...
  /** Optional color for UI differentiation. One of: blue, green, yellow, magenta, cyan, red, white, dim. */
  color?: AgentColorName;
}

export type AgentColorName = "blue" | "green" | "yellow" | "magenta" | "cyan" | "red" | "white" | "dim";
```

### 3.2. `AgentDetails` — New Field

```typescript
export interface AgentDetails {
  // ...existing fields...
  /** Optional color assigned to this agent. */
  color?: AgentColorName;
}
```

### 3.3. `AgentActivity` — Track Color

```typescript
// In the activity tracker or widget state
color?: AgentColorName;
```

---

## 4. Integration Points

| File | Change |
|---|---|
| `src/types.ts` | Add `AgentColorName` type, `color` field to `AgentConfig` |
| `src/ui/agent-widget.ts` | Accept and render color; update `AgentDetails` and `UICtx` |
| `src/index.ts` | Pass color through AgentDetails in tool rendering |
| `src/custom-agents.ts` | Parse `color` from frontmatter |
| `src/agent-types.ts` | `getAgentConfig()` returns color |

---

## 5. Testing Plan

| Test | What it verifies |
|---|---|
| Color assignment deterministic | Same agent ID gets same color |
| Frontmatter color parsed | `.pi/agents/test.md` with `color: green` reads correctly |
| Invalid color falls back | Unknown color name falls back to default |
| Color in AgentDetails | `AgentDetails.color` is populated |
| Widget renders color | Widget uses theme.fg() with the color name |