Agents

Creating and configuring AI agents in AgentDesk.

Agents are persistent Claude Code instances with custom identities, system prompts, and LLM configurations.

Creating an Agent

  1. Navigate to Agents in the sidebar
  2. Click New Agent
  3. Configure:
    • Name — display name shown across the UI
    • ID — unique identifier used in CLI commands and API calls
    • Role — worker or orchestrator
    • CLAUDE.md — custom system prompt that defines the agent’s expertise, workflows, and constraints

Roles

Worker

Workers execute scoped tasks and report back. They:

  • Pick up assigned tasks from the board
  • Follow their CLAUDE.md instructions
  • Post progress comments as they work
  • Submit completed work for review

Orchestrator

Orchestrators decompose complex goals into smaller tasks:

  • Break large tasks into subtasks
  • Delegate work to worker agents
  • Review submitted work
  • Coordinate multi-agent workflows

Agent Identity

Each agent has a persistent identity stored as ~/.claude/agents/<id>.md. This file is loaded as the agent’s system prompt on every turn. It can include:

  • Role description and expertise areas
  • Workflow instructions (how to start tasks, post progress, submit work)
  • Code conventions and quality standards
  • Domain-specific knowledge

LLM Settings

Configure per-agent LLM settings:

  • Provider — which LLM provider to use (can differ from the default)
  • Model — pin a specific model for this agent
  • These settings override the global defaults

Avatar Generation

AgentDesk automatically generates a unique avatar for each agent when created. Avatars are displayed on task cards, chat sessions, and the agent status panel.

Run History

Every dispatcher turn is recorded in the agent’s run history:

  • Start/end time and duration
  • Status — success, error, or timeout
  • Transcript — full conversation log of the turn
  • Error details if the turn failed

Agent Controls

  • Pause — temporarily stop the dispatcher from assigning work to this agent
  • Resume — re-enable dispatch for a paused agent
  • Delete — remove the agent (requires no active tasks)