Metadata-Version: 2.4
Name: grokfeed
Version: 0.3.0
Summary: Hacker News + Reddit + lobste.rs terminal feed viewer
Project-URL: Homepage, https://github.com/emarkou/grokfeed
Project-URL: Repository, https://github.com/emarkou/grokfeed
Project-URL: Issues, https://github.com/emarkou/grokfeed/issues
Author-email: Eleni Markou <eamarkou@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Eleni Markou
        
        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.
License-File: LICENSE
Keywords: feed,hacker-news,lobsters,reddit,terminal,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Terminals
Requires-Python: >=3.11
Requires-Dist: click>=8.0.0
Requires-Dist: httpx[http2]>=0.27.0
Requires-Dist: textual>=0.47.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Description-Content-Type: text/markdown

<div align="center">

<img src="docs/img/grokfeed.png" alt="grokfeed" width="500"/>


**Terminal feed reader for Hacker News, Reddit, and lobste.rs.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://img.shields.io/pypi/v/grokfeed)](https://pypi.org/project/grokfeed/)
[![Python versions](https://img.shields.io/pypi/pyversions/grokfeed)](https://pypi.org/project/grokfeed/)
[![GitHub release](https://img.shields.io/github/v/release/emarkou/grokfeed)](https://github.com/emarkou/grokfeed/releases/latest)
[![CI](https://img.shields.io/github/actions/workflow/status/emarkou/grokfeed/ci.yml?branch=main&label=CI)](https://github.com/emarkou/grokfeed/actions/workflows/ci.yml)

</div>

## Features

- Unified scrollable feed from HN, Reddit subreddits, and lobste.rs
- Color-coded by source: HN orange, lobste.rs red, subreddits in a cycling palette
- Read text posts and Ask HN inline — no browser needed
- Split view with post body and threaded comments side by side
- Filter feed by source, refresh on demand, paginate with `m`
- Config file at `~/.grokfeed/config.toml` — created automatically on first run

## Install

### Homebrew (macOS/Linux)

```bash
brew tap emarkou/grokfeed
brew install grokfeed
```

### pip

```bash
pip install grokfeed
```

### pipx (isolated install)

```bash
pipx install grokfeed
```

### From source

Requires Python 3.11+.

```bash
git clone https://github.com/emarkou/grokfeed.git
cd grokfeed
pip install -e .
```

---

On first run, a config file is created at `~/.grokfeed/config.toml`. Edit it to change subreddits:

```bash
nano ~/.grokfeed/config.toml
```

```toml
subreddits = ["programming", "ClaudeAI", "machinelearning"]
hn_story_count = 30
reddit_post_count = 15
lobsters_post_count = 25
cache_ttl_minutes = 10
```

Run `grokfeed` — changes take effect on next launch or press `r` to refresh.

## Demo

![Demo](demo.gif)

## Key bindings

### Main feed

| Key | Action |
|-----|--------|
| `j` / `↓` | Move down |
| `k` / `↑` | Move up |
| `Enter` | Open post + comments split view |
| `f` | Cycle source filter (All → HN → r/sub → lobste.rs → …) |
| `m` | Load more stories |
| `r` | Refresh all sources |
| `q` | Quit |

### Split view

| Key | Action |
|-----|--------|
| `j` / `↓` | Scroll down |
| `k` / `↑` | Scroll up |
| `Tab` | Switch between post and comments pane |
| `o` | Open URL in browser |
| `q` / `Esc` | Close |

## Config

`~/.grokfeed/config.toml` — created on first run with defaults.

| Key | Default | Description |
|-----|---------|-------------|
| `subreddits` | `["programming", "python", "machinelearning"]` | Subreddits to include |
| `hn_story_count` | `30` | HN stories per fetch |
| `reddit_post_count` | `15` | Posts per subreddit per fetch |
| `lobsters_post_count` | `25` | lobste.rs posts per fetch |
| `cache_ttl_minutes` | `10` | Minutes before refreshing cache |

## Tech stack

| Library | Role |
|---------|------|
| [Textual](https://github.com/Textualize/textual) | TUI framework |
| [httpx](https://www.python-httpx.org/) | Async HTTP client |
| [Click](https://click.palletsprojects.com/) | CLI entry point |

---
Related posts: 
- https://dev.to/elemar/building-a-terminal-feed-reader-for-hacker-news-reddit-and-lobsters-with-python-textual-2alf
