File System & Initialization
Relevant source files
The following files were used as context for generating this wiki page:
The SuperAgent MCP server relies on a structured initialization process to manage its library of specialized agents. This system bridges the gap between the static agent definitions shipped with the NPM package and a user-customizable local environment. The initialization logic ensures that the runtime has access to a persistent directory where agent prompts are stored, parsed, and made available to various CLI runners like Codex, Gemini, and Continue.
The primary goal of this subsystem is to provide a "seed-and-extend" model. Upon installation, the system provisions a local directory in the user's home folder, populating it with curated agent definitions while preserving any manual modifications made by the user. This architecture allows for tool discovery and dynamic prompt injection across multiple parallel execution threads.
Initialization Workflow
The initialization of SuperAgent occurs in two distinct phases: the installation phase (via a post-install script) and the server startup phase.
Installation & Provisioning
When the package is installed via NPM, a post-install hook triggers the creation of the local configuration environment. This process ensures that the user's home directory is prepared before the server ever runs.
The logic explicitly avoids overwriting existing files in the target directory to ensure that "user customizations" are not lost during package updates.
Sources: scripts/postinstall.js:15-51, README.md:23-25
Server Startup Sequence
When the SuperAgent MCP server starts, it performs a secondary check to ensure the file system is intact and loads the available agents into memory for tool definition.
- Signal Handling: The
processManageris initialized to handle graceful shutdowns. - Directory Verification:
ensureAgentsDirectory()is called to verify the home directory exists. - Agent Discovery: The server loads all
.mdfiles from the local directory to populate thelist-agentstool description. - Transport Connection: The
StdioServerTransportis established to communicate with the MCP client.
Sources: src/server.ts:248-258, src/agentLoader.ts:60-64
Agent File System Structure
SuperAgent uses a specific directory hierarchy to manage its assets. The system distinguishes between the "Package Directory" (read-only distribution) and the "User Directory" (read-write runtime).
Directory Locations
| Type | Path | Purpose |
|---|---|---|
| User Home | ~/.superagent/agents | Primary storage for active agent definitions. |
| Package Source | [dist]/agents/ | Source of seed files distributed with the NPM package. |
| Scripts | scripts/postinstall.js | Automation for directory provisioning. |
Sources: src/agentLoader.ts:13-33, scripts/postinstall.js:11-13
The Agent Definition Format
Agents are stored as Markdown files with YAML-style frontmatter. This format allows the file system to serve as a human-readable and machine-parsable database.
- Frontmatter: Contains metadata such as
name,description, andcategory. - Body: Contains the actual
systemPromptthat will be injected into the CLI agent.
Sources: src/agentLoader.ts:74-106, README.md:38-40
Agent Loading & Parsing Logic
The agentLoader.ts module is responsible for translating the file system state into data structures used by the MCP server.
Parsing Mechanism
The loader uses a regular expression to split the file content into metadata and the system prompt.
// Parsing logic overview
const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
// Extracted fields:
// name: used for tool invocation
// description: shown in list-agents
// systemPrompt: the markdown body
Sources: src/agentLoader.ts:76-100
Loading Sequence
The following sequence diagram illustrates how agents are retrieved from the file system and formatted for the MCP client.
Configuration & Environment
The initialization process respects specific environment variables and local configurations to determine behavior.
| Variable | Description | Source |
|---|---|---|
homedir() | Used to resolve the base path for ~/.superagent. | src/agentLoader.ts:13 |
CONTINUE_CONFIG_PATH | Required environment variable for the continue tool initialization. | README.md:46-50 |
import.meta.url | Used to locate the package's internal agents/ folder during npx or local execution. | src/agentLoader.ts:20-25 |
Summary
The File System and Initialization module provides the foundation for SuperAgent's extensibility. By provisioning a local ~/.superagent/agents directory during installation and verifying it at every startup, the system ensures that specialized agent prompts are both persistent and customizable. The use of Markdown with frontmatter allows for a simple yet powerful way to define agent behaviors that are dynamically loaded and exposed via MCP tools.
Sources: scripts/postinstall.js, src/agentLoader.ts, src/server.ts