Skip to content

Kayariyan28/octagit

BranchesTags

Repository files navigation

OctaGit — turn an issue into a pull request

OctaGit

Turn a GitHub issue into a tested, reviewable pull request — without touching the console.
An agent-driven, failure-first workflow with a smart adaptive UI.

Quick start · Architecture · UI setup · Backend setup · Product overview · Roadmap

TL;DR

OctaGit reads a GitHub issue, analyses the target repository, drafts a fix, runs the test suite, and — on success — opens a draft pull request. When a model hits a rate limit, loses context, or hallucinates, an octopus advisor translates the raw failure into a plain-English next step, and a 3D context terrain shows you exactly what the agent managed to map before it stopped.

It ships as three interchangeable surfaces that share one engine:

  1. OctaGit CLI — a Python package with a local agent loop.
  2. OctaGit-web (Next.js 14) — a browser surface that streams agent output over Server-Sent Events.
  3. OctaGit-mcp — an MCP server for Claude Code, Copilot, or any MCP client.

Demo video: media/octagit_walkthrough.mp4 · Carousel deck: media/OctaGit_Carousel.pdf

Product overview

Problem

Triaging and fixing GitHub issues is a workflow of tiny frictions:

  • Cloning the repo, reading the code, guessing the right model.
  • Watching a run hit a 429 and collapse mid-analysis, with no useful artefact left behind.
  • Context windows collapsing on medium-sized repos.
  • Stack traces that tell you that something failed, never what to do next.

Proof of concept

A single browser surface absorbs model selection, tier detection, and retry choreography. The user pastes a repo URL and an issue body. A pre-flight audit fetches live pricing, probes the user's actual TPM ceiling (not the catalogue tier), ranks viable models, and exposes a fallback chain. The agent then drives the fix inside a CLI subprocess whose output streams back over SSE. On any non-success, the octopus advisor takes the stage with an LLM-authored post-mortem and an actionable next step.

North star

Zero failed runs that end without a useful artefact. Either the fix lands, or the user walks away with a map of what the agent tried and why.

Key differentiators

Concern Status-quo tool OctaGit
Rate limits Hard fail, user restarts Auto-walk an N-hop fallback chain
Context overflow Hard fail Partial context graph is always persisted
Model hallucinations Wasted review time Test suite runs before the PR is drafted
Failure messages Raw stack trace Advisor with plain-English recommendation
Local-only workflow Typically unsupported 7 local servers auto-detected

Architecture

                 ┌─────────────────────────────────────────────────────────┐
                 │                    ISSUE + REPO URL                     │
                 └─────────────────────────────────────────────────────────┘
                                            ▼
                 ┌─────────────────────────────────────────────────────────┐
                 │          NEXT.JS 14 · APP ROUTER · PORT 5230            │
                 │   /api/audit       /api/analyze       /api/stream/:id   │
                 └──────────┬──────────────────────┬───────────────────────┘
                            ▼                      ▼
                 ┌──────────────────┐     ┌─────────────────────────┐
                 │  issue2pr-audit  │     │ issue2pr   (agent loop) │
                 │  PRICING · TPM   │     │ TOOLS · FALLBACK WALK   │
                 └──────────┬───────┘     └────────────┬────────────┘
                            ▼                          ▼
                 ┌─────────────────────────────────────────────────────────┐
                 │                     LITELLM ROUTER                      │
                 │  Anthropic · OpenAI · OpenRouter · HF · GitHub Models   │
                 │  Ollama · LM Studio · llama.cpp · Jan · GPT4All · vLLM  │
                 └─────────────────────────────────────────────────────────┘
                                            ▼
                         ┌──────────────────────────────────┐
                         │  FALLBACK CHAIN WALKER           │  ← red path
                         │  rate · context · auth · bad-model│
                         └──────────┬────────────┬──────────┘
                                    ▼            ▼
                         ┌──────────────┐  ┌──────────────┐
                         │  OCTOPUS     │  │  CONTEXT     │
                         │  ADVISOR     │  │  TERRAIN     │
                         └──────┬───────┘  └──────┬───────┘
                                └────────┬────────┘
                                         ▼
                              ┌──────────────────┐
                              │   PULL REQUEST   │
                              └──────────────────┘

Two runtimes, one pipe. The Next.js surface owns motion, state, and the advisor. The Python agent owns the tool loop, test execution, and provider routing. They talk over line-buffered stdout with a small OCTAGIT_* JSON marker protocol for advisor and graph hand-offs.

See media/OctaGit_Carousel.pdf for the full system diagram and a deeper architectural tour.

Quick start

Prerequisites

  • macOS / Linux (Windows via WSL)
  • Python 3.10+
  • Node.js 18+ and npm
  • git
  • At least one LLM credential (Anthropic, OpenAI, OpenRouter, HF, GitHub Models) or a local server (Ollama / LM Studio / llama.cpp)
# 1. Clone
git clone https://github.com/karandey/issue2pr.git
cd issue2pr

# 2. Backend (Python agent)
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .

# 3. Frontend (Next.js web UI)
cd web && npm install && cd ..

# 4. Credentials
cp .env.example .env   # then edit .env — add at least one API key

# 5. Launch (two terminals)
# ── terminal A ─────────────────────────────────────────
source .venv/bin/activate
# (Python CLI is available as `issue2pr` and `issue2pr-audit`)

# ── terminal B ─────────────────────────────────────────
cd web
PORT=5230 npm run dev
# open http://localhost:5230

That's it. Paste a repo URL and an issue body, click Analyze Repo, and watch the agent drive.

UI setup

The browser surface is a standard Next.js 14 App Router app. No database, no auth server, no queue.

Install

cd web
npm install

Run in dev

PORT=5230 npm run dev

The dev server must run on port 5230 — the Python audit CLI spawns as a subprocess of the Next.js process, so the port is referenced in the video capture tooling and in any deep-linked screenshot. Other ports work, just update the launcher.

Build for production

npm run build
PORT=5230 npm start

What you get

  • Home page — hero, tagline typewriter, "Analyze Repo" CTA, ambient pixel octopus mascot.
  • Analyzer view — repo URL + issue body + optional provider keys; pre-flight audit; live streaming log.
  • Octopus advisor — full-screen overlay on any non-success; LLM-authored post-mortem typed character-by-character.
  • Context terrain — Three.js repo topography; peaks = symbol-dense files, valleys = config/tests, red contour lines = complexity density.

Demo mode (no backend required)

Append ?demo=success or ?demo=failure to the URL to skip the Python subprocess and preview the success/failure overlays directly. This is how the walkthrough video at media/octagit_walkthrough.mp4 was captured.

Browser support

Chromium-based browsers only for the 3D terrain (WebGL 2, custom GLSL shaders). Safari and Firefox render the rest of the UI fine; the terrain falls back to a 2D heatmap.

Backend setup

The backend is a pure Python package. No framework, no server — just a CLI that the Next.js app can spawn.

Install

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .                # runtime
pip install -e '.[mcp]'         # runtime + MCP server

Three entry points are installed:

  • issue2pr — the agent loop (used by the web UI's /api/analyze route).
  • issue2pr-audit — the pre-flight audit (used by /api/audit).
  • issue2pr-mcp — the MCP server (for Claude Code / Copilot / any MCP client).

Credentials

Copy .env.example → .env. Set at least one of:

ANTHROPIC_API_KEY="sk-ant-..."
OPENAI_API_KEY="sk-..."
OPENROUTER_API_KEY="sk-or-..."
HF_TOKEN="hf_..."
GITHUB_API_KEY="ghp_..."          # GitHub Models (inference)
GITHUB_TOKEN="ghp_..."            # PR creation — needs repo scope

Local servers don't need keys, only that they're running:

ollama serve           # default http://localhost:11434
lms server start       # LM Studio,    default http://localhost:1234
llama-server -p 8080   # llama.cpp
jan                    # Jan,          default http://localhost:1337

OctaGit probes each of these on every run and only appends a local hop to the fallback chain if the server is up and has at least one usable model loaded (Ollama /api/tags, OpenAI-compatible /v1/models).

CLI usage

issue2pr \
  --repo /path/to/repo \
  --issue-file /path/to/issue.md \
  --test-command "pytest -q"

Common flags:

  • --provider {auto|openai|anthropic|ollama|huggingface|github|…}
  • --model <litellm-model-slug> (e.g. anthropic/claude-sonnet-4-6)
  • --fallback-chain "anthropic/claude-opus-4-7,anthropic/claude-sonnet-4-6,openai/gpt-4.1"
  • --max-turns 24
  • --open-pr — after success, stage, commit, push, and open a draft PR.
  • --repo-url https://github.com/…/repo.git (inferred from origin if omitted)
  • --base-branch main
  • --no-draft — mark the PR ready-for-review.

Provider recipes

Anthropic (recommended)

export ANTHROPIC_API_KEY="sk-ant-..."
issue2pr --provider anthropic \
         --model anthropic/claude-sonnet-4-6 \
         --repo /tmp/demo-bug \
         --issue-file /tmp/demo-bug/issue.md

OpenAI

export OPENAI_API_KEY="sk-..."
issue2pr --provider openai --model gpt-4.1 \
         --repo /tmp/demo-bug --issue-file /tmp/demo-bug/issue.md

Local Ollama

ollama pull qwen2.5-coder:7b
issue2pr --provider ollama --model ollama_chat/qwen2.5-coder:7b \
         --repo /tmp/demo-bug --issue-file /tmp/demo-bug/issue.md

Hugging Face Inference

export HF_TOKEN="hf_..."
issue2pr --provider huggingface \
         --model huggingface/meta-llama/Llama-3.3-70B-Instruct \
         --repo /tmp/demo-bug --issue-file /tmp/demo-bug/issue.md

GitHub Models

export GITHUB_API_KEY="..."
issue2pr --provider github --model github/Phi-4 \
         --repo /tmp/demo-bug --issue-file /tmp/demo-bug/issue.md

MCP server

pip install 'issue2pr[mcp]'
issue2pr-mcp        # stdio transport, wire it into your MCP client config

Tools exposed:

  • issue2pr_run — clone, run agent, test, and (optionally) open a draft PR.
  • issue2pr_open_pr — given an already-prepared local clone with edits, push and open a draft PR.

Features

Pillar What it does
Pre-flight audit LiteLLM live pricing, real TPM probe via response headers, 75% context-fit safety margin, Haiku-authored post-mortem on risk.
Agent loop 7 tools (read/write/git/test/…); N-hop fallback chain; 60s/120s per-hop timeout; 6-category failure classifier (rate / context / auth / billing / bad-model / hallucination).
Recovery UX Octopus advisor, typewriter stream, partial context graph persisted on failure, one-click actionable CTA.
Local-first Auto-detects Ollama, LM Studio, llama.cpp, Jan, GPT4All, vLLM, text-generation-webui. Picks the actually-loaded model.
PR automation Stages, commits, pushes, opens a draft PR with a human-readable body.

Tech stack

Frontend · Next.js 14 (App Router) · React 18 · TypeScript · Three.js + custom GLSL shaders · Framer Motion · SSE client · Portal overlay.

Backend · Python 3.10+ · OpenAI Agents SDK · LiteLLM router · urllib probes · AST-based symbol extraction · concurrent.futures.ThreadPoolExecutor for parallel HTTP + per-hop timeout.

Providers · Anthropic (Opus 4.7, Sonnet 4.6, Haiku 4.5) · OpenAI (GPT-4.1, 4.1-mini) · OpenRouter · Ollama · LM Studio · llama.cpp · Jan · GPT4All · vLLM · text-generation-webui · Hugging Face · GitHub Models.

Transport · Server-Sent Events · line-buffered stdout · OCTAGIT_* JSON marker protocol.

Tooling · Puppeteer headless (walkthrough capture) · ffmpeg (video) · Mermaid (diagrams) · git (shallow clone).

Repo layout

issue2pr/
├── issue2pr/                 # Python package — the agent
│   ├── main.py               #   CLI entry + agent loop + fallback walker
│   ├── audit.py              #   pre-flight audit CLI
│   ├── audit_agent.py        #   LLM-authored audit post-mortem
│   ├── graph.py              #   repo → heightmap data for terrain
│   ├── pr.py                 #   git stage/commit/push + PR creation
│   ├── recovery.py           #   failure classifier + advisor prompt
│   └── mcp_server.py         #   MCP stdio server
│
├── web/                      # Next.js 14 web UI
│   └── src/app/
│       ├── api/audit         #   → spawns `issue2pr-audit`
│       ├── api/analyze       #   → spawns `issue2pr` + streams over SSE
│       ├── api/stream/[id]   #   SSE endpoint
│       ├── api/graph/[id]    #   context graph data
│       └── components/
│           ├── AnalyzerView.tsx
│           ├── OctopusRecommendationOverlay.tsx   # advisor
│           ├── RepoTerrain3D.tsx                  # Three.js terrain
│           ├── OctopusMascot.tsx                  # ambient pet
│           └── OctopusIcon.tsx                    # the red mark
│
├── media/
│   ├── readme_hero.png           # ← this README's header
│   ├── octagit_walkthrough.mp4   # 75s walkthrough
│   └── OctaGit_Carousel.pdf      # 13-slide product deck
│
├── pyproject.toml
└── README.md

Troubleshooting

audit exited 1 — the web surface reports a raw exit code if the audit CLI crashes before printing JSON. Run issue2pr-audit --repo-url … --issue-file … directly to see the real error.

Ollama hop hangs — OctaGit only appends an Ollama hop if /api/tags returns a loaded model. If your model name ends in :cloud it's filtered out. Pull a local variant: ollama pull qwen2.5-coder:7b.

"Rate-limited" on a paid key — the chain walker classifies errors into six buckets. If a paid key reports as rate-limited, it's likely a tier ceiling (free-tier cap still active until first payment clears). Check the octopus advisor output — the real error text is printed below the category label.

Could not find a declaration file for module 'three' — from the web build. Run cd web && npm install --save-dev @types/three.

WebGL not rendering in headless capture — the walkthrough capture script uses --use-gl=angle --use-angle=swiftshader --enable-unsafe-swiftshader. Without those flags, Three.js silently falls back.

Roadmap

Near-term

  • Persistent conversation with the octopus advisor after a run.
  • PR-review agent mode — reviewer persona instead of fixer.
  • Multi-repo batch queue — triage 10 issues, wake up to 10 PRs.
  • User-authored recovery playbooks per-provider.

Infra

  • Worker pool for parallel analyses (currently one-at-a-time).
  • Persistent context-graph store (Neo4j) for repeat runs on the same repo.
  • Resumable runs — retry just the hop that timed out.

UX

  • Voice input (partial — browser dictation already works in the form).
  • Guided tier upgrade — advisor includes a one-click upgrade link.
  • Shareable audit cards, auto-generated from a completed run.

Research

  • Auto-curated "escalation card" explaining why a model couldn't handle a repo.
  • Reinforcement from accepted / rejected PR outcomes to improve hop ordering.

Credits

Designed and built by Karan Chandra Dey — k28art.space

Powered by Anthropic Claude, OpenAI GPT, and the open-source LiteLLM router. Built with the OpenAI Agents SDK, Next.js, React, Three.js, and Framer Motion.

Thanks to everyone whose 429 we turned into a story.

© 2026 · OctaGit · K28 · Carousel deck · Walkthrough video

About

Turn a GitHub issue into a tested pull request — agent-driven, failure-first.

Resources

Readme

License

MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages