apollo-agent

Apollo Agent is an MCP-enabled AI assistant designed to work inside codebases and development environments. It integrates Serena for semantic code analysis, a Sequential Thinking MCP for structured planning, and a suite of MCP-powered tools accessed through a rich CLI. Once started, Apollo loads 30+ tools from various MCP servers and connects to OpenRouter to leverage LLM capabilities. You can interact with the agent to perform tasks such as code analysis, refactoring, searching for symbols, executing terminal commands with smart sudo handling, and managing a persistent knowledge base across sessions. The agent offers an interactive prompt where you can issue tasks, inspect status, review knowledge entries, and run code-oriented commands or modifications through the integrated tooling.

To use Apollo, ensure your environment is configured with the required API keys and prerequisites, then start the server. In interactive mode, you can request tasks like “Refactor the UserService to use async/await,” ask to list all API endpoints, or command the agent to install and configure dependencies. You can also access system operations such as installing packages, updating dependencies, or setting up ESLint via the provided commands and prompts. The agent’s tooling enables direct interaction with your codebase, symbol indexing for quick navigation, and memory-based context to maintain continuity across sessions.

Prerequisites:

• Node.js >= 18.x (install from https://nodejs.org)
• Linux or macOS (recommended for development)
• Optional: uv (Python package manager) for Serena/Serena MCP runtime

Installation steps:

1. Clone the repository

git clone https://github.com/AlexandrosLiaskos/apollo-agent.git
cd apollo-agent

2. Install dependencies

npm install

3. Configure environment Copy the example environment file and edit as needed

cp .env.example .env
# Edit .env with your values, e.g.:
# OPENROUTER_API_KEY=your_openrouter_api_key

4. Start the Apollo agent

npm start

5. (Optional) Run in development mode with watch

npm run dev

Notes:

• The agent relies on OpenRouter for LLM capabilities and uv for semantic analysis in the Serena MCP workflow. Ensure the uv tool is installed if you plan to use Serena MCP features locally.
• If you plan to run in a container or production-like environment, consider wrapping the start command in a process manager (e.g., pm2) and exposing appropriate environment variables.

Tips and common considerations:

• Environment variables: OPENROUTER_API_KEY is REQUIRED for LLM access. SUDO_MODE controls terminal command permissions; default is auto. Consider setting SUDO_MODE to nopasswd for passwordless operations in trusted environments.
• OpenRouter model: OPENROUTER_MODEL can be customized to a preferred model; Claude Sonnet 4 is used in examples.
• Serena MCP (semantic code analysis) and Sequential Thinking MCP (structured reasoning) are integral to analysis and task planning. Ensure uv is installed and accessible if Serena is used locally.
• If you encounter “OpenRouter API error” verify that OPENROUTER_API_KEY is valid and present in the environment or .env file.
• Common startup issue: if the agent cannot connect to MCP servers, verify network access and that dependencies are installed (npm install), then re-run npm start.