Agent Identity

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 (the system that helps agents discover and route to each other).

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. It's the source of truth (a database copy stays in sync automatically), so editing it by hand is safe:

{
  "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

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

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

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 guide for details.

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.

Removing an Agent

Open the kebab menu (the ⋮ 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

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

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

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

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

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.