vibetools is a suite of tools used to compile programs using LLMs. Currently programs are specified as design documents. The tools compile these design documents into Python (3.12) code using Grok. Within reason it is not difficult to extend the tools to use other LLMs (ChatGPT, Claude, etc.) and other target languages.

1. Download the tools from GitHub
2. Generate a Grok API key:
   export XAI_API_KEY="your_key_here"
   Save this in a script and source it in your shell.
3. Add the tools and your current directory to your PATH:

   export PATH=$PATH:`pwd`:.

4. Test that it works:

   vibecl.py --description "write a program to calculate the Nth fibonacci number. N is provided on the command line"

   If you see a program written in Python that looks like it would actually calculate the fibonacci number for an input passed on the command line, then you are ready to start using the tools.

From here you can compile full design documents with vibemake, grow programs with vibeenhance, or debug them with vibedebug. For serious applications, start by writing good design documents.

The "source code" that vibetools uses is design documents. These are plain text files using a few keywords. A single design document describes an entire application (or library) as a tree of modules. Circular dependencies between modules are not supported.

Keywords (must appear at the start of a line):

• Module: Human-readable name (one line)
• Short: short_case_computer_name
• Uses: short_name1, short_name2, short_name3 (optional)

After the keywords comes free-form English describing what the module does, optionally how it should do it, and what functions/classes it exports.

Example Design Documents

• riscv32sim.txt - A RISC-V rv32i intepreter. This will intepret (not compile) RV32i assembly. A simple OS is in the intepreter to print numbers and strings and such.
• psh.txt - A Python command-line shell. This example illustrates where the module is too large. The LLM basically gives up and provides a working, but incomplete answer. You can use vibecl twice to get it to work.
• ls.txt - AI-generated ls implementation (via vibedesign). Note this example will not compile "clean". You will need to use vibedebug to get it to execute, and then even some semantic correction to get it to fully work right.

A good design document is key to a positive experience with vibetools. The design document is the source code. This is a mental shift that developers must make to use vibetools effectively. The tools translate design documents into an application (aka a "binary"). This "binary" happens to be Python code, but it won't always be, and it doesn't have to be now. There will be a temptation for a developer to edit the resulting Python, because that is how traditional vibe coding works, and well, it is just Python code. But resist this urge.

If the code does not compile cleanly and/or correctly using vibetools then don't edit the Python. Fix the design document. There are few different common fixes you will end up doing:

• Be explicit / more correct on the requirements of a module. Most bugs in the generated code come down to fuzzy or incorrectly written specifications.
• Provide warnings / implementation hints about what not to do. Some times the LLM really wants to implement something a certain way and that is not what you want. That should be fixed by explicitly stating (in English) not to implement something a certain way.
• Be explicit about exports. Often times you will want the public symbols of a module to have precise names. Put that requirement in the design document.
• Correct the module hierarchy. It is quite common for complex applications to not specifiy the module hierarchy correctly. I.e. you forgot a dependency. If this happens the LLM will "make up" reference or duplicate code and this is not what you want. The solution is to correctly fix describe the module dependencies.
• Don't make modules do too much. The LLM will "give up" and punt if you ask it to make a module that does too much. You can see an examples of this with psh.txt. This will often only partially compile and you have to run vibeehance or vibecl (with the first pass result as input) to get the completed code. The real solution isn't to use vibecl twice or vibeenhance, but instead to break the design up into smaller modules.

There are a class of bugs that the design document cannot fix (yet). Sometimes the LLM does not understand the intermediate language well enough. It will just generate bad Python 3.12 code. This is a work in progress and we're working on ideas to fix this. For now though you can use the automated debugger (in most cases) to fix these issues

Automated debugger? Yes, the vibedesign tool is here to help you. It can iteratively compile / debug your code until it compiles correctly. This can fix most issues with the LLM not understanding the target language well. It can also (usually) hint at where design documents are not well specified. Resist the urge to fix and be done with the vibedebug tool. While you can get a working application this way, I would strongly encourage you to edit the design document with any information the vibedebug tool uncovers about the design. You wouldn't hack the binary at the end of your build process would you? Same for hacking the resulting Python code. Put the fixes in the design document!

vibecl is the core compiler that turns a single module description (or ad-hoc prompt) into working code.

usage: vibecl.py [-h] --description DESCRIPTION [--context CONTEXT] [--files [FILES ...]] 
                 [--model MODEL] [--complete COMPLETE] [--language LANGUAGE] [--revise REVISE]

Options:
  --description DESCRIPTION    Description or path to .txt module file
  --context CONTEXT           Extra context to give the model
  --files [FILES ...]         Include contents of these files as context
  --model MODEL               Default: grok-4-1-fast-non-reasoning
  --language LANGUAGE         Default: Python
  --revise REVISE             Revise existing file instead of generating from scratch
          

Example commands:

vibecl.py --description "Generate a program to quiz the user on two-digit multiplication..." > math_quiz.py

vibecl.py --revise math_quiz.py --description "Add division problems" > math_quiz_v2.py

vibecl.py --description psh.txt
          

vibemake parses design documents that contain multiple modules into traditional Makefile and then invokes 'make' on that file. The resulting execution will invoke vibecl.

usage: vibemake.py [-h] [--model MODEL] design_file

Generate module files and Makefile from a design document.

positional arguments:
  design_file    Path to the design document file.

options:
  -h, --help     show this help message and exit
  --model MODEL  Grok model to use for code generation (passed to vibecl.py).
       

Note that the Makefile and components of the design file will end up in a subdirectory 'build'.

You can, but do not need to, invoke vibemake on design documents that contain only one module.

This tool uses the LLM to get you started with writing a design document. Think of it as suppose you want to design a traditional program (or part of a program) that would be a few thousand lines of code. This tool will take a short description of what that code does and expand it to a design document.

usage: vibedesign.py [-h] --description DESCRIPTION [--language LANGUAGE] [--context CONTEXT]
                     [--files [FILES ...]] [--model MODEL]

Generate or refine design documents using the Grok API

options:
  -h, --help            show this help message and exit
  --description DESCRIPTION
                        Description of the program to generate
  --language LANGUAGE   Assume the design document is for a program written in a given language.
  --context CONTEXT     Additional textual context to provide to the model.
  --files [FILES ...]   Paths to files whose contents to include as context (can specify multiple).
  --model MODEL         The Grok model to use (default: grok-4-1-fast-reasoning)
          

Examples

  vibedesign.py --description "this application should use NOAA to report the weather at the current location to the user."

  vibedesign.py --files my_lib.py --description "This application should use the my_lib library
  to open up database files and count the number of unique customer records."

Note the resulting design documents will vary quite radically in usability and correctly inferring what you want. You should most definitely look at them and make necessary edits before passing them to vibemake.

vibedebug is a (semi)automated debugger. It can be used to get broken code to "compile" (not cause a Python error) and it can fix semantic problems if you describe what those issues are to it.

usage: vibedebug.py [-h] --files FILES [FILES ...] [--input_files FILES [FILES ...]
                    --command COMMAND --input INPUT [--max_iterations MAX_ITERATIONS]
                    [--model MODEL] [--issue ISSUE]

Debug a program using Grok API.

options:
  -h, --help            show this help message and exit
  --files FILES [FILES ...]
                        List of files to include for debugging
  --input_files FILES [FILES ...]
                        Input files the program uses
  --command COMMAND     Command to execute the program (as string)
  --input INPUT         Input string to pipe to stdin
  --max_iterations MAX_ITERATIONS
                        Maximum number of debugging iterations
  --model MODEL         Model to use for API calls
  --issue ISSUE         Describe the problem and pass that to grok, don't execute

The best way to think of vibedebug is there are two modes: full automatic, which is useful for getting incorrectly written Python code to at least be syntactically correct; and semi automatic, where you need to describe what the issue is with the code and it will attempt to fix it. Here is example of each:

Fully automatic:

vibedebug.py --files *.py --command "python3 mycode.py [my_program_args]" --input "" --max_iterations 10

This will execute your program, capturing stdout/stderr, and send all of the python files in the current directory to the LLM, asking it to fix the issue. The LLM sends back new files and the process repeats until the code exits successfully (returns 0).

Semi automatic:

vibedebug.py --files *.py --command "python3 mycode.py [my_program_args]" --input "" --max_iterations 1 --issue "The program does not compute the sum"

This will not execute your program but instead send the code to the LLM along with the issue you describe and ask it to fix it. The resulting code sent back updates the files in place.

Warning: In both cases the files are updated in place. There are situations where the LLM server will send back corrupted answers and this can corrupt your source files. It is strongly recommended you make a backup of the files before using this tool.

It is recommended that once you learn what the issues are in the code that you make the necessary changes to the design document so they do not occur again. This can be tricky. If it's just Python 3.12 misunderstandings, well there's not always much you can do (yet). vibedebug will iterate through them and that may just have to be part of the build process (yuck). For semantic issues and module inclusion mismatches these are usually fixable by editing the design document.

vibeenhance will automatically add new features to code or suggest features the LLM thinks would be useful.

usage: vibeenhance.py [-h] --files FILES [FILES ...] [--max_iterations MAX_ITERATIONS] [--model MODEL]
                      [--enhance ENHANCE] [--suggest_only SUGGEST_ONLY]

Enhance a program using Grok API.

options:
  -h, --help            show this help message and exit
  --files FILES [FILES ...]
                        List of files to include for debugging
  --max_iterations MAX_ITERATIONS
                        Maximum number of iterations
  --model MODEL         Model to use for API calls
  --enhance ENHANCE     Describe how the code should be changed.
  --suggest_only SUGGEST_ONLY
                        Suggest changes only, do not actually make them.

Example usage

Have the LLM add new features automatically (3 times):

  vibeenhance.py --files *.py --max_iterations 3

Have the LLM just suggest new features to you:

  vibeenhance.py --files *.py --max_iterations 1 --suggest_only True

Have the LLM add a new feature that you request:

  vibeenhance.py --files *.py --max_iterations 1 --enhance "make program support..."

As with vibedebug, the files are updated in place. Make a backup prior to use. Also note that while you can set --max_iterations to anything you like you'll probably not be very happy with the results. You can look at the suggestions the LLM makes for an example of where it may go, but generally speaking it'll very quickly diverge from your vision quickly.

It is recommended that take the features added by vibeenhance and specify them back in the original design document. The goal is to compile design documents in a (largely) repeatable manner. If you don't put the changes back in the document they will be lost the next time you build from scratch.

vibereverse will generate a design document from existing code.

usage: vibereverse.py [-h] --files FILES [FILES ...] [--model MODEL] [--language LANGUAGE]

Reverse engineer a design document from code.

options:
  -h, --help            show this help message and exit
  --files FILES [FILES ...]
                        List of source files
  --model MODEL         Model to use for API calls
  --language LANGUAGE   Assume the design document is for a program written in a given language.

Examples

Reverse engineer the vibecl compiler into a design document:

  vibereverse.py --files vibecl.py > vibegen.txt

And for fun, compile the design document back into vibecl:

  vibecl.py --description vibegen.txt

Note the files need not be the same language as the target for the vibetools. YMMV

vibebundle will collect a bunch of individual source files and ask the LLM to merge them into one source file. This is often useful to do when the code is all working and you want something distribute

usage: vibebundle.py [-h] --files FILES [FILES ...] [--model MODEL]

Bundle multiple source files into one.

options:
  -h, --help            show this help message and exit
  --files FILES [FILES ...]
                        List of source files
  --model MODEL         Model to use for API calls