# Agent Identity
Source: https://dorkos.ai/docs/guides/agents

Give your projects a name, color, and emoji so you think in agents, not file paths





# Agent Identity [#agent-identity]

<ProductShot id="agents" alt="The DorkOS Agents page showing a fleet of named agents, each with its own color, emoji, and description" />

Instead of seeing `/Users/me/projects/api` everywhere, you can see a named agent with a color dot and an emoji. That's what an agent identity gives your project directory in DorkOS: a face, not just a path. It works on its own, with no setup required, and independently of [Mesh](/docs/guides/agent-discovery) (the system that helps agents discover and route to each other).

## What You Get [#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 [#creating-an-agent]

<Steps>
  <Step>
    ### Quick create from the sidebar [#quick-create-from-the-sidebar]

    Click the **+ Agent** button next to the directory path in the sidebar. This creates a `.dork/agent.json` file with sensible defaults: a name derived from the directory, plus a deterministic color and emoji.
  </Step>

  <Step>
    ### Customize in the Agent Hub [#customize-in-the-agent-hub]

    The Agent Hub panel opens automatically after creation. Edit the name, description, pick a color and emoji, then close the panel. Changes save automatically.
  </Step>
</Steps>

### Manual creation [#manual-creation]

You can also create the file directly. It's the source of truth (a database copy stays in sync automatically), so editing it by hand is safe:

```json title=".dork/agent.json"
{
  "id": "01HXYZ...",
  "name": "backend-bot",
  "description": "REST API and database agent",
  "runtime": "claude-code",
  "capabilities": ["api-design", "database"],
  "behavior": { "responseMode": "always" },
  "registeredAt": "2026-02-26T00:00:00.000Z",
  "registeredBy": "manual"
}
```

## Customizing Your Agent [#customizing-your-agent]

Click an agent in the sidebar to open the **Agent Hub** panel. The hero at the top has quick pickers for the avatar (color and emoji) and personality; below it, three tabs cover everything else.

### Sessions [#sessions]

Scheduled tasks for this agent (if any), followed by its sessions, grouped by time.

### Config [#config]

Edit the agent's description, runtime, and tags, and manage two collapsible sections:

* **Channels**: connect chat apps (like Slack or Discord) to this agent through Relay, the message bus DorkOS uses to route agent traffic. Relay is shipped, but multi-agent coordination through it is still unverified end to end, so treat any channel connection as an early feature and test it before relying on it.
* **Advanced**: the agent's personality and any custom instruction files. See the [Persona Injection](/docs/guides/persona) guide for details.

### Toolkit [#toolkit]

Two sections here:

* **Tools**: turn MCP (the protocol that lets Claude call DorkOS tools) tool groups on or off per agent: Tasks, Relay, Mesh, and Adapter. Each toggle has three states: inherited (follows global config), enabled, or disabled. Changes take effect on the next session. Disabling a group for one agent doesn't affect any other agent.
* **Skill Packs**: marketplace skill packs installed for this agent's directory, with a link to browse more.

<Callout type="info">
  Mesh and Relay power discovery and cross-agent routing, but that coordination is still being
  hardened. Tool toggles and channel connections work today; treat multi-agent handoffs as an early
  capability, not a guarantee.
</Callout>

## Removing an Agent [#removing-an-agent]

Open the kebab menu (the &#x2A;*⋮** icon) in the Agent Hub panel for three options:

* **Block**: hides the agent from future directory scans. Its files stay untouched, and you can unblock it later.
* **Unregister**: removes the agent from your list without touching project files. Any scheduled tasks pause. DorkOS offers an undo right after, and re-scanning the directory brings the agent back.
* **Delete Agent & Data**: permanently erases the agent's personality, settings, and custom rules (you have to type its name to confirm). Your project files are never touched, but this one can't be undone.

System agents, like DorkBot, skip all three: they're managed automatically and can't be blocked, unregistered, or deleted.

## Visual Identity [#visual-identity]

Every agent gets a deterministic color and emoji derived from its ID, so even a brand-new, unnamed agent looks intentional rather than broken. You can override either in the Config tab. The priority is:

1. Your override, if you set one (stored in `.dork/agent.json` as `color`/`icon`)
2. A deterministic hash from the agent's ID (stable across directory renames)
3. For unregistered directories: a deterministic hash from the path

<Callout type="info">
  Clearing a color or emoji override reverts to the deterministic default. No visual identity is
  ever lost.
</Callout>

## Reference [#reference]

The rest of this page is for people writing code against DorkOS. If you're just using the UI, you can stop here.

### API [#api]

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

| Method | Endpoint                       | Purpose                                 |
| ------ | ------------------------------ | --------------------------------------- |
| GET    | `/api/agents/current?path=...` | Get agent for a directory               |
| POST   | `/api/agents`                  | Create a new agent                      |
| PATCH  | `/api/agents/current?path=...` | Update agent fields                     |
| POST   | `/api/agents/resolve`          | Batch resolve agents for multiple paths |

These endpoints are always available, no feature flag needed, and all paths are boundary-validated (checked against the folders DorkOS is allowed to touch). This is the core set; the server exposes a few more routes for advanced flows like scaffolding a new agent from a template.

### MCP Tool [#mcp-tool]

Claude sessions can query an agent's identity via the `get_agent` MCP tool, providing either an `agent_id` (a ULID, an ID that also records when it was created) or `cwd` (working directory path). This is always available, regardless of whether Mesh is configured.