{"id":29288676,"url":"https://github.com/bewinxed/llm-whip","last_synced_at":"2026-05-20T07:41:14.757Z","repository":{"id":298781332,"uuid":"1000919802","full_name":"Bewinxed/llm-whip","owner":"Bewinxed","description":"File monitoring tool that detects lazy patterns and anti-cheat behaviors in code and LLM conversations","archived":false,"fork":false,"pushed_at":"2025-06-13T17:15:24.000Z","size":4896,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-13T17:36:18.972Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bewinxed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-12T14:20:54.000Z","updated_at":"2025-06-13T17:15:27.000Z","dependencies_parsed_at":"2025-06-13T17:36:21.660Z","dependency_job_id":"95f1ea07-2be2-43d1-b467-54c6c9ad4488","html_url":"https://github.com/Bewinxed/llm-whip","commit_stats":null,"previous_names":["bewinxed/claude-watchdog","bewinxed/llm-whip"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Bewinxed/llm-whip","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bewinxed%2Fllm-whip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bewinxed%2Fllm-whip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bewinxed%2Fllm-whip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bewinxed%2Fllm-whip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bewinxed","download_url":"https://codeload.github.com/Bewinxed/llm-whip/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bewinxed%2Fllm-whip/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263841739,"owners_count":23518493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-06T03:12:03.444Z","updated_at":"2026-05-20T07:41:09.696Z","avatar_url":"https://github.com/Bewinxed.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LLM Whip\n\n[![npm version](https://badge.fury.io/js/llm-whip.svg)](https://www.npmjs.com/package/llm-whip)\n[![npm downloads](https://img.shields.io/npm/dm/llm-whip.svg)](https://www.npmjs.com/package/llm-whip)\n[![CI](https://github.com/bewinxed/llm-whip/workflows/CI/badge.svg)](https://github.com/bewinxed/llm-whip/actions)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n![banner](assets/banner.png)\n\nA TypeScript CLI tool that monitors code for lazy patterns and anti-cheat detection when working with LLMs.\n\n## Overview\n\nLLM Whip detects common shortcuts and anti-patterns in code:\n\n-   TODO comments and placeholders\n-   Stub implementations\n-   \"The important thing is...\" statements\n-   Not implemented errors\n-   Other lazy coding patterns\n\n## Features\n\n-   **Directory Auditing**: Scan codebases for existing patterns\n-   **Real-time Monitoring**: Watch files as they change\n-   **TypeScript Configuration**: Type-safe configuration files\n-   **Multiple Output Formats**: Table, JSON, CSV export\n-   **Baseline Tracking**: Alert only on new patterns\n-   **Configurable Patterns**: Define custom detection rules\n\n## Quick Start\n\n```bash\n# Install\nnpm install -g llm-whip\n\n# Monitor current directory with alerts\nllm-whip\n\n# Monitor with keyboard interrupts + sound\nllm-whip --interrupt --sound\n\n# Audit existing code\nllm-whip audit ./src\n```\n\n## Installation\n\n```bash\nbun add -g llm-whip\n# or\nnpm install -g llm-whip\n```\n\n## Usage\n\n```bash\n# Show help\nllm-whip --help\n\n# Monitor current directory\nllm-whip\n\n# Monitor specific directories\nllm-whip ./src ./lib\n\n# Monitor with keyboard interrupts (sends ESC + text + Enter to active window)\nllm-whip ./src --interrupt\n\n# Monitor with sound alerts\nllm-whip ./src --sound\n\n# Create configuration file\nllm-whip init\n\n# Audit current directory\nllm-whip audit\n```\n\n## Commands\n\n| Command                    | Description                              |\n| -------------------------- | ---------------------------------------- |\n| `llm-whip`                 | Monitor current directory                |\n| `llm-whip init [dir]`      | Create configuration file                |\n| `llm-whip audit [dirs...]` | Scan directories for patterns            |\n| `llm-whip watch \u003cdirs...\u003e` | Monitor directories in real-time         |\n\n## Options\n\n| Option              | Description                                              |\n| ------------------- | -------------------------------------------------------- |\n| `--config=\u003cpath\u003e`   | Custom configuration file                                |\n| `--format=\u003ctype\u003e`   | Audit output format (table/json/csv)                     |\n| `--grep=\u003cpatterns\u003e` | Filter files by content patterns                         |\n| `--interrupt`       | Enable keyboard interrupts (sends ESC + text + Enter to active window) |\n| `--sound`           | Enable sound alerts                                       |\n\n## Configuration\n\nLLM Whip supports both TypeScript (`.ts`) and JSON (`.json`) configuration files.\n\n### TypeScript Configuration\n\nCreate `llm-whip.config.ts`:\n\n```typescript\nimport type { Config } from 'llm-whip/types';\n\nexport const config: Config = {\n\tpatterns: [\n\t\t{\n\t\t\tname: 'todo',\n\t\t\tpattern: 'TODO',\n\t\t\tseverity: 'high',\n\t\t\treactions: ['sound', 'alert', 'interrupt'],\n\t\t\tmessage: 'TODO comment detected',\n\t\t\tinterruptMessage:\n\t\t\t\t'TODO comments should be completed before submitting code. Please implement the actual functionality instead of leaving placeholder comments.',\n\t\t},\n\t\t{\n\t\t\tname: 'important-thing',\n\t\t\tpattern: 'The important thing is',\n\t\t\tseverity: 'medium',\n\t\t\treactions: ['alert'],\n\t\t\tinterruptMessage:\n\t\t\t\t\"Detected 'The important thing is...' - this often indicates avoiding detailed implementation. Please provide specific, actionable details.\",\n\t\t},\n\t],\n\treactions: {\n\t\tsound: { command: 'afplay /System/Library/Sounds/Glass.aiff' },\n\t\tinterrupt: {\n\t\t\tdelay: 500,\n\t\t\tsequence: ['\\\\u001b', '{message}', '\\\\n'], // ESC + message + Enter\n\t\t},\n\t\talert: { format: 'color' },\n\t},\n\tdebounce: 2000,\n\tfileTracking: true,\n};\n```\n\n### JSON Configuration\n\nCreate `llm-whip.config.json`:\n\n```json\n{\n  \"$schema\": \"https://raw.githubusercontent.com/bewinxed/llm-whip/main/schema.json\",\n  \"patterns\": [\n    {\n      \"name\": \"todo\",\n      \"pattern\": \"TODO\",\n      \"severity\": \"high\",\n      \"reactions\": [\"sound\", \"alert\", \"interrupt\"],\n      \"message\": \"TODO comment detected\",\n      \"interruptMessage\": \"TODO comments should be completed before submitting code.\"\n    }\n  ],\n  \"reactions\": {\n    \"sound\": true,\n    \"alert\": { \"format\": \"color\" },\n    \"interrupt\": {\n      \"delay\": 500,\n      \"sequence\": [\"\\\\u001b\", \"{message}\", \"\\\\n\"]\n    }\n  }\n}\n```\n\n## Default Patterns\n\nPatterns use **JavaScript regex syntax** and are case-insensitive by default:\n\n| Pattern           | Regex                                  | Example Match                        |\n| ----------------- | -------------------------------------- | ------------------------------------ |\n| `todo`            | `TODO`                                 | `// TODO: implement this`            |\n| `placeholder`     | `placeholder\\|stub`                    | `// placeholder implementation`      |\n| `not-implemented` | `not implemented\\|NotImplementedError` | `throw new Error(\"not implemented\")` |\n| `important-thing` | `The important thing is`               | `The important thing is to...`       |\n\n**Custom Pattern Examples:**\n\n```typescript\n{\n  name: \"fixme\",\n  pattern: \"FIXME\\|BUG\\|HACK\",  // Matches FIXME, BUG, or HACK\n  severity: \"high\"\n},\n{\n  name: \"console-log\",\n  pattern: \"console\\\\.(log\\|debug)\",  // Matches console.log or console.debug\n  severity: \"low\"\n}\n```\n\n## Keyboard Interrupts\n\nThe `--interrupt` flag enables keyboard interrupts that send detailed warnings to the active window when patterns are detected:\n\n```bash\n# Enable keyboard interrupts\nllm-whip ./src --interrupt\n```\n\nWhen a pattern is detected, LLM Whip will:\n\n1. Press ESC to clear any current input\n2. Type a warning message to the active window\n3. Press Enter to send the message\n4. The message includes:\n    - Pattern type and custom message\n    - File path and line number\n    - Timestamp\n\n**Note:** The `--interrupt` flag will automatically add keyboard interrupts to all patterns, even if they don't have \"interrupt\" in their reactions array in the config file.\n\nEach pattern can have a custom `interruptMessage` that gets sent:\n\n```typescript\n{\n  name: \"todo\",\n  pattern: \"TODO\",\n  reactions: [\"interrupt\"],\n  interruptMessage: \"TODO comments should be completed before submitting code. Please implement the actual functionality instead of leaving placeholder comments.\"\n}\n```\n\n## Sound Alerts\n\nThe `--sound` flag enables cross-platform sound alerts:\n\n```bash\n# Enable sound alerts\nllm-whip ./src --sound\n```\n\nDefault sounds by platform:\n- **macOS**: Glass.aiff (fallback: Ping.aiff)\n- **Windows**: Windows Critical Stop.wav (fallback: console beep)\n- **Linux**: alarm-clock-elapsed.oga (fallback: bell.oga)\n\n## Monitoring LLM Conversations\n\nLLM Whip can monitor LLM conversation outputs by watching log files. This helps detect anti-cheat patterns in both your code and the LLM's responses.\n\n### Method 1: Using `tee` to clone output\n\nWhen using Claude Code CLI or other LLM tools, pipe the output to a file that LLM Whip monitors:\n\n```bash\n# Terminal 1: Start LLM Whip monitoring\nllm-whip ./project ./logs\n\n# Terminal 2: Run Claude Code with output logging\nclaude-code ./project 2\u003e\u00261 | tee logs/claude-session.log\n```\n\n### Method 2: Direct file monitoring\n\nCreate a log file and have your LLM tool write to it:\n\n```bash\n# Start monitoring the logs directory\nllm-whip ./src ./logs\n\n# Your LLM tool outputs to logs/conversation.txt\n# LLM Whip will detect patterns in real-time\n```\n\n### Method 3: Script wrapper\n\nCreate a wrapper script that automatically logs and monitors:\n\n```bash\n#!/bin/bash\n# llm-monitor.sh\n\n# Create logs directory\nmkdir -p ./logs\n\n# Start LLM Whip in background\nllm-whip ./src ./logs \u0026\nWHIP_PID=$!\n\n# Run your LLM tool with logging\nclaude-code \"$@\" 2\u003e\u00261 | tee logs/session-$(date +%Y%m%d-%H%M%S).log\n\n# Clean up\nkill $WHIP_PID 2\u003e/dev/null\n```\n\nThen use it like: `./llm-monitor.sh ./my-project`\n\n## Advanced Usage\n\n### Baseline Tracking\n\nOnly alert on new patterns:\n\n```bash\nllm-whip audit ./src \u003e /dev/null\nllm-whip watch ./src\n```\n\n### Export Formats\n\n```bash\n# JSON export\nllm-whip audit ./src --format=json \u003e issues.json\n\n# CSV export\nllm-whip audit ./src --format=csv \u003e issues.csv\n```\n\n### Configuration Priority\n\n1. Local `llm-whip.config.ts` (current directory)\n2. Custom path via `--config=path`\n3. Built-in defaults\n\n## Development\n\n```bash\nbun install\nbun test\nbun run build\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbewinxed%2Fllm-whip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbewinxed%2Fllm-whip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbewinxed%2Fllm-whip/lists"}