Standard Installation:

• Windows: MrRSS-{version}-windows-amd64-installer.exe / MrRSS-{version}-windows-arm64-installer.exe
• macOS: MrRSS-{version}-darwin-universal.dmg
• Linux: MrRSS-{version}-linux-amd64.AppImage / MrRSS-{version}-linux-arm64.AppImage

Portable Version (no installation required, all data in one folder):

• Windows: MrRSS-{version}-windows-{arch}-portable.zip
• Linux: MrRSS-{version}-linux-{arch}-portable.tar.gz
• macOS: MrRSS-{version}-darwin-{arch}-portable.zip

AI Agent Skills:

• Codex: MrRSS-{version}-skills.zip (usage guide)

Prerequisites

Before you begin, ensure you have the following installed:

• Go (1.27 or higher)
• Node.js (20 LTS or higher with npm)
• Wails v3 CLI

Platform-specific requirements:

• Linux: GTK4, WebKitGTK 6.0, libsoup 3.0, GCC, pkg-config
• Windows: MinGW-w64 (for CGO support), NSIS (for installers)
• macOS: Xcode Command Line Tools

For detailed installation instructions, see Build Requirements

# Quick setup for Linux (Ubuntu 24.04+):
sudo apt-get install libgtk-4-dev libwebkitgtk-6.0-dev libsoup-3.0-dev gcc pkg-config

Installation

1. Clone the repository

   git clone https://github.com/DevXDojo/MrRSS.git
   cd MrRSS
   

2. Install frontend dependencies

   cd frontend
   npm install
   cd ..
   

3. Install Wails v3 CLI

   go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha2.117
   

4. Build the application

   # Using Task (recommended)
   task build
   
   # Or using Makefile
   make build
   
   # Or directly with wails3
   wails3 build
   

   The executable will be created in the build/bin directory.

5. Run the application

   • Windows: build/bin/MrRSS.exe
   • macOS: build/bin/MrRSS.app
   • Linux: build/bin/MrRSS

Normal Mode (default):

• Windows: %APPDATA%\MrRSS\ (e.g., C:\Users\YourName\AppData\Roaming\MrRSS\)
• macOS: ~/Library/Application Support/MrRSS/
• Linux: ~/.local/share/MrRSS/

Portable Mode (when portable.txt exists):

• All data stored in data/ folder

This ensures your data persists across application updates and reinstalls.

Running in Development Mode

Start the application with hot reloading:

# Using Wails v3
wails3 dev

# Or using Task
task dev

Code Quality Tools

Using Make

We provide a Makefile for handling common development tasks (available on Linux/macOS/Windows):

# Show all available commands
make help

# Run full check (lint + test + build)
make check

# Clean build artifacts
make clean

# Setup development environment
make setup

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality:

# Install hooks
pre-commit install

# Run on all files
pre-commit run --all-files

Running Tests

make test

Local API and Server Mode

The desktop app exposes its REST API at http://localhost:1234/api while it is running. The listener is restricted to the local computer.

For server deployments and API integration, use the headless server version:

# Using Docker (recommended)
docker run -p 1234:1234 mrrss-server:latest

# Or build from source
go build -tags server -o mrrss-server .
./mrrss-server

Pre-built server images based on ghcr.io are also available:

docker run -d -p 1234:1234 ghcr.io/devxdojo/mrrss:latest-amd64
docker run -d -p 1234:1234 ghcr.io/devxdojo/mrrss:latest-arm64

For browser access and local setup, see Browser interface.

Please refer to the Server Mode API Documentation for a complete API reference. To let Codex operate MrRSS through this API, install the release skill package described in MrRSS Skills.

Before contributing:

1. Read the Code of Conduct
2. Check existing issues or create a new one
3. Fork the repository and create a feature branch
4. Make your changes and add tests
5. Submit a pull request