Apollo Agent

   █████╗ ██████╗  ██████╗ ██╗     ██╗      ██████╗
  ██╔══██╗██╔══██╗██╔═══██╗██║     ██║     ██╔═══██╗
  ███████║██████╔╝██║   ██║██║     ██║     ██║   ██║
  ██╔══██║██╔═══╝ ██║   ██║██║     ██║     ██║   ██║   
  ██║  ██║██║     ╚██████╔╝███████╗███████╗╚██████╔╝
  ╚═╝  ╚═╝╚═╝      ╚═════╝ ╚══════╝╚══════╝ ╚═════╝

AI-powered coding agent with semantic code understanding and structured reasoning

Apollo Agent integrates cutting-edge MCP (Model Context Protocol) servers with OpenRouter LLMs to provide intelligent, context-aware assistance for software development tasks. It combines semantic code analysis (Serena), structured problem-solving (Sequential Thinking), and powerful language models to understand and manipulate codebases at a deep level.

🎯 Features

🔍 Semantic Code Analysis - Understands code structure, symbols, and relationships via Serena MCP
🧠 Structured Reasoning - Plans and executes multi-step tasks systematically
📚 Knowledge Base - Maintains context and learnings across sessions
🔧 Terminal Integration - Execute commands with smart sudo handling
📊 Symbol Indexing - Fast code navigation and search
🎨 Rich CLI Interface - Beautiful, informative terminal output

🚀 Quick Start

Prerequisites

Required:

Node.js ≥18.0.0 (install)
uv - Python package manager (install)
Linux or macOS (primary development platform)

Optional:

OpenRouter API key (get one)

Installation

# Clone the repository
git clone https://github.com/AlexandrosLiaskos/apollo-agent.git
cd apollo-agent

# Install dependencies
npm install

# Configure environment
cp .env.example .env
nano .env  # Add your OPENROUTER_API_KEY

# Start Apollo
npm start

First Run

On first startup, Apollo will:

Initialize Serena MCP server (via uvx)
Initialize Sequential Thinking MCP server
Connect to OpenRouter
Create a terminal session
Load available tools (30+ from MCP servers)

   █████╗ ██████╗  ██████╗ ██╗     ██╗      ██████╗
  ██╔══██╗██╔══██╗██╔═══██╗██║     ██║     ██╔═══██╗
  ███████║██████╔╝██║   ██║██║     ██║     ██║   ██║
  ██╔══██║██╔═══╝ ██║   ██║██║     ██║     ██║   ██║
  ██║  ██║██║     ╚██████╔╝███████╗███████╗╚██████╔╝
  ╚═╝  ╚═╝╚═╝      ╚═════╝ ╚══════╝╚══════╝ ╚═════╝

  AI Agent with MCP Integration

✔ OpenRouter initialized (model: anthropic/claude-sonnet-4)
✔ Connected to all MCP servers
✔ Loaded 30 tools from MCP servers

? 🚀 Task (or "exit" to quit):

📖 Usage

Interactive Mode

Apollo provides an interactive CLI where you can:

Give tasks:

? 🚀 Task: Refactor the UserService class to use async/await

Use commands:

status          - Show agent status
tasks           - View current task list
knowledge       - List knowledge entries
symbols         - Show symbol index stats
search <name>   - Search for symbols
help            - Show all commands
exit            - Quit Apollo

Example Tasks

Code Analysis:

? Task: Find all uses of the calculateTotal function
? Task: Show me the structure of the UserController class
? Task: List all API endpoints in this project

Code Modification:

? Task: Add error handling to the login method
? Task: Convert all var declarations to const/let
? Task: Add TypeScript types to user.js

System Operations:

? Task: Install and configure the axios package
? Task: Update all dependencies to latest versions
? Task: Set up ESLint with standard config

🛠️ Configuration

Environment Variables

Edit .env:

# OpenRouter Configuration (REQUIRED)
OPENROUTER_API_KEY=your_api_key_here

# Model Selection (optional)
OPENROUTER_MODEL=anthropic/claude-sonnet-4

# Sudo Configuration (see below)
SUDO_MODE=auto  # auto | nopasswd | interactive | password

Sudo Commands

Apollo can execute sudo commands. Configure via SUDO_MODE:

Option 1: Auto (Default)

SUDO_MODE=auto

Tries passwordless sudo first, falls back to interactive if needed.

Option 2: Passwordless Sudo (Recommended)

# Configure system for passwordless package management
sudo visudo

# Add (replace 'user' with your username):
user ALL=(ALL) NOPASSWD: /usr/bin/pacman
user ALL=(ALL) NOPASSWD: /usr/bin/apt-get
user ALL=(ALL) NOPASSWD: /usr/bin/dnf

# Then in .env:
SUDO_MODE=nopasswd

Option 3: Interactive

SUDO_MODE=interactive

Apollo pauses and prompts for password when needed.

Option 4: Password in Env (⚠️ Less Secure)

SUDO_MODE=password
SUDO_PASSWORD=your_password

Only for personal development with disk encryption.

📚 Architecture

Core Components

Agent Core (src/agent/apollo-agent.js)

Main agent orchestration
Task planning and execution
Tool coordination

MCP Integration (src/mcp/serena-client.js)

Connects to Serena (semantic code analysis)
Connects to Sequential Thinking (structured reasoning)
Tool registry and execution

LLM Provider (src/providers/openrouter.js)

OpenRouter API integration
Streaming support
Multiple model support

Terminal Tool (src/tools/terminal-tool.js)

Command execution
Sudo handling
Session management

Knowledge Base (src/agent/knowledge-base.js)

Persistent memory storage
Context accumulation
Cross-session learning

Symbol Index (src/agent/symbol-index.js)

Fast code symbol search
File indexing
Symbol relationships

MCP Servers

Serena MCP (oraios/serena)

Semantic code operations
Symbol navigation
Intelligent code editing
Memory management

Sequential Thinking MCP (@modelcontextprotocol/server-sequential-thinking)

Step-by-step reasoning
Plan validation
Structured problem solving

🔧 Development

Project Structure

apollo-agent/
├── src/
│   ├── index.js              # Entry point
│   ├── agent/
│   │   ├── apollo-agent.js   # Main agent
│   │   ├── task-manager.js   # Task tracking
│   │   ├── knowledge-base.js # Memory system
│   │   └── symbol-index.js   # Code indexing
│   ├── mcp/
│   │   └── serena-client.js  # MCP client manager
│   ├── providers/
│   │   └── openrouter.js     # LLM provider
│   ├── session/
│   │   └── session-manager.js # Session persistence
│   ├── tools/
│   │   ├── api-tools.js      # Tool registry
│   │   └── terminal-tool.js  # Command execution
│   └── ui/
│       └── rich-output.js    # CLI interface
├── package.json
├── .env.example
└── README.md

Running in Development

# Watch mode (auto-restart on changes)
npm run dev

# Standard mode
npm start

Adding Custom Tools

Implement tool in src/tools/
Register in ToolRegistry (src/tools/api-tools.js)
Add to agent tool list

Extending LLM Providers

Create provider class in src/providers/
Implement chat() and chatStream() methods
Update agent initialization

🐛 Troubleshooting

"Serena MCP failed to connect"

Cause: uv not installed or not in PATH

Fix:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify
uv --version

"OpenRouter API error"

Cause: Invalid or missing API key

Fix:

# Get API key from https://openrouter.ai/keys
# Add to .env:
echo "OPENROUTER_API_KEY=sk-or-..." >> .env

"Command not found: apollo"

Cause: Not installed globally

Fix:

# Option 1: Use npm start
npm start

# Option 2: Install globally
npm install -g .
apollo

"sudo: a password is required"

Cause: Passwordless sudo not configured

Fix:

# Configure in .env:
SUDO_MODE=interactive

# Or setup passwordless sudo (see Configuration section)

📊 System Requirements

Component	Minimum	Recommended
OS	Linux, macOS	Arch Linux, Ubuntu 22.04+
Node.js	18.0.0	20.0.0+
RAM	2GB	4GB+
Storage	500MB	1GB+
Network	Required	High-speed

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Serena MCP - Semantic code operations
Model Context Protocol - MCP specification
OpenRouter - LLM API aggregation
Anthropic Claude - Default language model

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions

Built with ❤️ by Alexandros Liaskos

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
src		src
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
FEATURES.md		FEATURES.md
LICENSE		LICENSE
README.md		README.md
SYMBOL-INDEX-QUICKSTART.md		SYMBOL-INDEX-QUICKSTART.md
SYMBOL-INDEX.md		SYMBOL-INDEX.md
install.sh		install.sh
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Apollo Agent

🎯 Features

🚀 Quick Start

Prerequisites

Installation

First Run

📖 Usage

Interactive Mode

Example Tasks

🛠️ Configuration

Environment Variables

Sudo Commands

📚 Architecture

Core Components

MCP Servers

🔧 Development

Project Structure

Running in Development

Adding Custom Tools

Extending LLM Providers

🐛 Troubleshooting

"Serena MCP failed to connect"

"OpenRouter API error"

"Command not found: apollo"

"sudo: a password is required"

📊 System Requirements

🤝 Contributing

📄 License

🙏 Acknowledgments

📞 Support

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Apollo Agent

🎯 Features

🚀 Quick Start

Prerequisites

Installation

First Run

📖 Usage

Interactive Mode

Example Tasks

🛠️ Configuration

Environment Variables

Sudo Commands

📚 Architecture

Core Components

MCP Servers

🔧 Development

Project Structure

Running in Development

Adding Custom Tools

Extending LLM Providers

🐛 Troubleshooting

"Serena MCP failed to connect"

"OpenRouter API error"

"Command not found: apollo"

"sudo: a password is required"

📊 System Requirements

🤝 Contributing

📄 License

🙏 Acknowledgments

📞 Support

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages