Installation and Setup

Relevant source files

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

• README.md
• package.json
• scripts/postinstall.js
• src/server.ts
• src/agentLoader.ts
• src/codexAgent.ts

SuperAgent is a Model Context Protocol (MCP) server designed to orchestrate and fan out multiple CLI tasks in parallel using Codex, Gemini, and Continue agents. The installation process ensures that the server is correctly registered as an MCP tool and that specialized agent definitions are provisioned in the user's local environment.

The system relies on a combination of Node.js infrastructure, local file system management for agent prompts, and environment variable configuration for third-party CLI integration.

Sources: README.md:3-8, package.json:2-10

Prerequisites and Requirements

Before installing SuperAgent, the environment must meet specific technical requirements to ensure compatibility with the MCP SDK and the underlying agent runners.

Requirement	Specification	Source
Node.js Runtime	Version 18 or newer	README.md:73
Package Manager	npm (tested with standard npm install)	README.md:14
Operating System	Cross-platform (uses homedir() for pathing)	src/agentLoader.ts:10
External Tooling	Codex, Gemini, or Continue CLIs installed	README.md:5-7

Core Installation Process

Installation is primarily handled through the Node Package Manager (npm). The package is distributed as a module with a defined entry point for the MCP server.

npm install @superclaude-org/superagent

Sources: README.md:14, package.json:2-10

Post-Installation Hook

Upon installation, a postinstall script is automatically executed. This script is critical for seeding the local environment with necessary agent definition files.

1. Directory Creation: The script ensures the existence of ~/.superagent/agents.
2. File Synchronization: It copies bundled Markdown agent definitions from the package directory to the user's home directory.
3. Preservation: It explicitly checks for existing files to avoid overwriting user-customized agent prompts.

Sources: scripts/postinstall.js:14-48, README.md:16-18

Lifecycle of the Installation Flow

The following diagram illustrates the automated setup performed by the package during the postinstall phase.

This diagram shows how the system ensures agent availability while protecting local modifications.
Sources: scripts/postinstall.js:14-48

Configuration and Environment

SuperAgent requires specific environment variables and directory structures to function, particularly when integrating with complex CLI tools like Continue.

External Tool Configuration

Specific tools wrapped by SuperAgent require additional environment setup:

• Continue CLI: Requires the CONTINUE_CONFIG_PATH variable to point to the config.yaml file. This is often configured in the env section of the MCP client.
• Codex CLI: Executed with --dangerously-bypass-approvals-and-sandbox to allow the MCP server to perform system actions without interactive prompts.

Sources: README.md:65-71, src/codexAgent.ts:46

Agent Library Structure

Agents are stored as Markdown files with frontmatter. The agentLoader.ts module manages these at runtime.

Component	Path / Detail	Purpose
Agents Directory	~/.superagent/agents	Local storage for editable agent definitions.
Agent Format	Markdown + Frontmatter	Defines agent name, description, and systemPrompt.
Loader Logic	ensureAgentsDirectory()	Verifies and repairs the agent directory on server start.

Sources: src/agentLoader.ts:10-15, src/agentLoader.ts:65-98, README.md:61-63

Server Initialization

Once installed, the server is started via the bin entry point defined in package.json.

The sequence diagram demonstrates the initialization sequence where the server secures its environment before accepting connections.
Sources: src/server.ts:251-262, src/agentLoader.ts:56-62

Development Setup

For contributors or users wishing to run the server from source, the project provides specific scripts for building and execution.

1. Build: npm run build compiles TypeScript files into the dist/ directory.
2. Execution: npm start runs the compiled JavaScript using Node.
3. Hot-Reload/Dev: npm run dev uses ts-node to run the server directly from TypeScript source.

Sources: package.json:11-16, README.md:73-77

Conclusion

Installation and setup of SuperAgent-MCP is a streamlined process that automates the provisioning of specialized AI agents. By utilizing a post-install hook to manage local Markdown prompts and providing a unified entry point for multiple CLI tools, the system ensures that it is ready for immediate use upon installation while maintaining extensibility for local developer workflows.