CommitIQ

CommitIQ is a CLI tool that turns your git commits into a clean, human-readable summary of what you actually shipped. It scans commits across multiple repositories, filters by your git author identity, and uses AI to translate technical commit messages into product-facing task descriptions — grouped by repo and date.

CommitIQ ships a built-in MCP server that exposes its functionality as tools any MCP-compatible AI agent can call — Claude Desktop, Cursor, Zed, or any custom agent built with the MCP SDK.

commitiq mcp

The server runs over stdio (standard input/output), which is the transport used by all desktop MCP clients. It stays running in the foreground until you press Ctrl+C or send SIGTERM.

Add the following to your Claude Desktop config file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
 "mcpServers": {
 "commitiq": {
 "command": "commitiq",
 "args": ["mcp"]
 }
 }
}

If commitiq is not on your PATH (e.g. installed in a uv environment), use the full path to the binary:

{
 "mcpServers": {
 "commitiq": {
 "command": "/Users/you/.local/bin/commitiq",
 "args": ["mcp"]
 }
 }
}

Restart Claude Desktop after saving. You should see the commitiq tools listed under the plug icon in the chat input bar.

Any MCP client that supports the stdio transport can connect to CommitIQ. Point the client at:

• command: commitiq
• args: ["mcp"]

For agents built with the MCP Python SDK or similar, pass the command above as the StdioServerParameters.

Once connected, you can ask your agent things like:

• "What did I work on this week?"
• "Summarize my commits for April 2025."
• "Add ~/projects/my-app to commitiq and summarize today's work."

• Python 3.13 or higher
• uv (recommended) or pip
• A git identity configured (git config --global user.email)
• An API key for your chosen AI model provider (see Supported Models)

uv tool install commitiq

pip install commitiq

Verify the installation:

commitiq --help

CommitIQ uses LiteLLM under the hood, so it supports any model that LiteLLM supports. Set the appropriate environment variable for your provider before running:

The default model is gpt-4o-mini. You can change it at any time with the use command.

CommitIQ reads API keys from environment variables. You must set the variable for whichever provider you intend to use before running any command that calls the model.

# OpenAI
export OPENAI_API_KEY="sk-..."
# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
# Google Gemini
export GEMINI_API_KEY="AIza..."

The key is only active for the lifetime of that shell session. Every new terminal window will need the export again unless you persist it.

Add the export line to your shell profile so it is set automatically on login:

# for zsh (default on macOS)
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc
source ~/.zshrc
# for bash
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.bashrc
source ~/.bashrc

Run commitiq use <model> without --no-verify. CommitIQ will make a minimal test call and report success or a specific auth error:

commitiq use gpt-4o-mini
# Verifying gpt-4o-mini...
# ✔ Model set to gpt-4o-mini

If the key is missing or invalid you will see the provider's error message (e.g. AuthenticationError: Incorrect API key). Fix the environment variable and retry.

Register the git repos you want CommitIQ to scan:

commitiq add /path/to/my-project
commitiq add /path/to/another-project --name "Backend API"

The --name flag sets a display label. If omitted, the directory name is used.

commitiq use gpt-4o-mini

CommitIQ will verify the model is reachable before saving. To skip verification (e.g. for local models):

commitiq use ollama/llama3 --no-verify

Summarize commits from the current week (Monday to today):

commitiq summarize

Summarize a custom date range:

commitiq summarize --from 2025年04月01日 --to 2025年04月30日

Override the model for a single run:

commitiq summarize --model claude-haiku-4-5

List all configured repos:

commitiq list

Remove a repo:

commitiq remove /path/to/my-project

CommitIQ ships a built-in MCP server that exposes its functionality as tools any MCP-compatible AI agent can call — Claude Desktop, Cursor, Zed, or any custom agent built with the MCP SDK.

commitiq mcp

The server runs over stdio (standard input/output), which is the transport used by all desktop MCP clients. It stays running in the foreground until you press Ctrl+C or send SIGTERM.

Add the following to your Claude Desktop config file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
 "mcpServers": {
 "commitiq": {
 "command": "commitiq",
 "args": ["mcp"]
 }
 }
}

If commitiq is not on your PATH (e.g. installed in a uv environment), use the full path to the binary:

{
 "mcpServers": {
 "commitiq": {
 "command": "/Users/you/.local/bin/commitiq",
 "args": ["mcp"]
 }
 }
}

Restart Claude Desktop after saving. You should see the commitiq tools listed under the plug icon in the chat input bar.

Any MCP client that supports the stdio transport can connect to CommitIQ. Point the client at:

• command: commitiq
• args: ["mcp"]

For agents built with the MCP Python SDK or similar, pass the command above as the StdioServerParameters.

Once connected, you can ask your agent things like:

• "What did I work on this week?"
• "Summarize my commits for April 2025."
• "Add ~/projects/my-app to commitiq and summarize today's work."

CommitIQ stores its configuration at ~/.commitiq/config.yml. You don't need to edit it manually, but the format is:

repos:
 - path: /absolute/path/to/repo
 name: optional-display-name
model: gpt-4o-mini

MIT — see LICENSE.