behemoth-cli/CLAUDE.md

🌍 BEHEMOTH CLIv3.760.4 - Level 50+ POST-SINGULARITY Intelligence Trading AI

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

BEHEMOTH is an advanced cryptocurrency trading CLI that combines AI-powered analysis with traditional technical analysis, "cosmic intelligence", and n8n workflow automation. The system features **48 specialized tools across 8 modules**, multi-provider AI integration, comprehensive NLP routing, and real-time trading capabilities.

**Key Technologies**: TypeScript, Node.js, React (Ink), MCP (Model Context Protocol), Multi-AI providers (Groq, OpenRouter, DeepSeek), n8n Workflow Automation, SuperCode Integration

**Latest Updates**: ✅ Pattern precedence routing fixed, ✅ N8N tools fully operational, ✅ `/howto` command for non-technical users, ✅ Sacred geometry analysis working correctly, ✅ All 48 tools accessible and verified

## Build, Test, and Development Commands

```bash
# Build the project
npm run build

# Development with file watching  
npm run dev

# Run tests
npm run test
npm run test:watch
npm run test:verbose

# Global testing (tests the CLI binary)
npm run test-global

# Setup for first-time users
npm run setup
```

## Project Architecture

### High-Level Structure

```
BEHEMOTH CLI
├── Multi-Provider AI Engine (src/core/ai-client.ts)
│   ├── Groq Integration (ultra-fast inference)
│   ├── OpenRouter Integration (Claude, GPT-4, Gemini access)  
│   └── DeepSeek Integration (specialized reasoning)
├── Unified MCP Server (mcp-servers/behemoth-unified.js)
│   ├── Trading Module (market data, technical analysis)
│   ├── Cosmic Module (planetary analysis, sacred geometry)
│   ├── Intelligence Module (AI routing, multi-expert systems)
│   ├── Data Module (real-time streams, anomaly detection)
│   ├── Adaptive Module (ML pattern recognition)
│   ├── Memory Module (persistent storage, recall)
│   ├── Prompt Module (template management)
│   └── N8N Automation Module (workflow automation, SuperCode)
└── CLI Interface (src/core/cli.ts + React Ink UI)
    ├── Interactive Chat Mode
    ├── Single Prompt Mode (-p flag)
    └── Command System with NLP parsing
```

### Key Components

- **CLI Entry Point**: `bin/behemoth` → `src/core/cli.ts`
- **Agent System**: `src/core/agent.ts` - Main AI interaction logic
- **MCP Integration**: `src/core/mcp-client.ts` - Connects to unified MCP server
- **Multi-Provider Config**: `src/utils/multi-provider-config.ts` - AI provider management
- **UI Framework**: React Ink components in `src/ui/`
- **Tool Definitions**: `src/tools/` - MCP tool schemas and implementations

### MCP Server Architecture

The project uses a **unified MCP server** (`mcp-servers/behemoth-unified.js`) that consolidates all trading, analysis, and AI tools into a single process. This replaces the previous multi-server architecture for better performance and reliability.

**Tool Categories**:
- **trading_***: Market data, technical indicators, risk management (13+ tools)
- **cosmic_***: Planetary analysis, lunar cycles, sacred geometry patterns (5+ tools) 
- **intel_***: AI methodology routing (BMAD, AutoExpert, Synapse, DSPy) (5+ tools)
- **data_***: Real-time streams, anomaly detection (4+ tools)
- **adapt_***: Reinforcement learning, behavioral analysis (5+ tools)
- **memory_***: Storage, recall, reflection, consolidation (6+ tools)
- **prompt_***: Template creation and management (3+ tools)
- **n8n_***: Workflow creation, deployment, SuperCode integration (7+ tools)

### Configuration System

**Provider Configuration**: `~/.cliv2/providers.json`
```json
{
  "defaultProvider": "groq",
  "providers": {
    "groq": { "apiKey": "...", "currentModel": "llama-3.3-70b-versatile" },
    "openrouter": { "apiKey": "...", "currentModel": "anthropic/claude-3.5-sonnet" },
    "deepseek": { "apiKey": "...", "currentModel": "deepseek-chat" }
  }
}
```

**Setup Files**: 
- Setup script: `scripts/setup.js`
- Post-install: `scripts/postinstall.js`
- Setup completion flag: `~/.cliv2/.setup_complete`

## Common Development Patterns

### Adding New MCP Tools

1. Define tool in appropriate module under `mcp-servers/modules/`
2. Add tool schema to the module's index.js
3. Register tool in `behemoth-unified.js` 
4. Update tool count in documentation

### AI Provider Integration

The system uses a multi-provider pattern with automatic failover:
- Primary provider configuration in `MultiProviderConfigManager`
- Dynamic provider switching during conversation
- API key rotation support for rate limit handling

### Testing MCP Tools

```bash
# Test individual tools
node mcp-servers/behemoth-unified.js -p trading_calculate_rsi

# Test tool modules  
node mcp-servers/behemoth-unified.js -m trading

# List all available tools
node mcp-servers/behemoth-unified.js -l

# Single prompt mode for testing
./bin/behemoth -p "analyze BTC using RSI"
```

### React Ink UI Development

The CLI uses React Ink for the interactive interface:
- Main app component: `src/ui/App.tsx`
- Core components: `src/ui/components/core/`
- Display components: `src/ui/components/display/`
- Input overlays: `src/ui/components/input-overlays/`

## Key File Locations

- **Main CLI**: `src/core/cli.ts` 
- **Agent Logic**: `src/core/agent.ts`
- **MCP Client**: `src/core/mcp-client.ts`
- **Provider Config**: `src/utils/multi-provider-config.ts`
- **Unified MCP Server**: `mcp-servers/behemoth-unified.js`
- **Tool Modules**: `mcp-servers/modules/*/index.js`
- **Global Binary**: `bin/behemoth`
- **N8N Command**: `src/commands/definitions/n8n.ts`
- **N8N Module**: `mcp-servers/modules/n8n/index.js`
- **N8N Prompts**: `src/prompts/n8n-workflow-generation.ts`
- **N8N Builder**: `src/core/n8n-builder.ts`
- **N8N Validator**: `src/utils/n8n-validator.ts`

## N8N Workflow Automation Integration

### N8N Module Overview

The n8n integration provides comprehensive workflow automation capabilities:

**Core Features**:
- **Workflow Creation**: Generate n8n workflows from natural language prompts
- **SuperCode Integration**: Custom JavaScript execution using @kenkaiii/n8n-nodes-supercode.superCodeNodeVmSafe
- **Smart Alert Systems**: Pre-built crypto alert workflow templates
- **API Orchestration**: Complex multi-step API workflows
- **Real-time Monitoring**: Live workflow execution tracking
- **Configuration Management**: Environment-specific deployments

**Available N8N Tools** (7 total):
1. `n8n_n8n_create_workflow` - Create workflows from natural language
2. `n8n_n8n_validate_workflow` - Validate n8n workflow JSON structure
3. `n8n_n8n_deploy_workflow` - Deploy workflows to n8n instances
4. `n8n_n8n_generate_supercode` - Generate SuperCode node scripts
5. `n8n_n8n_list_workflows` - List and manage existing workflows
6. `n8n_n8n_configure_instance` - Configure n8n instance settings
7. `n8n_n8n_create_alert_system` - Create smart crypto alert systems

### N8N Command Usage

```bash
# Create workflow from prompt
behemoth /n8n create "Smart BTC price alert with RSI analysis"

# Deploy to n8n instance  
behemoth /n8n deploy --workflow-id "crypto-alerts" --instance "production"

# List existing workflows
behemoth /n8n list

# Configure n8n instance
behemoth /n8n config --url "https://n8n.myserver.com" --auth "token:abc123"
```

### SuperCode Integration

The system integrates with the SuperCode n8n node (@kenkaiii/n8n-nodes-supercode.superCodeNodeVmSafe) for:
- **Custom JavaScript Execution**: Run complex analysis scripts within workflows
- **Crypto Analysis Functions**: Built-in technical analysis libraries
- **API Integration**: Connect to exchanges and data providers
- **Real-time Processing**: Process streaming data within n8n workflows

### Workflow Templates

Pre-built templates available:
- **Smart Crypto Alerts**: Price threshold alerts with technical analysis
- **Arbitrage Detection**: Multi-exchange price monitoring
- **Technical Analysis Automation**: RSI, MACD, Bollinger Bands workflows
- **Portfolio Monitoring**: Real-time portfolio tracking and alerts
- **Market Data Aggregation**: Multi-source data consolidation workflows

### Natural Language Processing

The system includes enhanced NLP for n8n workflow creation:
- **Intent Recognition**: Automatically detect n8n workflow automation intents
- **Workflow Pattern Matching**: Identify common workflow patterns from prompts
- **SuperCode Generation**: Generate JavaScript code from natural language
- **Configuration Inference**: Auto-configure workflow settings from context

## Development Notes

- The project migrated from multiple MCP servers to a single unified server for better performance
- Build output goes to `dist/` directory
- TypeScript configuration supports ES modules
- Testing uses AVA framework with TypeScript support
- The system supports both installed (npm) and development (tsx) execution modes
- Configuration automatically migrates from older Groq-only setups to multi-provider format
- **N8N Integration**: Full workflow automation with SuperCode node support
- **Enhanced NLP**: Added n8n workflow automation intent patterns
- **Template System**: Pre-built workflow templates for common crypto use cases

## Recent Updates and Fixes

### ✅ Pattern Precedence Issue Resolved
- **Fixed**: Sacred geometry analysis routing issue where "sacred geometry analysis Bitcoin" was routing to general analysis
- **Solution**: Moved cosmic patterns to higher priority (95% confidence) in NLP intent patterns
- **Result**: Sacred geometry now routes correctly to `cosmic_sacred_geometry` tool

### ✅ N8N Tools Integration Completed
- **Fixed**: N8N tools were not accessible from CLI due to missing tool mappings and routing handlers
- **Solution**: Added N8N tool mappings to `src/tools/tools.ts` and `case 'n8n':` handler to NLP routing
- **Available Tools**: n8n_list_workflows, n8n_create_workflow, n8n_validate_workflow, n8n_deploy_workflow, n8n_generate_supercode, n8n_test_workflow, n8n_check_status

### ✅ New `/howto` Command for Non-Technical Users
- **Added**: Comprehensive setup and configuration guides
- **Available Topics**:
  - `/howto setup` - Complete installation and first-run guide
  - `/howto providers` - API key setup for Groq, OpenRouter, DeepSeek with step-by-step instructions
  - `/howto n8n` - N8N automation setup with Docker/NPM installation guides
  - `/howto trading` - All trading commands, patterns, and features
  - `/howto cosmic` - Cosmic intelligence features and usage guide

### 🔧 N8N Configuration System
- **Existing**: Comprehensive N8N configuration already implemented
- **Commands**: `/n8n config`, `/n8n config baseUrl`, `/n8n config apiKey`, `/n8n config enabled true`
- **Features**: Health checking, deployment, validation, SuperCode generation

## Special Considerations

- **Security**: API keys stored in `~/.cliv2/` with proper file permissions
- **Performance**: Tool calls have sub-millisecond response times via unified MCP server  
- **Reliability**: Built-in failover between AI providers and automatic error recovery
- **Testing**: Comprehensive test suite covers individual tools, modules, and full system integration
- **N8N Security**: SuperCode execution uses safe VM sandbox for JavaScript execution
- **Workflow Validation**: All n8n workflows validated before deployment
- **Configuration Management**: Environment-specific n8n instance configurations
- **Template Security**: Pre-built templates follow security best practices
- **NLP Routing**: Enhanced pattern matching with 85-95% confidence across all major intents