Buggernaut 1.0.3

Buggernaut

Link to the Swedish README file: README.md

Buggernaut is a CLI tool that generates C# exercises with built-in bugs through an LLM provider of your choice.
The idea is simple: open a file, find the bug, run the tests, get better at programming.

The project is designed to give junior developers a practical way to train bug hunting and bug fixing, while building a stronger understanding of programming concepts without leaving their own development environment.

Inspired by ThePrimeagen's Kata-Machine. Thanks to Marcus Loof for ideas and feedback.

What is this?

You run a command. Buggernaut asks an AI for a C# exercise, writes a .cs file with an intentional bug, and adds a matching test file. Your task is to find and fix the bug until the tests are green.

No browser tabs. No sign-up. Everything happens in your editor.

Quick demo

Contents

• Prerequisites
• Quick start
• Daily usage
• Configuration
• Run tests
• Common issues
• Want to contribute?
• Contact

Prerequisites

• .NET 10 SDK
• An API key for any provider (for example Gemini, OpenAI, Anthropic, Mistral)

Ollama works without an API key, but requires a local server.

Want to try it without an API key first? Use --dry-run.

Quick start

Run all commands from Buggernaut/ unless stated otherwise.

1) Install the tool

cd Buggernaut
dotnet tool restore

2) Save API key (one-time setup)

Run in tools/Buggernaut.Generator/:

cd tools/Buggernaut.Generator
dotnet user-secrets set "LLM:Gemini:ApiKey" "your-key"

The key is stored locally on your machine and is never committed to Git.

Using another provider? Just replace Gemini:

dotnet user-secrets set "LLM:OpenAI:ApiKey" "your-key"
dotnet user-secrets set "LLM:Anthropic:ApiKey" "your-key"
dotnet user-secrets set "LLM:Mistral:ApiKey" "your-key"
dotnet user-secrets set "LLM:OpenRouter:ApiKey" "your-key"

Need help finding your provider API key?

• Gemini: https://aistudio.google.com/app/apikey
• OpenAI: https://platform.openai.com/api-keys
• Anthropic: https://console.anthropic.com/settings/keys
• Mistral: https://console.mistral.ai/
• OpenRouter: https://openrouter.ai/settings/keys

3) Generate your first exercise

cd Buggernaut
dotnet buggernaut generate

A new .cs file appears in src/Buggernaut.Exercises/. Open it, find the bug, and fix it.

Daily usage

dotnet buggernaut generate                         # generate a new exercise
dotnet buggernaut generate -c LINQ -d Hard         # choose category and difficulty
dotnet buggernaut generate --dry-run               # test without API key

dotnet test exercises.slnf                         # run your exercise tests

dotnet buggernaut hint <ClassName>                 # get a hint when stuck
dotnet buggernaut explain <ClassName>              # get explanation when tests pass

Tip: See all flags and categories with:

dotnet buggernaut --help

Configuration

Change LLM provider

Open tools/Buggernaut.Generator/appsettings.json and change "Provider":

{
  "LLM": {
    "Provider": "Gemini"
  }
}

Available providers: Gemini, OpenAI, Anthropic, Mistral, Ollama, OpenRouter.

Missing a provider? Open an issue and suggest it.

Want to run fully local without internet? Set up Ollama and use:

{
  "LLM": {
    "Provider": "Ollama",
    "Ollama": {
      "BaseUrl": "http://localhost:11434/v1",
      "Model": "llama3"
    }
  }
}

Optional: set model per provider

{
  "LLM": {
    "Provider": "Gemini",
    "Gemini": {
      "Model": "gemini-2.5-flash"
    },
    "OpenAI": {
      "Model": "gpt-4o-mini"
    },
    "Anthropic": {
      "Model": "claude-3-5-haiku-latest"
    },
    "Mistral": {
      "Model": "mistral-small"
    },
    "Ollama": {
      "BaseUrl": "http://localhost:11434/v1",
      "Model": "llama3"
    }
  }
}

Run tests

Common issues

dotnet buggernaut is not found

• Run dotnet tool restore in Buggernaut/.

API key is not found

• Confirm user-secrets was set in tools/Buggernaut.Generator/.

Wrong provider or model is used

• Check tools/Buggernaut.Generator/appsettings.json.

Want to contribute?

Great! Read CONTRIBUTING.md for branch, commit, and pull request guidelines. No pressure, no stress - we learn together.

Contact

Want to reach me? You can find contact details on GitHub, or send an email.