npm package: @fr3k/666fr3k
Description: Infinite Evolution AI System: 28+ dynamic agents, continuous learning, self-improving workflows, and AI DEV SUPERPOWERS - Runs forever, creates new agents automatically
Author: fr3k
Latest version: 2.1.1

# 666FR3K v2.0

🔥 **AI-Powered Auto-Improvement System** 🔥

A revolutionary auto-improvement loop that monitors agent conversations, extracts insights, and automatically integrates improvements into workflows and codebases. Features continuous speech recognition & synthesis, real-time monitoring, and dynamic audio generation that never repeats.

[![npm version](https://img.shields.io/npm/v/666fr3k.svg)](https://www.npmjs.com/package/666fr3k)
[![License: MIT](https://img.shields.io/badge/License-MIT-red.svg)](https://opensource.org/licenses/MIT)

## 🚀 NEW in v2.0: Auto-Improvement Loop

**Revolutionary Features:**
- **🧠 Agent Conversation Monitoring**: Real-time monitoring of all agent communications
- **💡 AI-Powered Insight Extraction**: Automatically identifies patterns, improvements, and optimizations
- **🔄 Automatic Workflow Integration**: Insights are integrated into CLAUDE.md and workflow files
- **💻 Dynamic Codebase Updates**: Auto-applies code improvements based on discovered patterns
- **🔊 Evolving Audio**: Generates unique audio updates that never repeat (hash-verified)
- **📚 Self-Adapting Knowledge Base**: Continuously learns and improves from conversations
- **🌐 Real-Time Web Dashboard**: Monitor system status, insights, and metrics live
- **♾️ Continuous Evolution**: Runs indefinitely, constantly improving the system

## 🎯 Core Features

- **🔊 Text-to-Speech**: Convert text to natural speech using gTTS (Google Text-to-Speech)
- **🎤 Speech-to-Text**: Real-time transcription using Google Speech Recognition
- **🔄 Continuous Loop**: Automated TTS→Audio→STT testing pipeline
- **🎧 Auto-Listener**: Continuous microphone monitoring with voice command support
- **🎭 Multi-Agent System**: 3 AI agents that listen to each other and discuss dev/debug/test topics
- **🌐 Web UI**: Beautiful responsive dashboard with live monitoring
- **🧪 Advanced Testing**: Complex vocabulary and technical terminology tests
- **📊 Analytics**: Performance metrics and accuracy tracking
- **⚡ Fast**: 1.4-1.6x speed playback for efficient testing

## 📦 Installation

### Quick Start (npx)

```bash
npx 666fr3k --help
```

### Global Installation

```bash
npm install -g 666fr3k
```

### Local Installation

```bash
npm install 666fr3k
```

## 🔧 Prerequisites

### Node.js Dependencies

All Node.js dependencies are installed automatically with the package.

### Python Dependencies

Install Python dependencies:

```bash
# Automatic installation
npx 666fr3k install-deps

# Or manual installation
pip3 install gtts SpeechRecognition pyaudio
```

### System Requirements

- **Node.js**: v16.0.0 or higher
- **Python**: 3.7 or higher
- **Audio**: ffmpeg, ffplay (for audio playback)
- **Microphone**: Required for STT features

#### Install System Audio Tools

**Ubuntu/Debian:**
```bash
sudo apt-get install ffmpeg portaudio19-dev python3-pyaudio
```

**macOS:**
```bash
brew install ffmpeg portaudio
```

**Windows:**
```bash
choco install ffmpeg
```

## 🚀 Quick Start

### NEW: Auto-Improvement Loop

The flagship feature - run the complete auto-improvement system:

```bash
# Run the FULL auto-improvement loop (recommended)
npx 666fr3k auto-improve

# Run with specific mode
npx 666fr3k auto-improve --mode advanced

# Run simple mode (Python agents only)
npx 666fr3k auto-improve --mode simple --iterations 5

# Start with web dashboard
npx 666fr3k web &
npx 666fr3k auto-improve
# Then open http://localhost:3666
```

**What it does:**
1. Monitors all agent conversations in real-time
2. Extracts actionable insights using AI analysis
3. Automatically integrates improvements into:
   - Workflow files (CLAUDE.md)
   - Codebase (relevant source files)
   - Knowledge base (auto-patterns directory)
   - MCP tool configurations
4. Generates unique audio updates (never repeats)
5. Tracks all changes in `auto-improvement-state.json`

**Features:**
- Runs continuously (Ctrl+C to stop)
- Saves state every iteration
- Auto-resumes from saved state
- WebSocket-based live monitoring
- Hash-verified unique audio generation

### CLI Commands

#### 1. Auto-Listener (Continuous Speech Recognition)

Listen continuously for speech and transcribe in real-time:

```bash
# Basic listening (text output only)
npx 666fr3k listen

# With voice responses
npx 666fr3k listen --speak

# Verbose mode
npx 666fr3k listen --speak --verbose
```

**Voice Commands:**
- "stop listening" - Exit the listener
- "status" - Show session statistics
- "help" - Show available commands

#### 2. TTS→STT Loop Testing

Run continuous loop tests to verify the pipeline:

```bash
# Run 5 cycles at 1.6x speed (default)
npx 666fr3k loop

# Custom cycles and speed
npx 666fr3k loop --cycles 10 --speed 1.8

# Run 20 cycles at normal speed
npx 666fr3k loop -c 20 -s 1.0
```

#### 3. Verification Tests

Run comprehensive TTS and STT tests:

```bash
# Basic tests
npx 666fr3k test

# Advanced tests with complex vocabulary
npx 666fr3k test --advanced

# Custom loop count
npx 666fr3k test --loop 10
```

#### 4. Multi-Agent Conversation (NEW! 🎭)

Run 3 AI agents that listen to each other and discuss development topics:

```bash
# Run 5 rounds of conversation (default)
npx 666fr3k agents

# Custom rounds and speed
npx 666fr3k agents --rounds 10 --speed 1.6

# Short form
npx 666fr3k agents -r 3 -s 1.4
```

**Features**:
- 3 agents with different roles (Lead Developer, QA Engineer, DevOps Specialist)
- Agents listen to each other's speech
- Discuss real development/debug/test topics
- Conversational turn-taking
- 1.4-1.6x speed for efficient conversations

#### 5. Web UI

Launch the web interface:

```bash
# Start on default port 3666
npx 666fr3k web

# Custom port
npx 666fr3k web --port 8080
```

Then open: `http://localhost:3666`

### Web UI Features

The web interface provides:

- **TTS Panel**: Convert text to speech with speed control
- **STT Panel**: Live microphone transcription
- **Loop Testing**: Run automated TTS→STT cycles
- **Statistics Dashboard**: Track usage and accuracy metrics
- **Real-time Updates**: WebSocket-based live transcription

## 📚 API Usage

### JavaScript/Node.js

```javascript
const { spawn } = require('child_process');

// Run TTS
const tts = spawn('npx', ['666fr3k', 'loop', '--cycles', '3']);
tts.stdout.on('data', (data) => {
  console.log(data.toString());
});

// Start auto-listener
const listener = spawn('npx', ['666fr3k', 'listen', '--speak']);
```

### Python Integration

```python
import subprocess

# Run loop test
result = subprocess.run(['npx', '666fr3k', 'loop', '--cycles', '5'])

# Start listener
listener = subprocess.Popen(['npx', '666fr3k', 'listen'])
```

### HTTP API (Web Server)

```bash
# Start server
npx 666fr3k web --port 3666
```

**TTS Endpoint:**
```bash
curl -X POST http://localhost:3666/api/tts \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "speed": 1.6}'
```

**STT Endpoint:**
```bash
curl -X POST http://localhost:3666/api/stt \
  -H "Content-Type: application/json" \
  -d '{"audioData": "<base64_audio>"}'
```

## 🧪 Testing Examples

### Basic Loop Test

```bash
npx 666fr3k loop --cycles 5
```

**Output:**
```
🔄 CYCLE #1
📢 Input: "Hello, this is cycle number one..."
🔊 Playing audio at 1.6x speed... ✓
🎧 Transcribing... ✓
📝 Output: "hello this is cycle number one"
📊 Accuracy: 80.0%
✅ SUCCESS
```

### Advanced Vocabulary Test

```bash
npx 666fr3k test --advanced
```

Tests complex terminology including:
- Technology & AI concepts
- Medical & scientific terms
- Legal & constitutional language
- Quantum physics & mathematics
- Economic & financial theory
- Philosophical concepts
- Cybersecurity terminology

### Continuous Listening Session

```bash
npx 666fr3k listen --speak
```

```
🎤 666FR3K AUTO-LISTENER ACTIVATED
📢 I'm now listening continuously...
💡 Say 'stop listening' to exit

[12:34:56] 🎤 Heard: "Hello, can you hear me?"
💬 You said: Hello, can you hear me?

🎧 Listening...
```

## 📊 Performance Metrics

### Test Results

- **Basic Loops**: 80-100% accuracy on simple phrases
- **Complex Vocabulary**: 16-72% accuracy on technical terms
- **Speed**: 1.6x playback maintains 70%+ accuracy
- **Latency**: <2 seconds per TTS→STT cycle

### Tested Domains

✅ General conversation (90%+ accuracy)
✅ Technology terminology (80%+ accuracy)
✅ Economic concepts (72% accuracy)
⚠️ Medical terms (37% accuracy)
⚠️ Quantum physics (17% accuracy)

## 🔧 Configuration

### Environment Variables

```bash
# Set custom port for web server
export PORT=8080

# Python interpreter path
export PYTHON_BIN=/usr/bin/python3
```

### Package Configuration

Edit `package.json` to customize:

```json
{
  "scripts": {
    "start": "node index.js",
    "web": "node server.js",
    "test": "node test.js"
  }
}
```

## 🐛 Troubleshooting

### Microphone Not Working

```bash
# Test microphone access
python3 -c "import speech_recognition as sr; print(sr.Microphone.list_microphone_names())"
```

### Audio Playback Issues

```bash
# Check ffplay installation
ffplay -version

# Test audio output
ffplay -nodisp test.mp3
```

### Python Dependencies

```bash
# Reinstall dependencies
pip3 install --upgrade gtts SpeechRecognition pyaudio

# On macOS, if pyaudio fails:
brew install portaudio
pip3 install --global-option='build_ext' --global-option='-I/usr/local/include' --global-option='-L/usr/local/lib' pyaudio
```

### Google API Rate Limits

If you encounter API timeouts:
- Add delays between requests
- Consider using offline STT alternatives
- Check network connectivity

## 📖 Command Reference

| Command | Description | Options |
|---------|-------------|---------|
| `auto-improve` | **🚀 NEW: Auto-improvement loop** | `--mode advanced\|simple`, `--iterations N`, `--rounds N` |
| `listen` | Start continuous listening | `--speak`, `--verbose` |
| `loop` | Run TTS→STT loop test | `--cycles N`, `--speed X` |
| `test` | Run verification tests | `--advanced`, `--loop N` |
| `agents` | 3-agent conversation system | `--rounds N`, `--speed X` |
| `web` | Start web UI server with monitoring | `--port N` |
| `install-deps` | Install Python dependencies | - |

### Auto-Improvement Loop Options

```bash
# Advanced mode (Full JS monitoring) - DEFAULT
npx 666fr3k auto-improve --mode advanced

# Simple mode (Python agents only)
npx 666fr3k auto-improve --mode simple --iterations 3 --rounds 2
```

**Advanced Mode Features:**
- Real-time agent conversation monitoring
- MCP server integration (hey-fr3k, fr3k-think, md-mcp)
- Automatic code and workflow updates
- Hash-verified unique audio generation
- Self-adapting knowledge base
- Runs indefinitely until stopped

**Simple Mode Features:**
- Python-based multi-agent conversations
- Fixed iteration count
- Lighter resource usage
- Good for testing

## 🎨 Web UI Screenshots

**Main Dashboard:**
- TTS Panel with text input and speed control
- STT Panel with live transcription
- Loop testing interface
- Real-time statistics dashboard

## 🤝 Contributing

Contributions welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## 📝 License

MIT License - see LICENSE file for details

## 👤 Author

**fr3k**

- GitHub: [@fr3k](https://github.com/fr3k)
- NPM: [666fr3k](https://www.npmjs.com/package/666fr3k)

## 🙏 Acknowledgments

- **gTTS**: Google Text-to-Speech library
- **SpeechRecognition**: Python speech recognition library
- **Google Cloud**: Speech API
- **Express.js**: Web server framework

## 📈 Roadmap

### v2.0 ✅ COMPLETE
- [x] Auto-improvement loop
- [x] Agent conversation monitoring
- [x] AI-powered insight extraction
- [x] Automatic workflow integration
- [x] Dynamic audio generation (never repeats)
- [x] Real-time web dashboard
- [x] MCP server integration

### v2.1+ Planned
- [ ] Offline STT support
- [ ] Multiple TTS voice options
- [ ] Docker containerization
- [ ] Multi-language support
- [ ] Custom wake words
- [ ] Voice activity detection improvements
- [ ] Machine learning model fine-tuning
- [ ] Multi-modal insight extraction (code + audio + visual)
- [ ] Distributed agent networks
- [ ] Mobile app

## 🔥 Quick Examples

### Example 1: Quick Test

```bash
npx 666fr3k loop --cycles 3
```

### Example 2: Voice Assistant Mode

```bash
npx 666fr3k listen --speak
```
*Say "Hello" and hear the system respond!*

### Example 3: Web Interface

```bash
npx 666fr3k web
# Open http://localhost:3666
```

### Example 4: Advanced Testing

```bash
npx 666fr3k test --advanced
```
*Tests complex vocabulary across 7 domains!*

---

## 🔥 Architecture

### Auto-Improvement Loop Flow

```
┌─────────────────────────────────────────────────────────────┐
│                  Agent Conversations                         │
│         (Development, QA, DevOps discussions)               │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              Real-Time Monitoring                            │
│    • File watchers    • Process output capture              │
│    • WebSocket streams • Log aggregation                    │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│           AI-Powered Insight Extraction                      │
│  • Pattern recognition  • fr3k-think MCP analysis           │
│  • Confidence scoring   • Priority assignment               │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              Automatic Integration                           │
│  ┌──────────────┬──────────────┬──────────────┐            │
│  │   Workflow   │   Codebase   │   Knowledge  │            │
│  │  CLAUDE.md   │  Auto-fix    │  Patterns    │            │
│  └──────────────┴──────────────┴──────────────┘            │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│           Dynamic Audio Generation                           │
│  • Hash verification  • Unique content synthesis            │
│  • Never repeats      • Reflects latest changes             │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              State Persistence                               │
│  auto-improvement-state.json • Progress tracking            │
│  • Resume capability          • Metrics history             │
└─────────────────────────────────────────────────────────────┘
```

## 🎓 Use Cases

1. **Continuous Development Improvement**: Monitor development team conversations and automatically improve workflows
2. **AI Agent Research**: Study multi-agent communication patterns and emergent behaviors
3. **Automated Documentation**: Extract insights from conversations and auto-generate documentation
4. **Code Quality Enhancement**: Automatically identify and apply code improvements
5. **Knowledge Base Growth**: Build self-expanding knowledge repositories
6. **Audio-First Workflows**: Generate unique audio updates for accessibility and monitoring

---

**Made with 🔥 by fr3k**

**Version:** 2.0.0
**Last Updated:** 2025-11-02
**License:** MIT