git-agent

A smart git commit, push, and PR tool. Works as a standalone CLI, with any AI agent, or as a Claude Code skill.

What it does

• Reads your staged diff and branch name
• Generates a structured commit message (via Claude, GPT-4o, or your $EDITOR)
• Extracts a ticket/issue ID from the branch name and prefixes the commit
• Works with any ticketing system — Jira, Linear, GitHub Issues, YouTrack, and more
• Commits, pushes, and optionally opens a PR/MR
• Supports GitHub, GitLab, and Bitbucket (auto-detected from remote URL)

Install

Requires Python 3.9+ and git.

git clone https://github.com/keivanzavari/git-agent
# Option A: symlink globally
ln -sf "$PWD/git-agent/git-agent" /usr/local/bin/git-agent

# Option B: add to PATH in your shell profile
export PATH="$PWD/git-agent:$PATH"

git_agent.py is stdlib-only and needs no installation. Optional extras:

# MCP server (for VS Code / Copilot / Claude Desktop integration)
pip install -r requirements.txt

# Running the test suite
pip install -r requirements-dev.txt

Claude Code skill (optional)

mkdir -p ~/.claude/skills/git-agent
cp git-agent/SKILL.md ~/.claude/skills/git-agent/SKILL.md

Then invoke with /git-agent inside Claude Code.

Usage

# Stage your changes first
git add -p

# Standalone — LLM generates the commit message
git-agent

# With ticket context (Jira, Linear, GitHub Issues, etc.)
git-agent "AUTH-42: adds Google SSO via short-lived JWTs in httpOnly cookies"

# Commit + push + open PR
git-agent --pr

# Draft PR on a specific base branch
git-agent --pr --draft --base develop

# Agent-driven: message already written, skip all prompts
git-agent --message "Add OAuth2 login via Google" --pr --yes

# Commit only, no push
git-agent --no-push

Options

Flag	Description
-m, --message MSG	Use this commit message (skip LLM generation)
--title TITLE	Override PR/MR title
--pr	Open a PR/MR after pushing
--draft	Open a draft PR/MR (implies --pr)
--base BRANCH	Base branch for PR/MR (default: auto-detected)
--no-push	Commit only
-y, --yes	Skip all confirmation prompts

Configuration

Set environment variables in your shell profile (~/.zshrc, ~/.bashrc).

LLM keys

These power the built-in commit message generator used by the standalone CLI and the generate_commit_message MCP tool.

export ANTHROPIC_API_KEY=sk-ant-...   # Claude (preferred)
export OPENAI_API_KEY=sk-...          # GPT-4o

In typical MCP usage (Copilot, Claude Desktop), the host agent generates the commit message and calls commit directly — so these keys are not required for that workflow. They are only needed when running git-agent standalone or when explicitly invoking the generate_commit_message MCP tool.

If neither key is set, the standalone CLI falls back to $EDITOR for message input.

Ticket configuration

# Optional: clickable ticket links in PR bodies — use {id} as the placeholder
export TICKET_URL_TEMPLATE=https://yourorg.atlassian.net/browse/{id}  # Jira
# export TICKET_URL_TEMPLATE=https://linear.app/myteam/issue/{id}     # Linear
# export TICKET_URL_TEMPLATE=https://github.com/org/repo/issues/{id}  # GitHub Issues

# Optional: override the default ticket ID regex ([A-Z]+-[0-9]+)
# export TICKET_PATTERN='[0-9]+'       # plain issue numbers (GitHub / GitLab)
# export TICKET_PATTERN='sc-[0-9]+'    # Shortcut
# export TICKET_PATTERN='AB#[0-9]+'    # Azure DevOps

Platform support

Platform	CLI (required for PRs)	Install
GitHub	gh	https://cli.github.com
GitLab	glab	https://gitlab.com/gitlab-org/cli
Bitbucket Server/DC	bb (preferred)	https://github.com/keivanzavari/bb-cli
Bitbucket Cloud	bkt (fallback)	brew install avivsinai/tap/bitbucket-cli

The platform is auto-detected from git remote get-url origin. For self-hosted Bitbucket Server instances set BITBUCKET_SERVER_URL so the hostname can be matched:

export BITBUCKET_SERVER_URL=https://bitbucket.yourcompany.com
export BITBUCKET_TOKEN=your-http-access-token   # Personal Settings → HTTP access tokens

Each CLI handles its own authentication — run once to set up credentials:

gh auth login          # GitHub
glab auth login        # GitLab
# bb uses BITBUCKET_SERVER_URL + BITBUCKET_TOKEN env vars (see above)

Commits and pushes work without any CLI installed.

Ticket ID extraction

A ticket/issue ID is extracted from the branch name via the TICKET_PATTERN regex (default: [A-Z]+-[0-9]+, which covers Jira, Linear, YouTrack, and similar systems):

feature/AUTH-42/google-sso   →   [AUTH-42] ...
fix/PLAT-7-null-pointer      →   [PLAT-7] ...
main                         →   (no prefix)

For other systems, override TICKET_PATTERN:

TICKET_PATTERN='[0-9]+'      issue/123-fix-login   →   [123] ...   (GitHub/GitLab)
TICKET_PATTERN='sc-[0-9]+'   sc-456/dark-mode      →   [sc-456] ...  (Shortcut)

VS Code / Copilot integration (MCP)

git-agent ships with an MCP server (git_agent_mcp.py) that exposes its tools to any MCP-compatible client — including GitHub Copilot agent mode in VS Code and Claude Desktop.

Setup

1. Install dependencies: pip install -r requirements.txt
2. The .vscode/mcp.json in this repo auto-configures the server for VS Code. Clone the repo and open it — the git-agent server will appear in Copilot's tool list once agent mode is enabled.

Available tools

Tool	What it does
get_git_status	Branch, staged/unstaged files, recent log
get_staged_diff	Full diff + stat + ticket ID for the staged changes
generate_commit_message	LLM-generated commit message from staged diff (requires ANTHROPIC_API_KEY or OPENAI_API_KEY; in normal agent workflows the host agent generates the message instead)
commit	Commit staged changes (optionally push)
create_pr	Open a PR/MR on GitHub, GitLab, or Bitbucket
get_pr_comments	Fetch reviewer comments and reviews on the open PR/MR for the current branch
update_pr	Update the title, description, base branch, or draft status of the open PR/MR

Example Copilot agent prompts

• "What's staged right now?" → calls get_staged_diff
• "Generate a commit message for my changes" → calls generate_commit_message
• "Commit and push with message: Fix null pointer in auth" → calls commit
• "Open a draft PR against develop" → calls create_pr
• "What are the review comments on my PR?" → calls get_pr_comments
• "Update the PR title to include the ticket number" → calls update_pr

Using with AI agents

Any agent with Bash tool access can call git-agent directly:

# The agent generates the message, the script handles the mechanics
git-agent --message "<agent-generated message>" --pr --yes "<extra context>"

For Claude Code, use the /git-agent skill which handles message generation and delegates execution to this script automatically.

Running tests

python3 -m pytest tests/ -v

Requires pytest — see requirements-dev.txt.

Requirements

• Python 3.9+
• git
• gh CLI (optional — required only for GitHub PR creation/update)
• glab CLI (optional — required only for GitLab MR creation/update)
• bb CLI (optional — preferred for Bitbucket Server/DC PR creation/update/comments)
• bkt CLI (optional — fallback for Bitbucket when bb is not installed)

git_agent.py is stdlib-only (no pip install needed for the CLI). The MCP server (git_agent_mcp.py) additionally requires mcp>=1.2.0 — see requirements.txt.