Bugs sit unfixed because someone has to notice them first. IssueLoop reads the test suite directly — a failing test is the bug report. It can also watch a live-running process or log file, for bugs that only show up outside a test run. No human has to spot it, and no human has to manually triage which failures are actually distinct problems.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.
Core concepts
IssueLoop moves a failing test from raw output to an actionable, prioritised ticket through a fixed pipeline. Each stage hands off cleanly to the next, and the whole thing runs locally with zero external accounts by default.Scan
issueloop.scan_repo("repos/myrepo") walks the repository and writes a file inventory — a manifest of every source and test file IssueLoop will need to reference later.Run tests
issueloop.run_tests("myrepo") executes all test commands listed in test_manifest.json and captures their output to a local log cache. Exit codes, stdout, and stderr are all recorded.LLM triage
issueloop.create_tickets("myrepo") sends each failure log to the configured LLM provider. The LLM deduplicates overlapping failures, assigns a priority, and writes a plain-English error summary for each independent problem it finds.Ticket queue
Each triaged failure is stored as a
Ticket in a local SQLite database (or Supabase, if configured). Tickets enter the queue with status pending and wait to be dispensed.Ticket data model
Every failure that IssueLoop triages is represented as aTicket dataclass (defined in issueloop/agent_state.py). When tickets are returned from the Python API or the CLI, they are serialised to plain dictionaries with the following fields.
| Field | Type | Description |
|---|---|---|
id | str | Unique identifier for the ticket. |
repo | str | The repository name this ticket belongs to. |
error_summary | str | Plain-English description of the failure, written by the LLM during triage. |
raw_log_ref | str | Reference to the raw log entry that produced this ticket. |
priority | str | One of blocking, high, normal, or low. Assigned by the LLM and used to order the queue. |
status | str | Lifecycle state: pending, in_progress, blocked, done, failed, or needs_human. |
attempts | int | How many times this ticket has been worked on. Incremented on retry; triggers escalation when it reaches max_retries. |
created_at | str | UTC timestamp of when the ticket was created. |
resolved_at | str | null | UTC timestamp set when the ticket moves to done. null until resolved. |
dispensed_at | str | null | UTC timestamp set when get_top_error claims the ticket. null until dispensed. |
escalation_summary | str | null | Reason text populated when the ticket is escalated to needs_human. |
command | str | null | The test command associated with this failure, if known. |
test_id | str | null | The specific test identifier for re-running after a fix is applied. |
proposed_fix | str | null | A shell command or patch stored by propose_fix() for the fix-apply layer. |
Priority values
Controls queue ordering.
blocking tickets are always dispensed first.blocking— test or process cannot proceed at allhigh— significant failure affecting core behaviournormal— standard bug, default assignmentlow— cosmetic or minor issue
Status values
Tracks where a ticket sits in its lifecycle.
pending— waiting in the queue, not yet claimedin_progress— claimed byget_top_error, being worked onblocked— cannot proceed due to an external dependencydone— resolved successfullyfailed— fix attempt failed and was not retried furtherneeds_human— escalated; exceeded retry limit or manually escalated
Local-first design
IssueLoop stores everything in a SQLite file atdata/issueloop.db by default. There is no account to create, no service to sign up for, and nothing phones home. You can be up and running — including LLM triage via Ollama — without a single API key.
The Supabase backend is available as an optional extra (pip install issueloop[supabase]) for teams that want a hosted backup or multi-machine access, but it is never required.
The default LLM provider is Ollama running locally with
qwen2.5-coder:7b. If Ollama is installed and running, IssueLoop works entirely offline.What’s next
Quickstart
Install IssueLoop, configure a provider, and pull your first bug ticket in under five minutes.
Batch workflow
Scan a repository, run tests, triage failures, and work through the ticket queue in one batch pass.
Live monitoring
Watch a running process or log file and have failures converted to tickets automatically as they happen.
Fix-apply layer
Propose and apply fixes under an explicit, auditable permission allowlist, with automatic test verification.