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 Code chats: 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 chat. In a chat 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

• Chats: every chat this agent has had, newest first, with a search box.
• Tasks: its scheduled runs, and what ran recently.
• Rooms: the channels and DMs it sits in.
• Activity: everything this agent did, or had done to it, newest first, from the record.

What it can do

• Skills: every skill this agent's folder holds — the ones you wrote, the ones a package brought, and the ones that only live in one tool's own folder — and, beside each, what every coding tool you run does with it: reads it, has a shared copy, is out of date, cannot see it, or needs a decision from you. When some of those files are out of date, a line at the top of the page says so and offers a Sync now button that writes them. If syncing would also remove anything — a link to a skill you deleted, the files a package left behind when you uninstalled it — the page names every one of those files, and why each is going, before you click, and lists them again afterwards. Below the list, a panel per tool listing every agent file it cannot see — skills, rules, commands and more, which is why that count is usually bigger than the number of skills. Where a tool cannot see one, the reason is the same sentence dorkos harness sync prints in your terminal, so the two can never tell you different things. There is a link to browse for more. If DorkOS finds files for a tool in the folder that it is not sharing to, the page says so and gives you the one command that turns it on. The row above says how many skills there are once you have opened the page — before that it says nothing, because counting them means reading your folder and it would rather not do that every time you open a profile.
• Permissions: what this agent may do on its own, what waits for your yes, and what it cannot do at all — opening and arranging rooms, installing a package, changing settings, and how often it stops to check with you while it edits files and runs commands. A row says "Same as everyone" until you set this agent differently. It changes only through this page or Settings; an edit to the agent's settings file made some other way still takes effect, and the history records it as changed outside DorkOS. See the Permissions guide.
• MCP servers: the MCP servers this agent runs. (MCP is the protocol that lets Claude call into DorkOS and other tools.) What the agent may actually do with them is decided on its Permissions page above, not here.
• Connections: what accounts this agent can use, and the chat apps (like Slack or Telegram) it can reach you and be reached on. This is the same access you manage on the Connections page, scoped to this one agent.
• 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.

Pausing an Agent

Pausing stops an agent everywhere at once, without removing it. Open the kebab menu (the ⋮ icon) on its profile and choose Pause everywhere. You can add a short reason.

When you pause an agent:

• anything it is doing right now stops, including scheduled tasks that are running and work it left running in the background, like a helper or a long command
• nothing starts it again until someone resumes it: your messages, its schedules, rooms, and messages from other agents or chat apps
• it stays on your team. You can still open its profile and read its chats

A paused agent shows paused on its profile and a pause mark next to its name in the sidebar. If you send it a message, the chat says it is paused and offers Resume right there.

Work it missed while paused is not run later. A scheduled task that came due shows as skipped, saying the agent was paused. A room says the agent is paused once, and again whenever someone asks it directly.

Anyone can pause any agent, including DorkBot, and so can your other agents. Anyone can resume it too, except the paused agent itself. Every pause and resume is kept in the record, with who did it and why, and so is each piece of work the pause held back.

From a terminal:

dorkos agent pause <agent-id> --reason "Posting the same thing over and over"
dorkos agent resume <agent-id>

dorkos agent list shows each agent's id. Agents use the pause_agent, resume_agent and list_paused_agents tools.

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 Code chats 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.