Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/onenot8/issueLoop/llms.txt

Use this file to discover all available pages before exploring further.

This page walks through the full IssueLoop workflow from a fresh install to claiming and resolving your first bug ticket. You will install the package, point it at a repository, run the test suite, let the LLM triage the failures, and then pull the top ticket out of the queue — all in a few lines of Python or from the CLI.
The default LLM provider is Ollama running locally with qwen2.5-coder:7b — free, fully offline, and no API key required. If Ollama is already installed and running, you can complete this entire quickstart without touching any cloud service.
1

Install

Install IssueLoop from PyPI. Python 3.10 or later is required.
pip install issueloop
2

Configure

Call issueloop.use(...) once at the start of your script to set the database backend and LLM provider. The example below shows a multi-provider setup with Anthropic as the primary and Ollama as the local fallback — IssueLoop tries them in order and falls back automatically if one is unavailable.
import issueloop

issueloop.use(
    database="local",                      # or "supabase" for a hosted backup
    llm={"providers": [                    # priority list — falls back automatically
        {"provider": "anthropic", "model": "claude-sonnet-4-6", "api_key": "sk-..."},
        {"provider": "ollama", "model": "qwen2.5-coder:7b"},   # free, local, default if omitted
    ]},
    notify={"webhook": "https://your-endpoint"},   # fires if IssueLoop itself breaks
)
Omit the llm argument entirely to use the Ollama default with no configuration. The call issueloop.use(database="local") is all you need to get started.
3

Scan and run tests

Point IssueLoop at your repository to build a file inventory, then execute the test suite. scan_repo takes a path; run_tests takes the short repository name as registered in test_manifest.json.
issueloop.scan_repo("repos/myrepo")
issueloop.run_tests("myrepo")
run_tests returns a list of result dicts — one per test command — each containing test_id, exit_code, and the captured output. Failures are written to the local log cache and picked up automatically by the next step.
4

Create tickets

Send every failure log through the LLM triage step. IssueLoop deduplicates overlapping failures and writes one Ticket per independent problem, with a plain-English summary and an assigned priority.
tickets = issueloop.create_tickets("myrepo")
The return value is a list of ticket dicts. Each dict has the same shape as the JSON returned by get_top_error in the next step.
5

Claim a ticket

Pull the highest-priority pending ticket out of the queue. The ticket is atomically marked in_progress so that no other caller receives the same ticket.
ticket = issueloop.get_top_error("myrepo")
Example return value:
{
  "id": "a3f2c1d0-8b4e-4f1a-9c7d-123456789abc",
  "repo": "myrepo",
  "priority": "high",
  "status": "in_progress",
  "error_summary": "AssertionError in test_calculate_total: expected 42, got 0. Likely a missing return statement in calculate_total().",
  "raw_log_ref": "myrepo_run_20240601T120000.log",
  "command": "pytest tests/test_math.py",
  "test_id": "tests/test_math.py::test_calculate_total",
  "attempts": 0,
  "escalation_summary": null,
  "proposed_fix": null,
  "created_at": "2024-06-01 12:00:05.123456+00:00",
  "resolved_at": null,
  "dispensed_at": "2024-06-01 12:00:10.654321+00:00"
}
If there are no pending tickets, get_top_error returns None.
6

Resolve

Once your code or pipeline has fixed the underlying problem, mark the ticket done.
issueloop.resolve(ticket["id"])
The ticket’s status is set to done and resolved_at is recorded. It will not be dispensed again.

​
Equivalent CLI workflow

Every step above has a direct CLI counterpart. This is useful for shell scripts, CI pipelines, or any non-Python environment. 
# 1. Check that Ollama and required models are ready
issueloop check-env

# 2. Scan the repository and build a file inventory
issueloop scan repos/myrepo

# 3. Run the test suite
issueloop test myrepo

# 4. Triage failures and create tickets
issueloop tickets myrepo

# 5. Claim the next ticket (prints JSON)
issueloop next myrepo

# 6. (after fixing) clean up old resolved tickets
issueloop cleanup --days 30
issueloop next prints the full ticket JSON to stdout, so you can pipe it into jq or any other tool: 
issueloop next myrepo | jq '.error_summary'
Run issueloop serve --port 8787 to expose the same ticket queue over a local HTTP API. Any language that can make HTTP requests can then call GET /errors/top?repo=myrepo to claim tickets — no Python required.

Build docs developers (and LLMs) love

Get started for freeTalk to us