commizard 0.4.3
The commit writing Wizard Assistant
Requires Python: >=3.9
Keywords: AI assistant, Commit message helper, commit assistant, git

# CommiZard

<div align="center">

![CommiZard's banner](https://github.com/user-attachments/assets/a85f4ba5-f363-4c06-82b4-7e839ba49d75)
[![Python version](https://img.shields.io/badge/python-3.9+-blue.svg?logo=data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz48IS0tIFVwbG9hZGVkIHRvOiBTVkcgUmVwbywgd3d3LnN2Z3JlcG8uY29tLCBHZW5lcmF0b3I6IFNWRyBSZXBvIE1peGVyIFRvb2xzIC0tPgo8c3ZnIHdpZHRoPSI4MDBweCIgaGVpZ2h0PSI4MDBweCIgdmlld0JveD0iMCAwIDMyIDMyIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIj48ZGVmcz48bGluZWFyR3JhZGllbnQgaWQ9ImEiIHgxPSItMTMzLjI2OCIgeTE9Ii0yMDIuOTEiIHgyPSItMTMzLjE5OCIgeTI9Ii0yMDIuODQiIGdyYWRpZW50VHJhbnNmb3JtPSJ0cmFuc2xhdGUoMjUyNDMuMDYxIDM4NTE5LjE3KSBzY2FsZSgxODkuMzggMTg5LjgxKSIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIG9mZnNldD0iMCIgc3RvcC1jb2xvcj0iIzM4N2ViOCIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iIzM2Njk5NCIvPjwvbGluZWFyR3JhZGllbnQ+PGxpbmVhckdyYWRpZW50IGlkPSJiIiB4MT0iLTEzMy41NzUiIHkxPSItMjAzLjIwMyIgeDI9Ii0xMzMuNDk1IiB5Mj0iLTIwMy4xMzMiIGdyYWRpZW50VHJhbnNmb3JtPSJ0cmFuc2xhdGUoMjUzMDkuMDYxIDM4NTgzLjQyKSBzY2FsZSgxODkuMzggMTg5LjgxKSIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIG9mZnNldD0iMCIgc3RvcC1jb2xvcj0iI2ZmZTA1MiIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iI2ZmYzMzMSIvPjwvbGluZWFyR3JhZGllbnQ+PC9kZWZzPjx0aXRsZT5maWxlX3R5cGVfcHl0aG9uPC90aXRsZT48cGF0aCBkPSJNMTUuODg1LDIuMWMtNy4xLDAtNi42NTEsMy4wNy02LjY1MSwzLjA3VjguMzZoNi43NTJ2MUg2LjU0NVMyLDguOCwyLDE2LjAwNXM0LjAxMyw2LjkxMiw0LjAxMyw2LjkxMkg4LjMzVjE5LjU1NnMtLjEzLTQuMDEzLDMuOS00LjAxM2g2Ljc2MnMzLjc3Mi4wNiwzLjc3Mi0zLjY1MlY1LjhzLjU3Mi0zLjcxMi02Ljg0Mi0zLjcxMmgwWk0xMi4xNTMsNC4yMzdhMS4yMTQsMS4yMTQsMCwxLDEtMS4xODMsMS4yNDR2LS4wMmExLjIxNCwxLjIxNCwwLDAsMSwxLjIxNC0xLjIxNGgwWiIgc3R5bGU9ImZpbGw6dXJsKCNhKSIvPjxwYXRoIGQ9Ik0xNi4wODUsMjkuOTFjNy4xLDAsNi42NTEtMy4wOCw2LjY1MS0zLjA4VjIzLjY1SDE1Ljk4NXYtMWg5LjQ3UzMwLDIzLjE1OCwzMCwxNS45OTVzLTQuMDEzLTYuOTEyLTQuMDEzLTYuOTEySDIzLjY0VjEyLjRzLjEzLDQuMDEzLTMuOSw0LjAxM0gxMi45NzVTOS4yLDE2LjM1Niw5LjIsMjAuMDY4VjI2LjJzLS41NzIsMy43MTIsNi44NDIsMy43MTJoLjA0Wm0zLjczMi0yLjE0N0ExLjIxNCwxLjIxNCwwLDEsMSwyMSwyNi41MTl2LjAzYTEuMjE0LDEuMjE0LDAsMCwxLTEuMjE0LDEuMjE0aC4wM1oiIHN0eWxlPSJmaWxsOnVybCgjYikiLz48L3N2Zz4=)](https://www.python.org/downloads/)
[![GitHub License](https://img.shields.io/badge/license-MIT-yellow.svg?logo=data:image/svg+xml;base64,PHN2ZyBoZWlnaHQ9IjEwMjQiIHdpZHRoPSIxMDI0IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgogIDxwYXRoIGQ9Ik01MTQgMTkyYzM0LTEgNjEtMjggNjItNjIgMS0zNy0yOS02Ny02Ni02Ni0zNCAxLTYxIDI4LTYyIDYyLTEgMzcgMjkgNjcgNjYgNjZ6IG00NjQgMzg0aC0xOGwtMTI3LTI0NmMxOC0yIDM2LTkgNTItMTYgMjQtMTEgMjktNDMgMTEtNjJsLTEtMWMtMTEtMTEtMjgtMTUtNDMtOC0xNCA2LTM0IDEzLTUzIDEzLTU2IDAtODEtNjQtMjg3LTY0cy0yMzEgNjQtMjg3IDY0Yy0yMCAwLTM5LTYtNTMtMTMtMTUtNi0zMi0zLTQzIDhsLTEgMWMtMTggMTktMTMgNTAgMTEgNjIgMTYgOCAzNCAxNCA1MiAxNmwtMTI3IDI0NmgtMThjLTggMC0xNCA3LTEzIDE1IDExIDY0IDkyIDExMyAxOTEgMTEzczE4MC00OSAxOTEtMTEzYzEtOC01LTE1LTEzLTE1aC0xOGwtMTI3LTI0NWM4My03IDEyNy00OSAxOTEtNDl2NDg2Yy0zNSAwLTY0IDI5LTY0IDY0aC03MWMtMjggMC01NyAyOS01NyA2NGg1MTJjMC0zNS0yOS02NC03MS02NGgtNTdjMC0zNS0yOS02NC02NC02NHYtNDg2YzY0IDAgMTA4IDQyIDE5MSA0OWwtMTI3IDI0NWgtMThjLTggMC0xNCA3LTEzIDE1IDExIDY0IDkyIDExMyAxOTEgMTEzczE4MC00OSAxOTEtMTEzYzEtOC01LTE1LTEzLTE1eiBtLTY1OCAwaC0xOTJsOTYtMTgwIDk2IDE4MHogbTM4NCAwbDk2LTE4MCA5NiAxODBoLTE5MnoiIGZpbGw9IiNlMGUwZTAiLz4KPC9zdmc+Cg==)](LICENSE)
[![PyPI - Version](https://img.shields.io/pypi/v/commizard)](https://pypi.org/project/commizard/)
[![Coveralls](https://img.shields.io/coverallsCoverage/github/Chungzter/CommiZard?logo=coveralls)](https://coveralls.io/github/Chungzter/CommiZard)
[![CI check](https://github.com/Chungzter/CommiZard/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Chungzter/CommiZard/actions/workflows/ci.yml)

</div>

CommiZard is an interactive commit assistant, powered by AI! 🧙‍♂️
Generate, tweak, and copy commit messages with full control, right from a REPL.

## Features

- **REPL-style Interface**: Stay in an interactive session. Generate multiple
  commit variations without restarting.
- **Smart Generation**: Creates commit messages directly from your `git diff`.
- **Simple CLI**: Familiar, intuitive commands. No learning curve.
- **Flexible AI backends**: Easily swap models. Online model support planned!
- **Clipboard Magic**: Instantly copy generated messages to your system
  clipboard, ready to paste into `git commit`.
- **Zero Daemons**: No background processes, No Git hooks, no surprises.
- **Absolute Control**: Run it when *you* want, and you decide to commit,
  copy, tweak, or discard.

> [!WARNING]
>
> ⚠️ **Heads up!** CommiZard is in **alpha development**. Not all features are
> complete or stable yet.
>
> CommiZard is under active development. Expect bugs, crashes, and missing
> functionality.
> Please [open an issue](https://github.com/Chungzter/CommiZard/issues) if you
> encounter problems.
>
> Many features are still missing, since this project was released as a Minimum
> Viable Product (MVP). Stay tuned for new improvements!

## ⚙️ Installation

There are several ways to install this tool. Here are the most common
approaches:

1. The easiest way to get started is with [pip](https://pip.pypa.io/en/stable/):

```bash
pip install commizard
```

> [!TIP]
> Use `pipx` to install in an isolated environment and avoid dependency
> conflicts.

2. If you want the latest development version (bleeding-edge), clone the repo
   and install in editable mode:

```bash
git clone https://github.com/Chungzter/CommiZard
cd CommiZard
pip install -e .
```

You can update anytime with:

```bash
git pull && pip install -e .
```

3. You can also build from source yourself (e.g., with `build` or `hatchling`):

```bash
git clone https://github.com/Chungzter/CommiZard
cd CommiZard
python -m build
# or: hatchling build
pip install dist/commizard-*-py3-none-any.whl
```

## Usage

After installing CommiZard (See [Installation](#-installation)), you can launch
the interactive REPL in your Git repository:

```bash
commizard
```

You can also use -h or --help to see the available options.

Once launched, you’ll enter the interactive CommiZard terminal, where you can
use the following commands:

### Commands

|     Command      |                         Description                          |
|:----------------:|:------------------------------------------------------------:|
|      `help`      |       Show all commands or details for a specific one.       |
| `start <model>`  |        select a particular model to generate for you.        |
|      `list`      |  List all available Ollama models installed on your system.  |
|      `gen`       | Generate a new commit message based on the current Git diff. |
|       `cp`       |         Copy the generated output to your clipboard          |
|     `commit`     |             Directly commit the generated output             |
| `cls` or `clear` |                  Clear the terminal screen                   |
| `exit` or `quit` |                    Exit the REPL session.                    |

### Example Usage

![CommiZard on 7323da1a1847908 during alpha dev](https://github.com/user-attachments/assets/d8696e0a-ba6e-496d-b1f8-8d0247339cd4)

This is one of the very first times the program helped a user (me 😄) write a
meaningful commit message.

## 🧭 Alternatives & Similar Tools

When I started building CommiZard, I made sure to look around. Guess what?

> CommiZard isn’t the only wizard in town! 😊

If you’re exploring AI-powered commit tools, here are some other great projects
worth checking out:

- **[easycommit](https://github.com/blackironj/easycommit)**: written in Go,
  supports Ollama models out of the box.
- **[aicommit](https://github.com/suenot/aicommit)**: Packed with features —
  including a handy VS Code extension.
- **[AICommit2](https://github.com/tak-bro/aicommit2)**: The most complete FOSS
  option I've found

> *Why did I still follow through and build this?*
>
> Because I couldn’t find a tool that gave me both full user control and the
> little UX comforts I wanted.
>
> So yeah. I built CommiZard for *me*… and maybe for you too!

## Contributing

Contributions of all kinds are welcome.

If you’d like to get involved:

- Read the [CONTRIBUTING.md](CONTRIBUTING.md) guide for details on how to report
  bugs, suggest features, or open pull requests.
- Found a bug 🐞 or have an idea
  💡? [Open an issue](https://github.com/Chungzter/CommiZard/issues) and let’s
  discuss it!
- Starter-friendly tasks are listed in the
  [Starter Tasks section](./CONTRIBUTING.md#starter-tasks). Check it out if
  you’re not ready to dive into core features yet.

Not sure where to start? Open an issue or comment "I’d like to help with this,"
and we’ll figure it out together!

## License

`CommiZard` is released under the [MIT license](LICENSE).

Copyright (c) 2025-2026 Chungzter