Agent Identity

Agents give your project directories a first-class identity in DorkOS. Instead of seeing /Users/me/projects/api everywhere, you see a named agent with a color dot and emoji. Agent identity works independently of Mesh — no feature flags required.

What You Get

When a directory has an agent registered:

• Sidebar shows the agent name, color dot, emoji, and description instead of a raw path
• Tab title displays the agent's emoji and name
• Favicon reflects the agent's color
• Directory picker recents show agent names for registered directories
• Task schedules display agent identity instead of paths
• Claude sessions receive agent identity context in the system prompt

Unregistered directories work exactly as before with zero changes.

Creating an Agent

Manual creation

You can also create the file directly:

{
  "id": "01HXYZ...",
  "name": "backend-bot",
  "description": "REST API and database agent",
  "runtime": "claude-code",
  "capabilities": ["api-design", "database"],
  "behavior": { "responseMode": "always" },
  "budget": { "maxHopsPerMessage": 5, "maxCallsPerHour": 100 },
  "registeredAt": "2026-02-26T00:00:00.000Z",
  "registeredBy": "manual"
}

Agent Settings Dialog

Click the agent name or gear icon in the sidebar to open the settings dialog. It has four tabs:

Identity

Configure the agent's visual identity:

• Name and Description — displayed in the sidebar and directory picker
• Color — pick from a palette or enter a hex code; clears to a deterministic default
• Emoji — pick from a curated grid; clears to a deterministic default
• Runtime — claude-code, cursor, codex, or other

Persona

Configure how the agent shapes Claude's behavior. See the Persona Injection guide for details.

Capabilities

Per-agent tool group toggles and Mesh metadata:

• Tool Groups — enable or disable MCP tool domains per agent (Relay tools, Mesh tools, Adapter tools, Tasks tools). Each toggle has three states: inherited (follows global config), enabled, or disabled. Changes take effect on the next session.
• Capabilities — tag-style chips used by Mesh for discovery and routing (e.g., api-design, frontend)
• Namespace — subject namespace for Relay routing
• Response Mode and Budget — behavioral constraints

Connections

A read-only view linking to other subsystems:

• Task schedules targeting this agent's directory
• Relay endpoints registered for this agent
• Mesh health status and heartbeat info

Each section hides when its subsystem is disabled.

Visual Identity

Every agent gets a deterministic color and emoji derived from its ID. You can override either in the Identity tab. The priority is:

1. User-set override (stored in .dork/agent.json as color/icon)
2. Deterministic hash from the agent's ID (stable across directory renames)
3. For unregistered directories: deterministic hash from the path

API

Agent identity is available via REST endpoints at /api/agents/:

These endpoints are always available — no feature flag needed. All paths are boundary-validated.

MCP Tool

Claude sessions can query an agent's identity via the get_agent MCP tool, providing either an agent_id (ULID) or cwd (working directory path). This is always available, regardless of whether Mesh is configured.