Getting Started

CodeLens is an AI-powered tool that reads a GitHub issue and produces a step-by-step contribution roadmap — including the exact files to change and a working code diff.

Quick start

  1. 1Sign up — create a free account with email, GitHub, or Google OAuth.
  2. 2Paste a GitHub issue URL — any public issue from any repository.
  3. 3Get your roadmap — AI analyzes the issue and returns a full plan in ~30 seconds.
  4. 4Follow the steps — each step includes file paths, code changes, and explanations.
  5. 5Open your PR — use the generated diff as a starting point.
Start with issues labeled good first issue or help wanted — they tend to have clearer scope and better descriptions, which gives the AI more to work with.

How It Works

The analysis runs through a four-step AI pipeline. Each step builds on the previous one so the final output is grounded in real code — not generic boilerplate.

01

Issue analysis

Gemini Pro reads the full issue body, labels, and linked PRs to understand the problem type (bug, feature, refactor), affected area, and complexity.

02

File detection

The repo file tree is fetched via Octokit. Keyword mapping ranks files by relevance, filtering out config and focusing on source files (.ts, .py, .java, etc.).

03

Code context fetching

The top 2–3 files are fetched from GitHub (up to 3 500 chars each). Real function names and class structures are passed to the AI — no hallucinated code.

04

Solution generation

A complete roadmap is generated: difficulty score, estimated fix time, technical explanation, relevant files, 4-step plan with before/after diffs, and a confidence score.

Features

Multi-language support

Java, TypeScript, JavaScript, Python, Go, Ruby, C#, Rust, Kotlin

Real code context

Fetches actual source files from GitHub — no hallucinated code

Step-by-step roadmap

Each step includes file paths, code changes, and explanations

Before/after diffs

Visual code comparison showing exactly what to change

Confidence scoring

0–100 score based on how grounded the solution is in real code

OAuth login

Sign in with GitHub or Google — no password needed

OAuth Setup

Google OAuth

  1. 1Go to Google Cloud Console.
  2. 2Create a project, then navigate to APIs & Services → Credentials.
  3. 3Click Create Credentials → OAuth 2.0 Client ID.
  4. 4Set the authorized redirect URI to http://localhost:5000/api/v1/auth/google/callback.
  5. 5Copy the Client ID and Secret into your .env.
.env
GOOGLE_CLIENT_ID=your_google_client_id_here
GOOGLE_CLIENT_SECRET=your_google_client_secret_here

GitHub OAuth

  1. 1Go to GitHub Developer Settings.
  2. 2Click OAuth Apps → New OAuth App.
  3. 3Set the callback URL to http://localhost:5000/api/v1/auth/github/callback.
  4. 4Copy the Client ID and Secret into your .env.
.env
GITHUB_CLIENT_ID=your_github_client_id_here
GITHUB_CLIENT_SECRET=your_github_client_secret_here

API Reference

All endpoints require a Bearer JWT token in the Authorization header. Tokens are issued on login and expire after 7 days.

POST/api/v1/analyze

Analyze a GitHub issue and generate a contribution roadmap.

bash
curl -X POST http://localhost:5000/api/v1/analyze \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/owner/repo/issues/123"}'
json
{
  "success": true,
  "data": {
    "analysisId": "uuid",
    "issueTitle": "...",
    "repoName": "owner/repo",
    "difficulty": "Medium",
    "estimatedFixTime": "2-4 hours",
    "explanation": "Technical root cause...",
    "roadmapSteps": [...],
    "diffs": [...],
    "confidenceScore": 75
  }
}
GET/api/v1/analyses

List all analyses for the authenticated user.

bash
curl http://localhost:5000/api/v1/analyses \
  -H "Authorization: Bearer <your_jwt_token>"
GET/api/v1/analyses/:id

Get a specific analysis by ID.

bash
curl http://localhost:5000/api/v1/analyses/<analysis_id> \
  -H "Authorization: Bearer <your_jwt_token>"

Security

JWT authenticationAll API requests require a valid Bearer token.
Password hashingbcrypt with 10 rounds for email/password accounts.
OAuth 2.0Secure third-party auth via Google and GitHub.
Rate limiting100 requests per 15 minutes per IP.
Input validationAll inputs validated with Zod schemas.
SQL injectionParameterized queries via the pg library.
CORSRestricted to the frontend origin only.
Helmet.jsSecurity headers enabled by default.
Never commit your .env file. Rotate JWT_SECRET and SESSION_SECRET regularly. All OAuth secrets should be stored as environment variables in production.

Ready to contribute?

Start analyzing issues and shipping PRs with confidence.