git-issue-fixer

A pip-installable agent you can drop into any Python project. It reads open GitHub issues from a repo you configure, clones that repo, uses an Ollama LLM to patch files, and opens a pull request.

You do not copy this source into your app. Install the package, add a .env (or export environment variables), and run the command.

---

What you need

• Python 3.10+
• git on your PATH
• An Ollama server with the model you name in .env
• A GitHub personal access token with repo scope

The target GitHub repo is whatever you set in GIT_REPO_URL. It does not have to be the project where you installed the package.

---

1. Install into your project

From the folder that contains this package (or a built wheel):

cd your-python-project
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install /path/to/git_issue_fixer_agent

Editable install while developing the agent itself:

pip install -e /path/to/git_issue_fixer_agent

With uv:

uv add /path/to/git_issue_fixer_agent

That installs the git-issue-fixer console script into your environment.

You can also add it in pyproject.toml:

[project]
dependencies = [
  "git-issue-fixer @ file:///absolute/path/to/git_issue_fixer_agent",
]

---

2. Configure (.env in your project)

Run this in the directory you want to work from (usually your project root):

git-issue-fixer init

That writes a .env file if one does not already exist. Edit it:

# Required
GITHUB_TOKEN=ghp_your_token_here
GIT_REPO_URL=https://github.com/owner/your-repo.git

# Ollama (required to actually run)
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=qwen3.6:27b

# Optional
# ISSUE_LIMIT=5
# MAX_REPAIRS=3
# ISSUE_BRANCH_PREFIX=fix/
# GIT_ISSUE_FIXER_WORK_DIR=repo_work
# MAX_ANALYZE_FILE_BYTES=40000
# LLM_TEMPERATURE=0.9

Add .env to your project's .gitignore. Do not commit tokens.

How config is loaded

1. --env-file /path/to/file if you pass it
2. Else .env in the current working directory
3. Else variables already in the process environment

Variables already set in the shell are not overwritten by the file.

You can skip .env entirely:

export GITHUB_TOKEN=ghp_...
export GIT_REPO_URL=https://github.com/owner/your-repo.git
export OLLAMA_HOST=http://localhost:11434
export OLLAMA_MODEL=qwen3.6:27b
git-issue-fixer

Environment variables

Variable	Required	Default	Meaning
GITHUB_TOKEN	yes	—	GitHub PAT (repo scope)
GIT_REPO_URL	yes	—	Repo whose issues will be fixed
OLLAMA_HOST	no	http://localhost:11434	Ollama base URL
OLLAMA_MODEL	no	qwen3.6:27b	Model name on that host
ISSUE_LIMIT	no	5	How many open issues to process
MAX_REPAIRS	no	3	Repair attempts after failed tests
ISSUE_BRANCH_PREFIX	no	fix/	Prefix for new branches
GIT_ISSUE_FIXER_WORK_DIR	no	repo_work	Clone directory (relative to cwd)
MAX_ANALYZE_FILE_BYTES	no	40000	Max source bytes sent to the LLM
LLM_TEMPERATURE	no	0.9	Ollama temperature

---

3. Run it

From your project directory (where .env lives):

git-issue-fixer

Useful flags:

git-issue-fixer --help
git-issue-fixer --env-file /path/to/.env
git-issue-fixer --limit 1
git-issue-fixer init --env-file /tmp/issue-fixer.env
python -m git_issue_fixer --env-file .env

What happens

For each open issue (up to ISSUE_LIMIT):

1. Clone GIT_REPO_URL into repo_work/ (or GIT_ISSUE_FIXER_WORK_DIR)
2. Analyze only files inside that clone
3. Generate and apply a patch there
4. Commit on a short branch (fix/<first-3-title-words>-<10-char-random>)
5. Push and open a pull request

The agent does not edit files in your local project unless that project is the GitHub repo you pointed GIT_REPO_URL at.

---

4. Call it from Python

In any script, notebook, or app that uses the same virtualenv:

from git_issue_fixer.main import configure, run

configure()                    # loads .env from the current directory
run()

Custom env file and issue cap:

from git_issue_fixer.main import configure, run

configure(env_file="/path/to/.env", issue_limit=2)
run()

Or invoke the CLI from code:

from git_issue_fixer.cli import main

main(["--env-file", ".env", "--limit", "1"])

Load settings without running the agent:

from git_issue_fixer.config import load_settings

settings = load_settings(".env")
print(settings.git_repo_url, settings.ollama_host)

---

5. Typical layout in your project

your-python-project/
├── .venv/
├── .env                 # gitignored; GITHUB_TOKEN, GIT_REPO_URL, Ollama
├── pyproject.toml       # lists git-issue-fixer as a dependency
├── src/your_app/
└── repo_work/           # created at runtime, cloned target repo

repo_work/ is a throwaway clone. You can add it to .gitignore.

---

6. CI / automation

Example GitHub Actions step (secrets in the repo settings, not in .env):

- name: Run git-issue-fixer
  env:
    GITHUB_TOKEN: ${{ secrets.ISSUE_FIXER_TOKEN }}
    GIT_REPO_URL: https://github.com/${{ github.repository }}.git
    OLLAMA_HOST: http://ollama.internal:11434
    OLLAMA_MODEL: qwen3.6:27b
    ISSUE_LIMIT: "1"
  run: git-issue-fixer

The job environment must be able to reach Ollama (OLLAMA_HOST).

---

Troubleshooting

Problem	What to check
command not found: git-issue-fixer	Activate the venv where you ran pip install.
Missing GITHUB_TOKEN / GIT_REPO_URL	Run git-issue-fixer init in that directory and edit .env, or pass --env-file.
Env file not found	Path to --env-file is wrong; it is resolved from the current working directory.
Failed to clone	Token needs repo scope; URL should be https://github.com/owner/repo.git.
[Errno 65] No route to host / connection refused	OLLAMA_HOST is unreachable. Try curl "$OLLAMA_HOST/api/tags".
Wrong repo got cloned	GIT_REPO_URL is the target to fix, not necessarily the project you installed the package into.
No files changed	The agent only writes inside repo_work/. Paths outside that clone are skipped.

---

License / version

Package name: git-issue-fixer
Import name: git_issue_fixer
CLI: git-issue-fixer
Requires: Python >= 3.10