# Project pack: FreshRSS @ 9e38e2e

Facts about **FreshRSS** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> FreshRSS is a self-hosted RSS and Atom reader. You subscribe to websites, blogs, podcasts and even pages without feeds, and read everything in one place with filters, labels, search and keyboard shortcuts. It is light enough for a small server and works with many phone apps.

## Version and source
- Repository: https://github.com/FreshRSS/FreshRSS
- Pinned commit: `9e38e2e405aa6276697493c0b4c4f64e3c734e22`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/FreshRSS/FreshRSS/archive/9e38e2e405aa6276697493c0b4c4f64e3c734e22.zip
- Official docs: https://freshrss.github.io/FreshRSS
- Live demo: https://demo.freshrss.org/i/. Shared demo. Don't enter real data.
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/FreshRSS/FreshRSS bespoke-freshrss
  cd bespoke-freshrss
  git checkout --detach 9e38e2e405aa6276697493c0b4c4f64e3c734e22
  # Prepare development requirements and local configuration first.
  php -S localhost:8080 -t ./p
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --restart unless-stopped --log-opt max-size=10m -p 8080:80 -e TZ=Europe/Paris -e CRON_MIN=1,31 -v freshrss_data:/var/www/FreshRSS/data -v freshrss_extensions:/var/www/FreshRSS/extensions --name freshrss freshrss/freshrss
  # then open http://localhost:8080
  ```

- Needs: Docker for a trial, PHP 8.1+ with a web server for development
- Develop: `php -S localhost:8080 -t ./p`
- Test: `make test-all`
- Check/lint: `make lint`
- Stack: php, javascript (Minz (own PHP framework), vanilla JavaScript). Difficulty for a non-developer with an AI: **easy**. Plain PHP with its own small framework and no build step for the app. Extensions and themes are a folder with a few files, which makes it one of the easier apps to personalise.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`.

## Customisation points (settings → extend → code)
- **feeds-and-categories** [settings]: Subscriptions, categories, labels and filters. → `In the app, under Subscription management`
- **reading-options** [settings]: Layout, sorting, shortcuts and article actions. → `Configuration → Reading and Display`
- **extensions** [extend]: Add features such as save-to-Wallabag, image proxy or custom scripts. → `extensions/ (see the official extension repository)`
- **themes** [extend]: Colours and layout. → `p/themes/`
- **xpath-and-html-feeds** [settings]: Follow sites that have no RSS feed. → `Subscription → Advanced → web scraping`
- **php-core** [code]: Core features. → `app/ and lib/`

## Must keep working
- Feed fetching and refresh scheduling.
- Database migrations and the OPML import and export.
- API compatibility with mobile apps (Google Reader and Fever APIs).

## Staying updatable
Write an extension or theme in its own folder. Then upgrading FreshRSS needs no merging.

## Data, costs and safety
- Personal data: **yes**. Stored in: A database (SQLite by default) in the data folder. Your subscriptions and read history are personal. Export an OPML backup regularly.
- Setting `TZ`: Your time zone so refresh times make sense.
- Setting `CRON_MIN`: Minutes of each hour when feeds are refreshed.
- Keep it behind a login. Public instances can be abused.
- Extensions run code on your server. Install only trusted ones.

---

# Customising FreshRSS

FreshRSS is plain PHP. The AGENTS.md in the repo explains the project's conventions. Extensions and themes are the best way in.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Controllers, models and views | app/Controllers/, app/Models/, app/views/ |
| Libraries | lib/ |
| Extensions | extensions/ (one folder per extension, with metadata.json and extension.php) |
| Themes | p/themes/ |
| Command-line tools | cli/ |
| Translations | app/i18n/ |
| Tests | tests/ |

## Use the gentlest change first

1. **Settings (no code):** feeds, categories, filters, reading options and web scraping.
2. **Extend:** extensions and themes.
3. **Code:** the PHP core.

## Recipes

- **New extension:** create a folder in `extensions/`, add `metadata.json` and `extension.php` with an `init()` that registers hooks, then enable it in Configuration → Extensions.
- **New theme:** copy a theme folder, change its CSS and register it in the theme list.

## Running and checking your changes

- `make test-all` and `make lint` run the PHP and style checks.
- Subscribe to two feeds, refresh, mark as read and search.
- Export OPML and import it back.

## Pitfalls

- Keep the data folder out of Git.
- Add translation keys for new text in every language file you can, or at least English.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/freshrss/9e38e2e/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/freshrss/9e38e2e/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/freshrss/9e38e2e/r2/SKILL.md)