Metadata-Version: 2.4
Name: gh-issue-lens
Version: 0.1.0
Summary: Find beginner-friendly GitHub issues and export them as JSONL for LLM analysis.
Author-email: Mohammad El-Shennawy <mohamedwork216@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Mohammad El-Shennawy
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/MohamedM216/gh-issue-lens
Project-URL: Repository, https://github.com/MohamedM216/gh-issue-lens
Project-URL: Issues, https://github.com/MohamedM216/gh-issue-lens/issues
Keywords: github,open-source,issues,llm,cli,developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Dynamic: license-file

# Easier open source contribution process for newcomers

Stop digging through stale GitHub issues. **gh-issue-lens** finds unassigned, beginner-friendly open source issues in any repository and prepares them for LLM analysis in seconds. It bypasses API rate limits by grabbing issues, linked Pull Requests, assignees, and non-bot comments in a single network pass.

# How to use it?

## Option 1: Install from PyPI

```bash
pip install gh-issue-lens
```
**Export your GitHub Personal Access Token:**

First of all, create your personal github token from your github account then use it.

```bash
export GITHUB_TOKEN="your_personal_access_token"
```

**Fetch issues:**

```bash
gh-issue-lens kubernetes kubernetes -d 200
```

**Filter by labels:**

```bash
gh-issue-lens kubernetes kubernetes -l "good first issue" "help wanted" -d 50
```

And for more commands, you can see the sections below. The guidelines are the same. The only difference is to use `gh-issue-lens` directly instead of `python3 cli.py`.

## Option 2: Build it manually

**Clone the repo:**

```bash
git clone https://github.com/MohamedM216/gh-issue-lens.git
```

**Install requirements:**

```bash
pip3 install requests
```

**Export your GitHub Personal Access Token:**

First of all, create your personal github token from your github account then use it.

```bash
export GITHUB_TOKEN="your_personal_access_token"
```

**Verify it works:**

```bash
cd src/gh_issue_lens/
python3 cli.py --help
```

**Fetch 100 issues from a repository:**

100 issues is the default depth you can change it using the -d option.

```bash
python3 cli.py kubernetes kubernetes
```

### Filter by up to 5 labels (ORed) and set a depth limit:

This fetches a maximum of 50 issues that have EITHER the "good first issue", "help wanted", or "bug" label.

```bash
python3 cli.py kubernetes kubernetes -l "good first issue" "help wanted" "bug" -d 50
```

### Save to a custom JSON file:

If you want to use a custom name for the output file, you can run:

```bash
python3 cli.py kubernetes kubernetes -l "feature" -d 10 -o custom_dataset.json
```

### Incremental Saving & Resumability (Checkpointing):

When scraping massive repositories (like Kubernetes), hitting GitHub's API rate limits or network timeouts is common. You no longer have to worry about losing your progress!
* **JSONL Format:** Issues are now saved line-by-line instantly as they are fetched, ensuring zero data loss.
* **Auto-Resume:** The tool creates a hidden `.checkpoint` file tracking your progress. If the script crashes or you stop it, simply run the **exact same command** again. It will automatically resume from the exact page it left off, saving your API budget and time.

### Exclude issues with open PRs:

```bash
python3 cli.py kubernetes kubernetes --exclude-open-prs
```

### SQLite caching:

`gh-issue-lens` can cache already-exported issues in a local SQLite database. This prevents duplicate issues from being written again when you run the same export multiple times.

Enable caching:

```bash
python3 cli.py kubernetes kubernetes -d 200 --cache
```

By default, the cache is stored in `.gh_issue_lens_cache.db`. Use a custom cache database:

```bash
python3 cli.py kubernetes kubernetes -d 200 --cache --cache-db my_cache.db
```

Run again with caching enabled. Issues that were already exported in previous runs will be skipped. You can also enable early stopping when the tool keeps finding only cached issues:

```bash
python3 cli.py kubernetes kubernetes -d 200 --cache --cache-stop
```

This is useful when re-running the tool against the same repository and you only want newly discovered issues. To reset the cache, delete the cache file:

```bash
rm .gh_issue_lens_cache.db
```

Caching is different from checkpointing: checkpointing helps resume a crashed or interrupted run, while caching helps avoid exporting the same issues again across separate runs.

## What's next?

The generated JSON file is suitable to be used as context for Large Language Models (like Gemini, Claude, or ChatGPT). You can upload the output file to an LLM and use targeted prompts to find the perfect issue to work on.

**Example Prompts to try:**

> "I am a newcomer to this repository. Based on the attached JSON, find an issue that is easy to implement, has no active PRs, and doesn't have a long, debated comment history."

> "Filter these issues and list only the ones related to [backend / frontend / database / specific component]."

> "Read the comments on these issues. Which maintainers seem the most responsive and welcoming to beginners? Point me to issues authored or reviewed by them."

> "Summarize the technical requirements for issue #123 based on its description and comment thread. What files should I look at first?"

*Don't forget to STAR the repository :)*

*Happy hacking!*
