Custom Agents

Applies to: Dispatch v1.0.0, last updated 2026-04-05

You can add any agent .md file you have written to the Dispatch catalog. Importing registers the file’s path in ~/.dispatch/config.json so Dispatch tracks it alongside bundled agents.

Step 1: Write the agent file

Create a .md file with YAML frontmatter. The name field is required; all others are optional.

---
name: my-agent
description: What this agent does and when to use it.
model: sonnet
tools: Read, Grep, Glob, Edit, Write
---

Your system prompt here.

Save the file at an absolute path outside both the Dispatch repository’s agents/ directory and ~/.claude/agents/. A reasonable location is your home directory or a personal dotfiles repository.

For the full list of valid tool names and frontmatter fields, see Agent Catalog.

Step 2: Import via Settings

1. Open Settings and select the Agents tab.
2. Scroll to the Import Custom Agent section.
3. Enter the absolute path to your .md file and press Enter or click Import.
4. If validation passes, the agent appears in Available to Install with a custom label.
5. Click Install to copy it to ~/.claude/agents/.

Step 3: Verify

The agent appears in the Dispatch sidebar under Defined. It moves to Idle once it has run at least once, and to Live when it has an active session.

Format validation rules

The import endpoint applies these checks in order. The first failure returns an error and the file is not added.

Check	Error message
Path is provided and non-empty	path is required
Path is absolute	path must be absolute
Path ends with .md	path must end in .md
Path is not inside ~/.claude/agents/	path must not be inside the managed agents directory
Path is not inside the Dispatch agents/ directory	path must not be inside the bundled agents directory
File exists on disk	File does not exist
File is not a symbolic link	Symbolic links are not allowed
File is smaller than 100 KB	File must be smaller than 100KB
Frontmatter parses correctly and name is present	Agent file must have a name field in frontmatter
name matches ^[a-z0-9-]+$	Agent name must be lowercase letters, numbers, and hyphens only
name does not conflict with a bundled agent	Agent name "<name>" conflicts with a bundled agent

Once validated, the file path is appended to importedAgentPaths in ~/.dispatch/config.json. The file is not copied at import time. Dispatch reads it from the original path. If you move or delete the file after importing, the catalog entry shows [file not found] until you re-import with the new path.

Managing custom agents

Uninstalling

Uninstalling removes the agent file from ~/.claude/agents/. The agent is no longer available to Claude Code. The catalog entry remains and you can reinstall at any time.

Open Settings → Agents → find the agent under Installed Agents → click Uninstall.

Removing from the catalog

Removing a custom agent from the catalog deletes its entry from ~/.dispatch/config.json. The agent disappears from the Settings view. The source file on disk is not deleted.

Use Settings → Agents to remove custom agents. Bundled agents cannot be removed from the catalog. They are always present as long as the Dispatch repository is intact.

Archiving (disable without deleting)

To keep an agent’s file in ~/.claude/agents/ but hide it from active use, add enabled: false to its frontmatter:

---
name: my-agent
enabled: false
---

Dispatch displays the agent in the sidebar’s Archived section and excludes it from live/idle tracking. Remove enabled: false or set it to true to reactivate.