codekoala 0.0.1

Local-first LLM-powered code review and commit assistant

🐨 CodeKoala

Your Friendly, Local Code Reviewer (who prefers a nap!)

📌 Overview

CodeKoala is your lazy (but effective) local-first, LLM-powered code review tool that gently analyses Git changes and provides AI-driven feedback on code quality, best practices, and design principles. Perfect for the developer who wants to stay comfy without missing important code improvements. The tool is modular, supporting both local execution and future API-based LLMs.

🐨 From Gum Trees to Git Trees – Reviewing Your Commits with Care!

✨ Features

• 🧠 LLM-Powered Reviews – Get feedback on your commits without the stress of manual reviews.
• 🔍 Git Integration – Automatically ponders over your git diff changes. No need to lift a finger.
• 🚀 Runs Locally – Your code stays close, no external calls needed (privacy first, naps second).
• 🛠 Best Practice Checks – Catches code smells, anti-patterns, and design flaws (so you don't have to).
• 🗒️ Conventional Commits – Automatically generate commit messages that follow the Conventional Commits spec.

🚀 Installation

Pick the option that fits your workflow—each installs the codekoala CLI so you can call it from any repository.

Install from a GitHub Release (recommended)

1. Download the latest codekoala-*.whl from the Releases page.
2. Install it with pip:

   pip install path/to/codekoala-<version>-py3-none-any.whl
   

Requirements

• Python 3.10 or newer
• Ollama installed locally
• Pull the recommended model:

  ollama pull mistral-nemo:12b
  

  If you prefer a different model, set it after install with codekoala config --model <name>.

🛠 Usage

First-Time Setup

• Verify Ollama is running:

  ollama list
  

• Configure your preferred model (default is mistral-nemo:12b):

  codekoala config --model mistral-nemo:12b
  

Available Commands:

• review_code

  Review code changes before committing, comparing them with a specific branch or reviewing staged changes.

  Example:

  codekoala review_code --branch main --staged
  

• generate-message

  Automatically generate a commit message following the Conventional Commits specification based on your Git changes.

  Example:

  codekoala generate-message --ticket 54321 --context "Refines onboarding flow" --context-file docs/release-notes.md
  

  This analyses staged changes, blends in any optional context, and suggests a structured commit message. Use --prompt-only to copy the prompt instead of calling the local model directly.

  Helpful flags

  • --ticket: Provide a ticket number upfront (e.g. --ticket 54321).
  • --context: Add free-form context; repeat for multiple notes.
  • --context-file: Merge the contents of supporting files into the prompt.
  • --prompt-only: Copy the full prompt (diff + context) to your clipboard.

• config

  Configure CodeKoala settings, such as selecting the LLM model to use.

  Example to set the model:

  codekoala config --model mistral-nemo:12b
  

  Example to show current configuration:

  codekoala config --show
  

Example Workflow

1. Check your own code before committing
   You can review the changes you've staged for commit using:

   codekoala review_code --staged
   

   Or, if you want to check all changes (not just staged ones), run:

   codekoala review_code
   

2. Generate a commit message based on changes Instead of manually writing a commit message, let CodeKoala handle it:

   codekoala generate-message --ticket 54321
   

   This ensures consistency and adherence to Conventional Commits.

3. Review PRs or features compared to another branch You can use CodeKoala to review the differences between your current branch and another branch, such as develop, to ensure your code aligns with the main branch before merging:

   codekoala review_code --branch develop
   

   This command compares your current branch to develop and provides suggestions for any detected changes.

🐨 CodeKoala: Keeping Your Code Cuddly, Not Clunky!

🔁 Release Workflow

Releases are automated through GitHub Actions whenever you push a tag that matches v*.*.*.

1. Make sure the version in pyproject.toml is up to date.
2. Create a tag and push it, e.g.:

   git tag v0.2.0
   git push origin v0.2.0
   

3. The release workflow will:
   • lint the codebase with Flake8,
   • build and upload wheel/sdist artifacts,
   • create a GitHub Release (shows up in the repository sidebar automatically).