Why · Status · Features · Screenshots · Architecture · Tech stack · Quick start · Environment variables · API reference · Deployment · Security · Testing · Troubleshooting · FAQ · Upcoming · Contributing · License
GitHub search and labels tell you what matches a keyword, not what's worth your time. They don't show whether a maintainer responds to PRs, whether an issue's been dead for a year, or whether it's already been attempted and abandoned in the comments. Figuring that out by hand means a dozen open tabs and an hour gone before you've written any code.
MergeMind pulls repository and issue data from GitHub, scores it, and gives you a ranked list with a plain-language reason for each recommendation — difficulty, clarity, and merge probability, not just a label.
v1.0.0 — stable release. GitHub OAuth, repository health analysis, issue scoring, portfolio tracking, and Docker support are all in and working.
- Issue scoring — difficulty, merge probability, and clarity per issue, so you can skip dead ends before opening them
- Repository health — activity, maintenance, and responsiveness signals, so you avoid abandoned repos
- Explanations — every recommendation ships with a short reason, not just a score
- Portfolio — automatically tracks your merged PRs across repos
- GitHub OAuth — sign in with your existing account, nothing new to manage
- Dark mode
flowchart TB
subgraph Client
A[Developer]
end
subgraph Frontend["Frontend — Next.js 14 / React 18"]
B[Dashboard UI]
AUTH[NextAuth Session]
end
subgraph Backend["Backend — FastAPI"]
C[API Routers]
S[Scoring Service]
end
subgraph External
D[GitHub API]
end
subgraph AIEngine["AI Engine"]
E[Ollama + Llama 3.2]
end
subgraph Data["Database"]
F[(SQLite / PostgreSQL)]
end
A -->|OAuth login| AUTH
AUTH -->|session token| B
B -->|REST calls| C
C -->|fetch repos & issues| D
C -->|score request| S
S -->|inference| E
E -->|scores + explanation| S
S -->|persist| F
C -->|read/write| F
F -->|results| B
- Frontend — renders the dashboard, handles the OAuth session via NextAuth, calls the backend API
- Backend — coordinates GitHub data fetching, scoring requests, and persistence
- GitHub API — source of repository, issue, and pull request data
- AI engine — runs Llama 3.2 through Ollama to score issues and generate explanations, locally, no external inference cost
- Auth — GitHub OAuth via NextAuth; issues and encrypts session tokens
- Database — stores users, scores, and portfolio history
How scoring works: fetch issue and repo metadata from GitHub → extract signals (activity, labels, comment count, issue age) → run through Llama 3.2 via Ollama → produce difficulty, clarity, and merge-probability scores → generate a short plain-language explanation alongside the score → rank and surface in the dashboard. The explanation is what shows up under each recommendation, so if a score looks off, it tells you what the model was weighing.
Next.js 14, React 18, TypeScript, Tailwind — FastAPI, Python 3.11, SQLAlchemy — Ollama (Llama 3.2) — NextAuth (GitHub OAuth) — SQLite / PostgreSQL — Docker — GitHub Actions
git clone https://github.com/BistaDinesh03/mergemind.git
cd mergemind
cp backend/.env.example backend/.env # set GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET
docker compose up -d
open http://localhost:3000Local development (no Docker):
# backend
cd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload
# frontend, in a second terminal
cd frontend
npm install
npm run dev
# scoring engine
ollama pull llama3.2
ollama serveGITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET— from your GitHub OAuth App. Use a separate App registered with your production callback URL when deploying.DATABASE_URL— SQLite locally (sqlite:///./mergemind.db); PostgreSQL in production, since SQLite isn't meant for concurrent load.OLLAMA_HOST— address of your Ollama instance, e.g.http://localhost:11434. Must be reachable from the backend.NEXTAUTH_SECRET— generate withopenssl rand -base64 32. Use a fresh value per environment, never reuse a dev secret in prod.NEXTAUTH_URL— optional locally, required in production (your public HTTPS domain, e.g.https://mergemind.dev).
Base URL (local): http://localhost:8000. Sample values below illustrate response shape — replace with real data from your instance.
GET /api/health
{ "status": "ok", "version": "1.0.0" }GET /api/repositories — list analyzed repositories
{
"repositories": [
{ "id": "repo_123", "full_name": "owner/example-repo", "health_score": 82, "last_analyzed": "2026-07-01T12:00:00Z" }
]
}POST /api/repositories/analyze — run health analysis on a repository
// request
{ "repo_url": "https://github.com/owner/example-repo" }// response
{
"id": "repo_123",
"full_name": "owner/example-repo",
"health_score": 82,
"signals": { "activity": "high", "maintainer_responsiveness": "medium", "open_issue_count": 47 }
}GET /api/issues/{repo_id} — list scored issues for a repository
{
"issues": [
{
"id": "issue_456",
"title": "Fix pagination bug in search results",
"difficulty": "easy",
"merge_probability": 0.78,
"explanation": "Small, well-scoped bug with a clear reproduction case and an active maintainer."
}
]
}GET /api/recommendations — fetch the current top recommendation
{ "issue_id": "issue_456", "repo": "owner/example-repo", "score": 0.78, "reason": "High merge probability, low difficulty, active maintainer." }GET /api/portfolio — fetch a user's contribution portfolio
{
"user": "octocat",
"merged_pull_requests": [
{ "repo": "owner/example-repo", "pr_number": 128, "merged_at": "2026-06-15T09:32:00Z" }
]
}POST /api/auth/callback — GitHub OAuth callback, invoked by NextAuth. Not intended to be called directly.
cp backend/.env.example backend/.env.production
# set DATABASE_URL, NEXTAUTH_URL, NEXTAUTH_SECRET, GITHUB_CLIENT_ID/SECRET as above
docker compose -f docker-compose.prod.yml up -dPut the app behind a reverse proxy (Caddy, Nginx, Traefik) for TLS. Ollama needs to be reachable from the backend container — run it on the same host or point OLLAMA_HOST at a remote instance. Both the backend and Ollama are CPU/memory sensitive under load; size accordingly if scoring many repos concurrently.
Auth goes through GitHub OAuth — MergeMind never sees your password. Session tokens are encrypted with NEXTAUTH_SECRET. Scoring runs locally through Ollama, so issue and repo data never leaves your infrastructure. Report vulnerabilities privately rather than as a public issue.
cd backend && pytest
cd frontend && npm run testInclude tests with any PR that touches scoring logic, API routes, or shared UI.
- Scoring requests hang or time out — Ollama isn't running or isn't reachable. Confirm
ollama serveis up andOLLAMA_HOSTis correct. - OAuth login redirects to an error page — client ID/secret mismatch, or the callback URL on your GitHub OAuth App doesn't match
NEXTAUTH_URL. docker compose upfails on the backend — usually a missing or malformed.envfile. Confirm it exists and was copied from.env.example.- Empty issue list for an analyzed repo — either the repo has no open issues, or you've hit a GitHub API rate limit. Wait and re-run analysis.
Known limitations: scoring depends on Llama 3.2 and will occasionally misjudge scope on unusual issues; SQLite isn't meant for concurrent production load; Ollama must be running for scoring to work, with no hosted fallback yet; heavy analysis across many repos can hit GitHub rate limits.
Does it cost anything to run? No paid API required — scoring runs locally through Ollama. You cover your own GitHub OAuth App and hosting.
Do I need a GPU? No, but scoring is faster with one.
Can I swap in a different model? In principle, any Ollama-supported model — prompts are currently tuned for Llama 3.2.
Is my GitHub data sent anywhere? No. Repos and issues are fetched from the GitHub API and scored locally by your own Ollama instance.
- Production hosting guide, PostgreSQL migration for hosted instances
- Demo walkthrough video
- Browser extension
git checkout -b feature/short-description
# feat: add issue difficulty filter to dashboardRun pytest and npm run test before opening a PR, and make sure the description explains what changed and why. Issues labeled good first issue are a good place to start.
MIT © BistaDinesh03