genie_cli

Genie CLI

Genie CLI is a command-line tool that brings Test Driven Development (TDD) principles to life by integrating with a large language model (LLM) through the ruby_llm library. It provides an interactive session where you can ask the AI assistant to write tests, implement code, and manage your codebase—all while enforcing a strict TDD workflow.

Features

• Interactive REPL-style session powered by OpenAI (or any provider supported by ruby_llm).
• Built-in tools for common file operations:
  • ListFiles: List and filter files in your project directory.
  • ReadFile: Read the contents of files.
  • WriteFile: Create or overwrite files.
  • InsertIntoFile: Insert content at a specific marker in a file.
  • AppendToFile: Append content to existing files.
  • RunTests: Run your test suite and capture results.
  • TakeANote: Write notes without affecting your source files.
  • AskForHelp: Request guidance or explanations from the AI.
• Enforces Genie workflow: tests first, implementation second.
• Restricts file operations to your project directory for safety.

Installation

• Install the gem:

  gem install genie_cli
  

• Set your OpenAI API key (or other LLM provider keys) in your environment:

  export OPENAI_API_KEY="your_api_key_here"
  

  dotenv is also supported:

  # .env
  OPENAI_API_KEY="your_api_key_here"
  

Usage

Start a Genie session by running the genie command from the root of your project:

genie "initial prompt or command"

If you are using Bundler, you can run:

bundle exec genie "initial prompt or command"

• If you provide an initial prompt, the assistant will immediately respond. Otherwise, you'll enter an interactive prompt where you can type your questions or commands.
• To quit the session, type q, quit, done, or exit.

Example session:

$ genie
Starting a new session with:
 base_path: /Users/you/projects/genie_cli

 > "Create a failing test for a Calculator#add method"

# (AI writes a test file)

 > "Implement Calculator#add to pass the test"

# (AI writes the implementation)

 > "Run the test suite"

# (AI invokes `rake test` and reports results)

 > "exit"
Exiting...
Total Conversation Tokens: 1234

Logging

The output of genie to the terminal includes "essential" output, but not all output. To aid in debugging, the full RubyLLM debug log is saved to ruby_llm.log. This can be useful for auditing what's happened during a session in great detail.

Configuration

Configuration is available via a genie.yml.

Testing

This project includes a comprehensive test suite. Run all tests with:

bundle exec rake test

Contributing

Contributions are welcome! Please fork the repository and open pull requests for new features or bug fixes. Make sure to follow the Genie workflow and include tests for new functionality.

License

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

Why "Genie"?

Kent Beck has been using this term to describe LLMs, especially coding agents, because it grants your wishes, but rarely in the way you actually wanted it to. It's a great idea, so I'm shamelessly stealing it.

The Lamp

From https://www.asciiart.website/index.php?art=movies%2Faladdin