fr3kc0d3/README.md

Personal AI Infrastructure (PAI) - Complete implementation of Daniel Miessler's PAI vision with 4-layer context enforcement, FOBs system, flow orchestration, and Kai digital assistant

# 🧠 fr3kc0de Personal AI Infrastructure

**Advanced AI Systems - Integrated & Production-Ready**

[![npm version](https://img.shields.io/npm/v/fr3kc0de.svg)](https://www.npmjs.com/package/fr3kc0de)
[![Node.js Version](https://img.shields.io/node/v/fr3kc0de.svg)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

fr3kc0de transforms your development workflow with **proven AI methodologies** - Forge patterns, Sage commands, Nexus context management, Flow collaborative workflows, and dynamic hooks - all integrated into a unified, multi-provider AI CLI.

## 🚀 Quick Start

```bash
# Install and run immediately
npx fr3kc0de

# Or install globally
npm install -g fr3kc0de
fr3kc0de
```

## ✨ What Makes fr3kc0de Special

### 🎨 **Forge Pattern System** (300+ AI Patterns)
Battle-tested prompt patterns for consistent, high-quality AI outputs:
```bash
# Extract wisdom from any content
forge_execute_pattern extract_wisdom "Your content here"

# Analyze claims for accuracy and bias
forge_execute_pattern analyze_claims "Claims to verify"

# Improve writing clarity and impact
forge_execute_pattern improve_writing "Text to enhance"
```

### 🗂️ **Nexus (Universal File-based Context)**
Hierarchical context management system for complex projects:
```bash
# Initialize project context structure
nexus_init_project "MyProject"

# Save insights at appropriate levels
nexus_save_context --name="analysis" --level="project" --content="..."

# Load context with inheritance
nexus_load_context "analysis"
```

### 🤖 **Sage Command System** (60+ Specialized Commands)
Domain-specific AI commands across 7 categories:

**Analysis**: `analyze_claims`, `analyze_debate`, `analyze_prose`
**Creation**: `create_summary`, `create_report`, `create_keynote`
**Learning**: `explain_concept`, `create_quiz`, `create_study_guide`
**Technical**: `explain_code`, `review_code`, `create_documentation`
**Communication**: `improve_writing`, `create_email`, `translate_jargon`
**Business**: `analyze_competitors`, `create_pitch`, `analyze_market`
**Personal**: `create_plan`, `analyze_decision`, `extract_wisdom`

```bash
# Execute specialized AI commands
sage_execute_command create_summary "Long document here"
sage_execute_command explain_code "function complex() { ... }"
sage_execute_command analyze_competitors "My business description"
```

### 🧠 **Flow Digital Assistant** (Collaborative Workflows)
Multi-step collaborative workflows for complex projects:
```bash
# Start collaborative research workflow
flow_start_session --name="research" --workflow="research_and_analyze"

# Continue with AI-guided steps
flow_continue_session --session-id="flow_xxx" --input="My research topic"

# Collaborative editing sessions
flow_collaborate --document="project-doc" --type="writing"
```

### 🔗 **Dynamic Hook System**
Automated validation and processing with custom hooks:
```bash
# List available hooks
hooks_list_hooks

# Create custom validation hooks
hooks_create_hook --name="validate_output" --type="post" --script-type="bash"

# Execute hooks manually
hooks_execute_hook "pre_analysis_validation"
```

## 🛠️ Multi-Provider AI Integration

Connect to multiple AI providers with automatic failover:

### Supported Providers
- **🚀 Groq**: Ultra-fast inference (Llama 3.3 70B, Qwen2.5, Mixtral)
- **🌟 OpenRouter**: 200+ models (Claude 3.5 Sonnet, GPT-4, Gemini, DeepSeek R1)
- **🧠 DeepSeek**: Advanced reasoning (DeepSeek-Chat, DeepSeek-R1)

### Setup Your API Keys
```bash
# Configure providers interactively
fr3kc0de
# Follow the setup prompts to add your API keys

# Or use commands
/keys set openrouter YOUR_API_KEY
/model set anthropic/claude-3.5-sonnet
```

## 📋 Available Tools (70+ MCP Tools)

### 🎨 Forge Patterns (3 tools)
- `forge_list_patterns` - Browse 300+ patterns by category
- `forge_execute_pattern` - Execute specialized patterns
- `forge_search_patterns` - Search patterns by keyword

### 🗂️ Nexus Context (5 tools)
- `nexus_list_contexts` - List available contexts
- `nexus_load_context` - Load contexts with inheritance
- `nexus_save_context` - Save to hierarchical levels
- `nexus_init_project` - Initialize project structure
- `nexus_get_aggregated` - Combine multiple contexts

### 🤖 Sage Commands (5 tools)
- `sage_list_commands` - Browse 60+ specialized commands
- `sage_execute_command` - Execute domain-specific commands
- `sage_get_command` - Get command details
- `sage_get_categories` - Browse command categories
- `sage_create_custom_command` - Create custom commands

### 🧠 Flow Assistant (6 tools)
- `flow_start_session` - Start collaborative workflows
- `flow_continue_session` - Progress through workflow steps
- `flow_list_sessions` - Manage active sessions
- `flow_get_session` - Get session details
- `flow_create_workflow` - Design custom workflows
- `flow_collaborate` - Multi-participant editing

### 🔗 Dynamic Hooks (4 tools)
- `hooks_list_hooks` - List available hooks
- `hooks_execute_hook` - Execute specific hooks
- `hooks_create_hook` - Create automation scripts
- `hooks_get_hook_stats` - Hook system statistics

### Plus Advanced Modules
- **Intelligence**: Smart methodology routing (BMAD, AutoExpert, Synapse, DSPy)
- **Memory**: Persistent storage and retrieval with tagging
- **Data**: Real-time streams and anomaly detection
- **Adaptive**: Reinforcement learning and behavioral analysis
- **N8N**: Workflow automation and deployment

## 🎯 Example Workflows

### Content Analysis Workflow
```bash
# 1. Search for relevant patterns
forge_search_patterns "analysis"

# 2. Execute pattern for content extraction
forge_execute_pattern extract_wisdom "Your article content here"

# 3. Store insights in project context
nexus_save_context --name="content_analysis" --level="project" --content="Key insights..."

# 4. Create summary with Sage command
sage_execute_command create_summary "Detailed findings from analysis"
```

### Code Development Workflow
```bash
# 1. Start collaborative session
flow_start_session --name="code_review" --workflow="code_development"

# 2. Explain existing code
sage_execute_command explain_code "function complex() { return x * y; }"

# 3. Review for issues
sage_execute_command review_code "Your code here"

# 4. Generate documentation
sage_execute_command create_documentation "Final code"

# 5. Create validation hooks
hooks_create_hook --name="validate_code" --type="post" --script-type="bash"
```

### Learning Session Workflow
```bash
# 1. Start learning workflow
flow_start_session --name="learn_ai" --workflow="learning_session"

# 2. Explain complex concepts
sage_execute_command explain_concept "Machine Learning fundamentals"

# 3. Create study materials
sage_execute_command create_study_guide "ML concepts and examples"

# 4. Generate practice questions
sage_execute_command create_quiz "Study guide content"

# 5. Save learning progress
nexus_save_context --name="ml_learning" --level="session"
```

## 🔧 Advanced Configuration

### Context Hierarchy
fr3kc0de uses the Nexus (Universal File-based Context) system:
- **Global**: `~/.fr3kc0de/context/global/`
- **Project**: `<project>/.fr3kc0de/context/`
- **Local**: `<directory>/.context/`
- **Session**: `<temp>/fr3kc0de-session/`

### Hook Directories
Dynamic hooks are loaded from:
- `~/.fr3kc0de/hooks/`
- `<project>/.fr3kc0de/hooks/`
- `<directory>/.hooks/`

## 🚀 Why These Advanced Systems?

**fr3kc0de** integrates battle-tested AI methodologies developed and refined over years of real-world usage:

- **Forge**: 300+ prompt patterns used by thousands of developers
- **Sage**: Personal AI Infrastructure with proven command patterns
- **Nexus**: Universal context system for complex project management
- **Flow**: Collaborative AI workflows for team productivity

fr3kc0de integrates all these systems into a unified, production-ready CLI that you can use immediately.

## 📚 Resources

- [MCP Protocol](https://modelcontextprotocol.io/)
- [fr3kc0de Documentation](https://github.com/fr3k/fr3kc0de)
- [Personal AI Infrastructure Guide](https://github.com/fr3k/fr3kc0de/wiki)

## 📄 License

MIT License - feel free to use fr3kc0de in your projects!

## 🤝 Contributing

We welcome contributions! Please see our [DEVELOPMENT.md](./DEVELOPMENT.md) for setup instructions and contribution guidelines.

---

**Get started in seconds**: `npx fr3kc0de` ⚡