Creating Custom Agents

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/agentLoader.ts
• src/server.ts
• src/codexAgent.ts
• scripts/postinstall.js
• agents/general-purpose.md

SuperAgent allows developers to create and extend specialized agents through a decentralized library system. These agents are defined as Markdown files containing structured frontmatter and behavioral instructions. The system automatically synchronizes these definitions between the package installation and the user's local configuration, enabling the Model Context Protocol (MCP) server to discover and invoke them across different CLI environments like Codex, Gemini, and Continue.

The core purpose of custom agents is to provide specialized system prompts that define a specific behavioral mindset, focus areas, and operational boundaries for the underlying LLM-driven CLI tools. By adding new files to the designated agents directory, users can expand the server's capabilities without modifying the core TypeScript codebase.

Sources: README.md:1-12, src/agentLoader.ts:10-15, src/server.ts:48-65

Agent Architecture and Discovery

The SuperAgent system uses a file-based discovery mechanism to load agent definitions. When the server starts, it initializes the agentLoader to scan a specific local directory for Markdown files.

Storage and Synchronization

Agents are stored in the user's home directory to allow for local customization and persistence. The system performs a synchronization step during post-installation and server startup.

• Local Directory: ~/.superagent/agents
• Sync Logic: Files shipped with the NPM package are copied to the local directory only if they do not already exist. This ensures that user-modified or newly created custom agents are not overwritten by updates.

Sources: src/agentLoader.ts:13, scripts/postinstall.js:14-15, README.md:37-41

Discovery Flow

The following diagram illustrates how the server discovers and prepares agents for use by MCP clients.

The discovery process ensures that the list-agents tool always returns the most current list of available specialized personas.
Sources: src/agentLoader.ts:60-118, src/server.ts:251-255

Defining an Agent

A custom agent is defined by a Markdown file (.md) that follows a specific schema. The agentLoader uses a regular expression to split the file into two primary components: frontmatter and system prompt content.

File Schema

The file must start with a triple-dash (---) block containing YAML-like key-value pairs.

Field	Type	Required	Description
name	String	Yes	Unique identifier used in the agent parameter of tools.
description	String	Yes	Summary of the agent's purpose, shown in list-agents.
category	String	No	Functional grouping (e.g., 'engineering', 'analysis').

Sources: src/agentLoader.ts:16-21, src/agentLoader.ts:76-105

Implementation Example

The following snippet demonstrates the structure required for a custom agent file.

---
name: custom-expert
description: A specialized agent for custom tasks
category: specialized
---

# Custom Expert Prompt
You are an expert at...
## Behavioral Mindset
Focus on...

Sources: agents/general-purpose.md:1-10, src/agentLoader.ts:79-85

Data Flow and Invocation

When an MCP client invokes a tool (like codex or gemini) with an agent parameter, the server retrieves the corresponding system prompt and injects it into the CLI execution flow.

Prompt Construction Logic

The codexAgent.ts module handles the final prompt assembly before spawning the child process. It creates a hierarchy of instructions to ensure the agent follows both global system rules and the specific custom persona.

1. Meta Instruction: Internal system rules for MCP agents (conciseness, task focus).
2. Custom System Prompt: The body content of the .md file retrieved from the agent library.
3. User Request: The actual prompt provided by the client in the tool arguments.

Sources: src/codexAgent.ts:138-155, src/agentLoader.ts:125-132

Invocation Sequence

Technical Constraints and Guidelines

Developers creating custom agents should adhere to the following technical requirements discovered in the codebase:

• Path Resolution: Agent threads often reset the working directory between calls. Instructions should mandate the use of absolute paths for reliability.
• Response Format: Agents are expected to provide clean text. The server parses raw JSON events from the CLI and extracts assistant_message or agent_message types to build the final response.
• Naming Limits: Agent names should be between 1 and 64 characters to satisfy validation schemas.
• Tool Compatibility: The agent parameter is supported across codex, gemini, and continue tools.

Sources: agents/general-purpose.md:37-40, src/codexAgent.ts:63-95, src/types.ts:3

Summary

Creating custom agents in SuperAgent-MCP is a configuration-driven process that leverages Markdown files and frontmatter. By placing these files in ~/.superagent/agents, developers can define specialized personas that the server dynamically loads and presents as MCP tools. This architecture separates the behavioral logic of the agents from the technical implementation of the CLI runners, allowing for easy expansion and local customization of the agent library.