Metadata-Version: 2.4
Name: grokfeed
Version: 0.2.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

# grokfeed

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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


## 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
- Comments viewer with nested replies (up to 2 levels)
- Filter feed by source, refresh on demand
- Config file at `~/.grokfeed/config.toml` — created automatically on first run

## Install

### Homebrew (recommended)

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

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
```

Changes take effect on next launch or press `r` to refresh.

### From source

Requires Python 3.11+. Recommended: use [uv](https://github.com/astral-sh/uv).

```bash
# with uv
uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install -e .

# or plain pip (Python 3.11+)
pip install -e .
```

## Run

```bash
grokfeed
```

## Screenshots

![Feed](docs/screenshots/feed.png)

![Post body](docs/screenshots/post.png)

![Comments](docs/screenshots/comments.png)

## Key bindings

### Main feed

| Key | Action |
|-----|--------|
| `j` / `↓` | Move down |
| `k` / `↑` | Move up |
| `Enter` | Open post body (text posts) or URL in browser (link posts) |
| `c` | Open comments |
| `f` | Cycle source filter (All → HN → r/sub → lobste.rs → …) |
| `r` | Refresh all sources |
| `q` | Quit |

### Post body modal

| Key | Action |
|-----|--------|
| `j` / `↓` | Scroll down |
| `k` / `↑` | Scroll up |
| `c` | Open comments for this post |
| `o` | Open URL in browser |
| `q` / `Esc` | Close |

### Comments modal

| Key | Action |
|-----|--------|
| `j` / `↓` | Scroll down |
| `k` / `↑` | Scroll up |
| `q` / `Esc` | Close |

## Config

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

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

Edit to add or remove subreddits. Changes take effect on next launch or `r` refresh.

## Tech stack

| Library | Role |
|---------|------|
| [Textual](https://github.com/Textualize/textual) | TUI framework |
| [httpx](https://www.python-httpx.org/) | Async HTTP client |
| [Typer](https://typer.tiangolo.com/) | CLI entry point |
| [Rich](https://github.com/Textualize/rich) | Text rendering |
