🧙‍♂️ Feral Code Oracle

The most immersive multi-agent coding experience ever created!

A cutting-edge, game-like terminal interface for AI-powered coding assistance featuring 8 specialized agents working asynchronously in real-time.

🚀 Features

• 🎮 Immersive Terminal UI: Game-like interface with real-time agent status
• 🧠 8 Specialized Agents: Planner, Coder, Tester, Debugger, Optimizer, Security, Documenter, Reviewer
• ⚡ Asynchronous Processing: Agents work in parallel with live progress updates
• 🎯 Quest-Based Interface: Enter coding "quests" instead of tasks
• 📊 Real-Time Monitoring: Live agent status with progress bars and emojis
• 🔧 LLM Agnostic: Pluggable interface supporting any language model
• 🧪 252+ Comprehensive Tests: 90%+ coverage with automated quality assessment

🎮 Immersive Experience

When you run feral-code, you enter a coding adventure game:

╔═════════════════════════════════════════════════════╗
║                                                     ║
║   🧙‍♂️ FERAL CODE ORACLE 🧙‍♂️                           ║
║                                                     ║
║   Multi-Agent Coding Adventure - Press ? for help   ║
╚═════════════════════════════════════════════════════╝

🧠 Agent Legion          ⚡ Oracle Progress          🎯 Current Task
🧠 Planner: ⚡ Working     ██████████░░░░ 70%         🎯 TASK INITIATED
💻 Coder: 💤 Idle         [██████████░░░░]            Create a React component
🧪 Tester: 💤 Idle                                      Phase: Coding
🔧 Debugger: 💤 Idle
⚡ Optimizer: 💤 Idle
🛡️ Security: 💤 Idle
📚 Documenter: 💤 Idle
👁️ Reviewer: 💤 Idle

📊 Mission Status         📜 Oracle Chronicles
Phase: Coding             🧙‍♂️ Oracle: Task initiated!
Agents Active: 3          📨 Message: [coder] code: Generating component...
Time Elapsed: 2.3s        🌟 Agent wisdom collected...

🛠️ Installation

Install from npm (Recommended)

npm install -g feral-code
feral-code

Install from source

# Clone the repository
git clone https://github.com/Gonzih/feral-code-agent.git
cd feral-code-agent

# Install dependencies
npm install

# Build the project
npm run build

# Launch the oracle
npm start

🚀 Usage

Launch the Oracle (Default)

# Install globally and run
npm install -g feral-code
feral-code

# Or run locally
npm start

Command Line Options

# Basic task processing
feral-code task "Create a TypeScript function"

# Direct quest mode
feral-code quest "Build a React component"

# Launch oracle interface
feral-code oracle

Interactive Controls

• ESC/Q/Ctrl+C: Exit the oracle
• ?: Show help and agent information
• R: Start a random coding quest
• Enter: Submit your coding quest

🧠 Agent Legion

The Oracle commands 8 specialized agents working asynchronously:

| Agent | Emoji | Role | |-------|-------|------| | Planner | 🧠 | Analyzes requirements and creates detailed task breakdown | | Coder | 💻 | Generates production-ready code based on specifications | | Tester | 🧪 | Creates comprehensive test cases and validation scenarios | | Debugger | 🔧 | Reviews code for potential bugs and edge cases | | Optimizer | ⚡ | Improves performance and code efficiency | | Security | 🛡️ | Implements security measures and vulnerability checks | | Documenter | 📚 | Generates comprehensive documentation and JSDoc comments | | Reviewer | 👁️ | Final quality assessment and validation |

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Immersive CLI │───▶│   Oracle System  │───▶│  Message Bus    │
│   (Blessed.js)  │    │   (Event-Driven) │    │   (Async)       │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │   8 Agents      │    │   LLM Interface │
                       │ • Planner       │    │ • GrokLLM       │
                       │ • Coder         │    │ • MockLLM       │
                       │ • Tester        │    │ • Custom LLMs   │
                       │ • Debugger      │    │                 │
                       │ • Optimizer     │    └─────────────────┘
                       │ • Security      │
                       │ • Documenter    │
                       │ • Reviewer      │
                       └─────────────────┘

🔧 Configuration

Environment Variables

# For Grok LLM integration
XAI_API_KEY=your-xai-api-key-here

# For custom LLM configurations
CUSTOM_LLM_ENDPOINT=https://your-llm-endpoint.com
CUSTOM_LLM_API_KEY=your-custom-api-key

Custom LLM Integration

import { LLM } from './src/interfaces/llm';

class CustomLLM implements LLM {
  async generate(prompt: string): Promise<string> {
    // Your custom LLM implementation
    return 'Generated response';
  }
}

const llm = new CustomLLM();
const coordinator = new Coordinator(llm);

📊 Quality Metrics

| Metric | Score | Status | |--------|-------|--------| | Test Coverage | 90%+ | ✅ EXCELLENT | | Quality Assessment | 94% | ✅ EXCELLENT | | TypeScript Compliance | 100% | ✅ PERFECT | | Automated Testing | 252+ tests | ✅ COMPREHENSIVE | | User Experience | 100% | ✅ IMMERSIVE |

🧪 Testing

Run All Tests

npm test

Run Tests with Coverage

npm run test:coverage

Automated Quality Assessment

cd tmp/test-example
npx ts-node automated-test-runner.ts

📈 Quality Assessment Results

Factorial Function Test (83% - EXCELLENT)

✅ TypeScript syntax with proper type annotations ✅ Error handling for negative numbers and non-integers ✅ Iterative implementation for efficiency ✅ Input validation with throw statements ❌ Missing JSDoc documentation

React Component Test (100% - EXCELLENT)

✅ React import and functional component ✅ useState hook implementation ✅ Event handlers with proper onClick ✅ JSX return with TypeScript types

API Endpoint Test (100% - EXCELLENT)

✅ Express.js router setup ✅ POST method implementation ✅ Request validation middleware ✅ Error handling and responses

🎯 Sample Quests

Try these coding quests with the Oracle:

• "Create a TypeScript function to calculate fibonacci numbers with memoization"
• "Build a React component for a real-time chat interface"
• "Implement a REST API endpoint for user authentication"
• "Create a data structure for efficient graph traversal"
• "Build a CLI tool for file system operations"

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📝 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by cutting-edge multi-agent systems research
• Built with modern TypeScript and Node.js best practices
• Comprehensive testing framework ensures reliability
• Open-source community contributions welcome

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

⭐ Star this repository if you find it useful!

Built with ❤️ using cutting-edge AI and software engineering practices

🎮 Ready to embark on your coding adventure?

npm install -g feral-code
feral-code

Enter the realm of the Feral Code Oracle... 🧙‍♂️⚡