Vibe Compiler (vibec) A self-compiling tool that transforms prompt stacks into code and tests using LLM generation. Overview vibec is a unique compiler that processes markdown-based prompt stacks to generate code, tests, and documentation. It can compile itself through a bootstrap process, evolving its own implementation (bin/vibec.js) across numbered stages. The tool supports both static (.md) and dynamic (.js) plugins, maintains staged outputs in output/stacks/ for Git history, and aggregates the latest runtime version in output/current/ using a "Last-Wins" merge strategy. Project Structure vibec/ ├── bin/ # Initial implementation │ ├── vibec.js # Core compiler script │ └── test.sh # Test runner ├── bootstrap/ # Bootstrap documentation ├── stacks/ # Prompt stacks │ ├── core/ # Core functionality │ │ ├── 001_add_logging.md │ │ ├── 002_add_plugins.md │ │ ├── 003_add_cli.md │ │ ├── 004_add_config.md │ │ ├── 005_add_iterations.md │ │ ├── 006_add_dynamic_plugins.md │ │ └── plugins/ # Core plugins │ └── tests/ # Test generation ├── output/ # Generated artifacts │ ├── bootstrap/ # Bootstrap outputs │ │ ├── bin/ # Bootstrap compiler │ │ │ └── vibec.js │ │ ├── bootstrap.js # Bootstrap script │ │ └── test.sh # Bootstrap test script │ ├── current/ # Latest merged runtime version │ │ ├── bin/ # Current compiler │ │ │ └── vibec.js │ │ ├── bootstrap.js # Current bootstrap script │ │ ├── test.js # Current test suite │ │ └── test.sh # Current test script │ └── stacks/ # Staged stack outputs │ ├── core/ # Core stack stages │ │ ├── 001_add_logging/ │ │ │ └── bin/ │ │ │ └── vibec.js │ │ ├── 002_add_plugins/ │ │ │ └── bin/ │ │ │ └── vibec.js │ │ ├── 003_add_cli/ │ │ │ └── bin/ │ │ │ └── vibec.js │ │ ├── 004_add_config/ │ │ │ └── bin/ │ │ │ └── vibec.js │ │ ├── 005_add_iterations/ │ │ │ └── bin/ │ │ │ └── vibec.js │ │ ├── 006_add_dynamic_plugins/ │ │ │ └── bin/ │ │ │ └── vibec.js │ └── tests/ # Test stack stages │ ├── 001_basic_tests/ │ │ ├── test.js │ │ └── test.sh │ ├── 002_feature_tests/ │ │ └── test.js │ ├── 003_cli_tests/ │ │ └── test.js │ └── 004_config_tests/ │ └── test.js ├── vibec.json # Configuration file └── package.json # Node dependencies Architecture vibec employs a progressive bootstrapping process: Begins with the initial bin/vibec.js implementation Processes numbered stages sequentially (001, 002, etc.) Updates vibec.js when generated in a stage, using the new version for subsequent stages Creates a self-improving cycle where the compiler evolves during compilation Getting Started Installation Install globally: npm install -g vibec Or use via npx: npx vibec --version Set your LLM API key: export VIBEC_API_KEY=your_api_key_here Usage Run with custom options: npx vibec --stacks=core,tests --test-cmd="npm test" --retries=2 --iterations=3 --output=output CLI options: --workdir=<dir>: Working directory (default: .) --stacks=<stack1,stack2,...>: Stacks to process (default: core) --dry-run: Simulate without modifications (default: false) --start=<number>: Start with specific stage number (default: none) --end=<number>: End with specific stage number (default: none) --api-url=<url>: LLM API endpoint (default: https://openrouter.ai/api/v1) --api-model=<model>: LLM model (default: anthropic/claude-3.7-sonnet) --test-cmd=<command>: Test command to run (default: none) --retries=<number>: Retry attempts for API calls (≥ 0, default: 0) --iterations=<number>: Number of times to retry a stage on test failure (> 0, default: 2) --plugin-timeout=<ms>: Timeout for JS plugins in milliseconds (default: 5000) --output=<dir>: Output directory (default: output) --help: Display usage information --version: Show version (e.g., vibec v1.0.0) Configuration Configure via vibec.json: { "workdir": ".", "stacks": ["core", "tests"], "dryRun": false, "start": null, "end": null, "testCmd": "npm test", "retries": 2, "iterations": 3, "pluginTimeout": 5000, "apiUrl": "https://openrouter.ai/api/v1", "apiModel": "anthropic/claude-3.7-sonnet", "output": "output" } Option precedence: CLI > Environment Variables > vibec.json > Defaults Validation: retries: Must be non-negative (≥ 0) iterations: Must be positive (> 0) pluginTimeout: Must be positive (> 0) Malformed JSON in vibec.json triggers an error log and falls back to defaults Environment Variables VIBEC_WORKDIR: Working directory path. VIBEC_STACKS: Comma-separated stacks (e.g., core,tests) VIBEC_DRY_RUN: true/false. VIBEC_START: Numeric stage value. VIBEC_END: Numeric stage value. VIBEC_OUTPUT: Output directory. VIBEC_TEST_CMD: Test command VIBEC_RETRIES: Retry count for API calls VIBEC_ITERATIONS: Number of times to retry a stage on test failure VIBEC_PLUGIN_TIMEOUT: Plugin timeout (ms) VIBEC_API_URL: LLM API endpoint VIBEC_API_KEY: LLM API key (recommended over config) VIBEC_API_MODEL: LLM model VIBEC_DEBUG: Enable debug logging (1 to enable) LLM Integration Compatible with OpenAI-style APIs. Configure via VIBEC_API_URL and VIBEC_API_KEY. Prompt Structure Prompts use markdown: # Component Name Description of the generation task. ## Context: file1.js, file2.js ## Output: path/to/output.js ## Context:: Reference files for context ## Output:: Specify output file paths (multiple allowed) Plugin System Static Plugins (.md) Stored in stacks/<stack>/plugins/ Appended to prompts in alphabetical order Used for adding reusable context or constraints to prompts Dynamic Plugins (.js) JavaScript modules in stacks/<stack>/plugins/ Executed as async functions in alphabetical order with configurable timeout Receive a context object with access to: { config, // vibec.json contents stack, // Current stack name promptNumber, // Current prompt number promptContent, // Content of the current prompt workingDir, // Path to output/current testCmd, // Test command testResult // Test execution result } Plugin errors are logged and skipped without halting execution Iteration System The iteration system allows automatic refinement of generated code: When a test fails, the test output is captured The prompt is re-run with test output included Process repeats up to iterations times (default: 2) If all iterations fail, the process exits with an error This enables self-healing code generation that can fix test failures automatically. Development Adding Prompts Create a new numbered file (e.g., stacks/core/005_new_feature.md) Use NNN_name.md naming convention Specify outputs with ## Output: Testing Tests in stacks/tests/ generate: test.sh: Validates vibec.js and runs test.js test.js: Uses tape for unit tests (Node builtins only) Tutorial: Building a Simple Pong Game This tutorial is based on a fully-functional example project available at: github.com/Strawberry-Computer/vibe-pong 1. Initialize Project mkdir pong-game && cd pong-game mkdir -p stacks/core/plugins output 2. Set Up Coding Style Plugin Create a coding style plugin that forces the LLM to mark its reasoning in the generated code. This clever trick helps us trace which parts of the prompt produced specific code: - Make it clear why any given code is written by adding a comment with relevant prompt snippet, like: ``` // PROMPT: <relevant prompt snippet> ``` - Don't use any other comments. 3. Define Initial Prompt # Pong Game Initial Setup Generate a simple Pong game using HTML, CSS, and JavaScript: - Use `<canvas width="800" height="400" id="pongCanvas">` - Draw a white paddle (10px wide, 100px high) at the left side of the canvas, movable up/down with arrow keys. - Draw a white ball (10px radius) starting at canvas center, moving diagonally with constant speed. - Bounce the ball off the top and side walls; reset to center if it hits the bottom (misses paddle). - Detect paddle collision to bounce the ball back up. - Use requestAnimationFrame for smooth animation. ## Output: index.html ## Output: styles.css ## Output: game.js 4. Configure { "stacks": ["core"], "output": "output" } 5. Compile export VIBEC_API_KEY=your_api_key_here npx vibec 6. Test cd output/current python3 -m http.server 8000 Visit http://localhost:8000. 7. Add Scoring # Add Scoring to Pong Enhance the Pong game by adding score display ## Context: index.html, game.js ## Output: index.html ## Output: game.js Run npx vibec again to update the game. 8. Add AI Player # Add AI Player to Pong Add the computer player which moves the paddle automatically. Make sure that at this point there are 2 paddles: one for the user and one for the computer. ## Context: index.html, game.js ## Output: game.js Run npx vibec one more time to complete the game with an AI opponent. 7. Debug Use VIBEC_DEBUG=1 npx vibec for detailed logs. Troubleshooting API Key Missing: Set VIBEC_API_KEY No Output: Verify ## Output: in prompts Command Not Found: Use npx vibec or install globally Test Failures: Check test output for details Plugin Timeout: Increase --plugin-timeout if needed
