LEGIONHERCULES¶

Autonomous CLI Framework with Parallel Agent Execution

Developed by Death Legion Team Coders Demo X HEXA

🚀 What is LEGIONHERCULES?¶

LEGIONHERCULES is a powerful, open-source CLI framework that brings autonomous AI agents to your terminal. Built for developers who want the power of Claude Code or OpenCode, but completely free and running locally on their own hardware.

Key Features¶

🤖 Autonomous Agents - AI agents that can reason, plan, and execute tasks
⚡ Parallel Execution - Run multiple agents simultaneously for faster results
🔧 Built-in Tools - File operations, bash commands, web search out of the box
🆓 Completely Free - Uses Ollama for local LLM inference - no API keys needed
💻 Local-First - All processing happens on your machine
🎨 Rich Terminal UI - Beautiful, interactive CLI experience

📦 Installation¶

Prerequisites¶

Python 3.9 or higher
Ollama installed and running

Install from PyPI¶

pip install legionhercules

Install from Source¶

git clone https://github.com/deathlegion/legionhercules.git
cd legionhercules
pip install -e ".[dev]"

🚀 Quick Start¶

1. Start Ollama¶

Make sure Ollama is running:

ollama serve

2. Pull a Model¶

# Pull the recommended model
ollama pull llama3.2

# Or use legionhercules to pull
legionhercules models --pull llama3.2

3. Start Chatting¶

# Interactive mode
legionhercules chat

# Or send a single message
legionhercules chat "Hello, what can you do?"

📖 Usage¶

Interactive Chat¶

legionhercules chat

This starts an interactive session where you can chat with the AI agent.

Available Commands: - /quit or /exit - Exit the session - /clear - Clear conversation history - /tools - Toggle tool usage - /help - Show help

Using Different Models¶

legionhercules chat --model codellama
legionhercules chat --model mistral
legionhercules chat --model llama3.1:8b

Using Different Agents¶

# Use the code-focused agent
legionhercules chat --agent coder

# Use the research agent
legionhercules chat --agent researcher

Managing Models¶

# List available models
legionhercules models --list

# Pull a new model
legionhercules models --pull llama3.1

Managing Tools¶

# List available tools
legionhercules tools --list

🔧 Configuration¶

Initialize Configuration¶

legionhercules config --init

This creates a configuration file at ~/.legionhercules/config.yaml.

Configuration File Structure¶

version: "0.1.0"

llm:
  provider: ollama
  model: llama3.2
  base_url: http://localhost:11434
  temperature: 0.7
  max_tokens: 4096

orchestrator:
  max_concurrent_tasks: 5
  task_timeout: 300.0
  retry_attempts: 3
  enable_parallel: true

agents:
  - name: default
    description: Default general-purpose agent
    system_prompt: You are a helpful AI assistant.
    tools:
      - file_read
      - file_write
      - file_edit
      - bash
      - web_search

  - name: coder
    description: Code-focused agent
    system_prompt: You are an expert programmer...
    tools:
      - file_read
      - file_write
      - file_edit
      - bash

🛠️ Available Tools¶

LEGIONHERCULES comes with powerful built-in tools:

File Operations¶

file_read - Read file contents with optional offset and limit
file_write - Write or append to files
file_edit - Search and replace text in files

System Operations¶

bash - Execute bash commands with safety checks

Web Operations¶

web_search - Search the web using DuckDuckGo

🏗️ Architecture¶

LEGIONHERCULES is built with a modular architecture:

┌─────────────────────────────────────────┐
│              CLI Layer                │
│         (Rich Terminal UI)              │
├─────────────────────────────────────────┤
│           Orchestrator                  │
│    (Parallel Task Management)           │
├─────────────────────────────────────────┤
│            Agents                       │
│  (Reasoning + Tool Use + LLM)           │
├─────────────────────────────────────────┤
│            Tools                        │
│  (File, Bash, Web Search)               │
├─────────────────────────────────────────┤
│         LLM Provider                    │
│       (Ollama Integration)              │
└─────────────────────────────────────────┘

🤝 Contributing¶

We welcome contributions! Please see our Contributing Guide for details.

Development Setup¶

git clone https://github.com/deathlegion/legionhercules.git
cd legionhercules

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

📄 License¶

LEGIONHERCULES is licensed under the MIT License. See LICENSE for details.

🙏 Acknowledgments¶

Ollama - For making local LLMs accessible
Rich - For the beautiful terminal UI
Typer - For the CLI framework

Developed with ❤️ by Death Legion Team Coders Demo X HEXA