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

Every agent has one profile, and it is the only place you go. Open it from an agent's face anywhere in the app, from View profile in its menu, or with Cmd+Shift+A while you are in its session. On a session it docks into the right panel; everywhere else it slides in from the side.

The top of the profile is a portrait: the face, the name, the @handle, one sentence saying what the agent is doing, and who it belongs to. Tap the face to change its color and emoji.

Under that is a list of rows. A row with a › opens a full page; a row with a ▾ opens a small picker on the spot. Here is what each one holds.

The agent itself

• About: its name and description, plus the capabilities you have tagged it with.
• Runs on: which runtime it uses, which model, and how hard that model thinks. All three in one picker. If you've registered more than one Claude account, a fourth row lets you send this agent's work to one of them, so its runs bill to that account instead of your default. See Choose an Account.
• Personality: eight ready-made characters and six sliders behind them. See the Persona Injection guide.
• Folder: copies the agent's directory to your clipboard.

Its work

• Sessions: every chat this agent has had, newest first, with a search box.
• Tasks: its scheduled runs, and what ran recently.
• Rooms: the channels and conversations it sits in.

What it can do

• Skills: marketplace skill packs installed for this agent's directory, with a link to browse more.
• Tools & MCP: two different settings live here. The four tool groups — Tasks, Relay, Mesh, and Adapter — choose what this agent is told about. (These are MCP tools, the protocol that lets Claude call into DorkOS.) Each has three states: inherited (follows global config), on, or off. Turning one off leaves it out of the agent's instructions, so the agent stops reaching for those tools — but it is guidance, not a lock: an agent that asks for one anyway still gets it. Manage rooms is the exception, and it is a real lock. Turn it on and this agent can open channels and direct messages, add and remove members, rename a channel, and leave a channel; leave it off and DorkOS refuses those calls and tells the agent to ask you. It is off until you turn it on, only you can change it, and the agent cannot turn it on for itself. Even with it on, an agent can never remove you from a room, and any room holding two agents holds you too. Changes take effect on the next session, and one agent's settings never affect another agent. This page also lists the MCP servers this agent runs.
• Connections: connect chat apps (like Slack or Telegram) to this agent so it can reach you and you can reach it. This runs on 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 connection as an early feature and test it before relying on it.
• Instructions and Boundaries: the two files you write an agent's behavior into, each with the whole page to itself. Both pages end with a preview showing how your agent will be told who it is, how it should sound, and what it must not do — assembled the way it will get them, so you can read it before you save. See the Persona Injection guide.

Removing an Agent

Open the kebab menu (the ⋮ icon) at the top of the agent's profile 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 new agent is given a color and an emoji face the moment it's created, picked from a small curated set. The pick is worked out from the agent's own ID, so it's the same face on every screen and it never changes on its own. You can swap either one by tapping the face at the top of the agent's profile.

What you see is the first of these that exists:

1. The face you chose, or the one a marketplace package shipped with (stored in .dork/agent.json as color/icon)
2. The face DorkOS picks for that agent's ID — what a new agent is created wearing, and what an older one falls back to
3. For a directory that isn't a registered agent: a color worked out 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.