{"id":28450106,"url":"https://github.com/appwiz/hns","last_synced_at":"2026-05-09T19:36:12.774Z","repository":{"id":293805937,"uuid":"985180533","full_name":"appwiz/hns","owner":"appwiz","description":"Hacker News stories CLI. Stories summarized using Ollama and a local LLM.","archived":false,"fork":false,"pushed_at":"2025-05-28T20:24:39.000Z","size":835,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-08T23:48:39.609Z","etag":null,"topics":["cli","copilot","gemma3","hackernews","langchain","ollama","rust-lang","vibe-coding"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/appwiz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-17T08:17:33.000Z","updated_at":"2025-05-19T03:38:13.000Z","dependencies_parsed_at":"2025-05-17T09:36:26.708Z","dependency_job_id":null,"html_url":"https://github.com/appwiz/hns","commit_stats":null,"previous_names":["appwiz/hns"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/appwiz/hns","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appwiz%2Fhns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appwiz%2Fhns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appwiz%2Fhns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appwiz%2Fhns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appwiz","download_url":"https://codeload.github.com/appwiz/hns/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appwiz%2Fhns/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32833347,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","copilot","gemma3","hackernews","langchain","ollama","rust-lang","vibe-coding"],"created_at":"2025-06-06T15:06:30.339Z","updated_at":"2026-05-09T19:36:12.768Z","avatar_url":"https://github.com/appwiz.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hns - Hacker News Stories CLI\n\nA command-line interface for fetching and displaying top stories from Hacker News.\n\n`hns` is a simple, fast Rust command-line tool that pulls top stories from the official Hacker News API and displays them in a clean, readable format. The tool shows story titles, authors, timestamps, text content, and URLs in a structured way, making it easy to browse Hacker News without leaving your terminal.\n\n## Features\n\n- Fetch and display the top stories from Hacker News\n- Configurable number of stories to display\n- Clean formatting with proper handling of HTML content\n- Special handling for \"Show HN\" posts\n- Proper decoding of HTML entities\n- AI-powered URL summarization using Ollama's gemma3:4b model\n\n## Example\n```\n% hns --summarize\n```\n![displays how summarization works](hns-summarize.png)\n\n## Installation\n\nEnsure you have Rust and Cargo installed. Then:\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/hns.git\ncd hns\n\n# Build and install\ncargo install --path .\n```\n\n### Summarization Dependencies\n\nTo use the `--summarize` feature, you need to have Ollama running with the gemma3:4b model installed:\n\n1. [Install Ollama](https://ollama.ai/) following the official instructions\n2. Pull the gemma3:4b model:\n```bash\nollama pull gemma3:4b\n```\n3. Ensure Ollama is running before using the `--summarize` flag\n```bash\n# Start Ollama (keep running in a separate terminal)\nollama serve\n```\n\n## Usage\n\nRun the tool with default settings (shows 5 top stories):\n\n```bash\nhns\n```\n\n### Command-line Arguments\n\n| Argument | Short | Description | Default | Range |\n|----------|-------|-------------|---------|-------|\n| `--max-stories` | `-m` | Maximum number of stories to display | 5 | 1-25 |\n| `--summarize` |  | Enable URL summarization using gemma3:4b model | false | - |\n| `--help` | `-h` | Display help information | - | - |\n| `--version` | `-V` | Display version information | - | - |\n\n#### Examples\n\nDisplay the top 10 stories:\n\n```bash\nhns -m 10\n```\n\nDisplay the maximum number of stories:\n\n```bash\nhns --max-stories 25\n```\n\nDisplay stories with URL summaries:\n\n```bash\nhns --summarize\n```\n\nDisplay 10 stories with URL summaries:\n\n```bash\nhns -m 10 --summarize\n```\n\n## Output Format\n\nFor each story, the tool displays:\n\n1. A separator line\n2. Timestamp, author, and story ID\n3. Story title\n4. For \"Show HN\" posts: URL followed by text content (if available)\n5. For regular posts: Text content (if available) or URL\n\n## Development\n\n### Prerequisites\n\n- Rust 1.70.0 or higher\n- Cargo\n\n### Development Tools\n\nThe project includes several files to help with development:\n\n- `Makefile` - Common development tasks (run `make help` for details)\n- `CHANGELOG.md` - Track changes between versions\n- `CONTRIBUTING.md` - Guidelines for contributors\n\n### Dependencies\n\n- `clap` - Command-line argument parsing\n- `reqwest` - HTTP client for API requests (and Ollama API calls)\n- `tokio` - Asynchronous runtime\n- `serde` - JSON serialization/deserialization\n- `serde_json` - JSON serialization/deserialization for Ollama API\n- `chrono` - Timestamp formatting\n- `scraper` - HTML parsing\n- `ego-tree` - Tree data structure for HTML parsing\n- `html2text` - HTML to text conversion for URL content\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/hns.git\ncd hns\n\n# Build in debug mode\ncargo build\n\n# Build in release mode\ncargo build --release\n```\n\n### Running Tests\n\n```bash\ncargo test\n```\n\n### Release Process\n\nThis project uses GitHub Actions for continuous integration and deployment. The workflow automatically:\n\n1. Tests the codebase\n2. Builds binaries for multiple platforms (Linux, macOS Intel/ARM, Windows)\n3. Creates GitHub releases with packaged artifacts when tags are pushed\n4. Publishes to crates.io when a new version is tagged\n\nTo create a new release:\n\n```bash\n# 1. Update the version in Cargo.toml\n# 2. Commit the changes\ngit add Cargo.toml\ngit commit -m \"Bump version to x.y.z\"\n\n# 3. Tag the commit\ngit tag -a vx.y.z -m \"Release version x.y.z\"\n\n# 4. Push to GitHub with tags\ngit push \u0026\u0026 git push --tags\n```\n\n\u003e **Note:** To enable publishing to crates.io, you must set the `CRATES_IO_TOKEN` secret in your GitHub repository settings.\n\n## API\n\nThis tool uses the official Hacker News API:\n- https://github.com/HackerNews/API\n\n## License\n\nThis project is licensed under the BSD 3-Clause License - see the [LICENSE.md](LICENSE.md) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappwiz%2Fhns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappwiz%2Fhns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappwiz%2Fhns/lists"}