gitaiflow

AI-assisted Git change summarization and engineering analysis for Python developers.

Maintained by: https://djangoplay.org

gitaiflow analyzes your Git changes with an AI model and produces a structured, timestamped change summary that can be used as a commit title/body, piped into Git workflows, or consumed by another tool or agent.

It is provider-agnostic: use Google Gemini, a local Ollama model, or any OpenAI-compatible endpoint such as OpenAI, Groq, DeepSeek, OpenRouter, vLLM, or LM Studio.

Features

• Generate AI summaries from Git diffs
• Summarize a directory or individual file
• Generate commit-ready titles and bodies
• Produce structured JSON output
• Optionally generate a Markdown representation
• Print commit messages directly to stdout
• Skip selected paths such as migrations or tests
• Compare against a specified remote and base branch
• Use cloud or fully local AI models
• Query OpenRouter's live model catalog
• No vendor lock-in

Requirements

• Python 3.11 or later
• Git
• An AI provider configured before running gitaiflow

Installation

pip install gitaiflow

Quick Start

Configure an AI provider and run:

gitaiflow --path .

For a commit-ready message:

gitaiflow --path . --print-commit

Example:

mailer: add retry backoff for failed sends

- Added exponential backoff retry logic in retry.py
- tasks.py now retries send_mail up to 3 times on failure
- No changes to public function signatures

The commit output can be piped directly into Git:

gitaiflow --path . --print-commit > /tmp/msg.txt
git commit -F /tmp/msg.txt

AI Provider Configuration

gitaiflow requires an AI model. It supports Gemini, Ollama, and OpenAI-compatible endpoints.

Configuration can be provided through environment variables or a .gitaiflow.env file in the repository root.

OpenRouter

OpenRouter can be used with its free model router or with a specific model available through your account.

AI_PROVIDER=custom
AI_BASE_URL=https://openrouter.ai/api/v1
AI_API_KEY=<your-openrouter-api-key>
AI_MODEL=openrouter/free

AI_TEMPERATURE=0.2
AI_MAX_TOKENS=10000
AI_REQUEST_TIMEOUT=60

Keep API keys private and never commit .gitaiflow.env to source control.

To list currently available free OpenRouter models:

gitaiflow --list-models --free-only

To list the full OpenRouter catalog:

gitaiflow --list-models

Add --json when you need the raw model metadata.

Google Gemini

export AI_PROVIDER=gemini
export AI_API_KEY=<your-key>

Ollama

For fully local inference:

export AI_PROVIDER=ollama
export AI_MODEL=llama3.2:3b

The model name must match a model available from your local Ollama installation.

OpenAI-Compatible Providers

export AI_PROVIDER=custom
export AI_BASE_URL=<endpoint>
export AI_API_KEY=<key>
export AI_MODEL=<model>

This can be used with OpenAI-compatible services including OpenAI, Groq, DeepSeek, OpenRouter, vLLM, LM Studio, and other compatible endpoints.

Configuration

Variable	Default	Description
AI_PROVIDER	gemini	gemini, ollama, openai, or custom
AI_BASE_URL	Provider default	Optional API endpoint override
AI_API_KEY	None	API key for cloud/OpenAI-compatible providers
AI_MODEL	Provider default	Model identifier
AI_TEMPERATURE	0.2	Model temperature
AI_MAX_TOKENS	10000	Maximum generated tokens
AI_REQUEST_TIMEOUT	60	Request timeout in seconds

Usage

Summarize a directory:

gitaiflow --path mailer/

Summarize a single file:

gitaiflow --path users/views/logout.py

Skip paths:

gitaiflow --path . --skip migrations tests

Use a specific remote and base branch:

gitaiflow --path . --remote upstream --base-branch develop

Write output to a custom location:

gitaiflow --path . -o artifacts/

Generate a Markdown representation in addition to JSON:

gitaiflow --path . --markdown

Print a commit-ready title and body:

gitaiflow --path . --print-commit

Output

Each run produces a structured JSON change summary containing Git-derived information such as:

• Repository and branch
• Target and target type
• Base revision
• Change window
• Changed files and statuses
• AI provider and model
• Generated commit title
• Generated commit body

The generated commit title and body are the model-generated portions of the result. Git metadata such as the branch, base, changed files, and change window comes directly from Git.

With --markdown, gitaiflow also produces a human-readable Markdown representation from the same JSON data.

Local Usage Tracking

gitaiflow maintains a local usage log at:

~/.gitaiflow/usage.jsonl

The log records local execution information such as timestamps, repository name, model used, estimated token counts, duration, and success status.

The usage log remains on the user's machine.

Optional local daily limits can be configured with:

export GITAIFLOW_MAX_RUNS_PER_DAY=20
export GITAIFLOW_MAX_TOKENS_PER_DAY=50000

These are local courtesy limits, not server-side quotas or enforcement.

Privacy and Telemetry

Telemetry is disabled by default.

If explicitly enabled with:

export GITAIFLOW_TELEMETRY=true

a run sends limited operational information to the configured telemetry receiver, including the gitaiflow version, AI provider, model name, target type, changed-file count, estimated token counts, duration, operating system, and success status.

The following are not sent through telemetry:

• Repository name
• File paths
• File contents
• Git diff contents
• Git author or branch
• Commit messages
• AI-generated summary text

On the first telemetry-enabled run, gitaiflow prints the exact telemetry payload to stdout.

Limitations

• An AI provider must be configured before gitaiflow can generate summaries.
• Local usage limits are courtesy guardrails and can be removed by the user.
• Secret redaction is best-effort pattern matching; generated summaries should be reviewed before being shared.
• Token and cost estimates are approximate and are not provider billing measurements.

Links

• Homepage: https://gitlab.com/codefleet-labs/gitaiflow
• Repository: https://gitlab.com/codefleet-labs/gitaiflow
• Issues: https://gitlab.com/codefleet-labs/gitaiflow/-/issues
• Documentation: https://docs.djangoplay.org/view#projects/gitaiflow/

License

gitaiflow is released under Apache License.