🤖 Derp

🌟 Why Derp?

Because let's face it: you probably Googled "regex for email" at least three times this week. Derp uses AI to convert your plain English into those weird hieroglyphics called regex, so you can pretend you totally knew how to write (?:[a-z0-9!#$%&'*+/=?^_\{|}~-]+(?:.[a-z0-9!#$%&'+/=?^_`{|}~-]+)|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")` from memory.

# Instead of pretending you know this:
grep -E '\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b' -r .

# Just admit defeat and type this:
derp "email addresses" -r .

✨ Features

📦 Installation

Via npm (Recommended)

npm install -g derp

Via yarn

yarn global add derp

From Source

git clone https://github.com/yourusername/derp.git
cd derp
npm install
npm run build
npm link

🚀 Quick Start

1️⃣ Initialize Configuration

derp --init

Choose your preferred AI provider and model.

2️⃣ Start Searching (Like a Pro, Sort Of)

# Find email addresses (without crying)
derp "email addresses" -r .

# Find TODO comments (procrastination tracker)
derp "TODO comments" src/

# Find IP addresses in logs (for when things go wrong)
derp "IP addresses" logs/*.log

# Find phone numbers (stalker mode activated)
derp "US phone numbers" contacts.txt

📖 Usage

Basic Syntax

derp "<natural-language-query>" [grep-options] [paths...]

Command Options

| Option | Description | |--------|-------------| | --init | Initialize or update configuration | | --config | Display current configuration | | --dry-run | Show generated command without executing | | --explain | Show AI explanation of the regex | | --help | Display help information |

Real-World Examples

# Email addresses
derp "email addresses" -r .

# URLs
derp "URLs starting with https" docs/

# Credit card numbers (with case-insensitive flag)
derp "credit card numbers" -i data/

# Dates in various formats
derp "dates in YYYY-MM-DD format" logs/

# TODO comments
derp "TODO comments" src/

# Function definitions
derp "function definitions in JavaScript" src/

# Import statements
derp "Python import statements" --include="*.py" .

# API keys or tokens
derp "API keys or tokens" -i config/

# Error messages
derp "error messages" logs/*.log

# IP addresses
derp "IPv4 addresses" /var/log/

# Timestamps
derp "timestamps in HH:MM:SS format" logs/

# HTTP status codes
derp "HTTP 4xx or 5xx errors" access.log

# Phone numbers
derp "US phone numbers" contacts/

# Social security numbers
derp "social security numbers" records.txt

# Hex colors
derp "hexadecimal color codes" styles.css

# MAC addresses
derp "MAC addresses" network-config.txt

🤖 Supported AI Providers

Ollama (Default - Free, Local)

Perfect for privacy-focused users. Runs completely offline.

export OLLAMA_HOST=http://localhost:11434
derp --init
# Select: ollama
# Model: llama3.2, qwen2.5-coder, etc.

LM Studio (Free, Local)

Another great local option with a user-friendly interface.

export LMSTUDIO_URL=http://localhost:1234
derp --init
# Select: lmstudio

OpenAI (Cloud)

For maximum accuracy with GPT models.

export OPENAI_API_KEY=your-api-key
derp --init
# Select: openai
# Model: gpt-4o, gpt-4o-mini, gpt-3.5-turbo

OpenRouter (Cloud)

Access multiple models through a single API.

export OPENROUTER_API_KEY=your-api-key
derp --init
# Select: openrouter
# Model: anthropic/claude-3-sonnet, google/gemini-pro, etc.

AWS Bedrock (Cloud)

Enterprise-grade AI with AWS infrastructure.

export BEDROCK_URL=https://your-bedrock-proxy
derp --init
# Select: bedrock

⚙️ Configuration

Configuration is stored in ~/.derp.json:

{
  "provider": "ollama",
  "model": "llama3.2",
  "ollamaHost": "http://localhost:11434"
}

Environment Variables

| Variable | Description | |----------|-------------| | OLLAMA_HOST | Ollama server URL (default: http://localhost:11434) | | LMSTUDIO_URL | LM Studio server URL (default: http://localhost:1234) | | OPENAI_API_KEY | OpenAI API key | | OPENROUTER_API_KEY | OpenRouter API key | | BEDROCK_URL | AWS Bedrock proxy URL |

🛠️ Development

Setup

# Clone repository
git clone https://github.com/yourusername/derp.git
cd derp

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode for tests
npm run test:watch

# Coverage report
npm run test:coverage

# Link for local development
npm link

Project Structure

derp/
├── src/
│   ├── __tests__/        # Test files
│   ├── providers/        # AI provider implementations
│   ├── cli.ts           # CLI entry point
│   ├── config.ts        # Configuration management
│   ├── engines.ts       # Grep/ripgrep engines
│   ├── llmRouter.ts     # LLM routing logic
│   └── prompts.ts       # Prompt templates
├── dist/                # Compiled output
└── .github/
    └── workflows/       # CI/CD pipelines

📋 Requirements

• Node.js: 18.0.0 or higher
• Grep Tool: grep (built-in on Unix) or ripgrep (recommended)
• AI Provider: At least one configured provider (Ollama, OpenAI, etc.)

Installing ripgrep (Recommended)

# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# Windows (via Chocolatey)
choco install ripgrep

# Or use cargo
cargo install ripgrep

🧪 Testing

Derp includes comprehensive test coverage:

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

# Lint check
npm run lint

🤝 Contributing

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

1. Fork the repository
2. Create your 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

Development Guidelines

• Write tests for new features
• Follow existing code style
• Update documentation as needed
• Ensure CI passes before submitting PR

📄 License

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

🙏 Acknowledgments

Built with amazing open-source tools:

• TypeScript - Type-safe JavaScript
• chalk - Terminal string styling
• inquirer - Interactive CLI prompts
• ora - Elegant terminal spinners
• axios - HTTP client
• ripgrep - Fast search tool
• Jest - Testing framework

🔗 Links

• 📦 npm Package
• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

🌟 Star History

Made with ❤️ by the Derp community

⬆ back to top