add-skill-freshrss

Add FreshRSS

Configures RSS feed access for agent containers using a self-hosted FreshRSS instance and its Google Reader API.

Preflight

Before installing, verify NanoTars is set up:

[ -d node_modules ] && echo "DEPS: ok" || echo "DEPS: missing"
docker image inspect nanoclaw-agent:latest &>/dev/null && echo "IMAGE: ok" || echo "IMAGE: not built"
if grep -q "ANTHROPIC_API_KEY\|CLAUDE_CODE_OAUTH_TOKEN" .env 2>/dev/null || [ -f "$HOME/.claude/.credentials.json" ]; then echo "AUTH: ok"; else echo "AUTH: missing"; fi

If any check fails, tell the user to run /nanotars-setup first and stop.

Prerequisites

• A self-hosted FreshRSS instance with API access enabled

Step 1: Check Existing Configuration

grep "^FRESHRSS_URL=" .env 2>/dev/null && echo "ALREADY_CONFIGURED" || echo "NEEDS_SETUP"
ls plugins/freshrss/plugin.json 2>/dev/null && echo "PLUGIN_EXISTS" || echo "NO_PLUGIN"

If ALREADY_CONFIGURED, ask the user if they want to reconfigure or test the existing setup.

Step 2: Gather FreshRSS Details

Ask the user for:

1. FreshRSS URL -- the base URL of their instance (e.g. https://freshrss.example.com), no trailing slash
2. FreshRSS username -- the login username (e.g. admin, fruity)
3. FreshRSS API password -- this is NOT the web login password

Tell the user:

To get your FreshRSS API password:

1. Log in to your FreshRSS instance
2. Go to Settings (gear icon) > Profile
3. Scroll to API Management
4. Set an API password if you haven't already, then click Submit
5. Copy the API password and paste it here

Wait for the user to provide all three values.

Step 3: Save to .env

# Remove existing lines if present
sed -i '/^FRESHRSS_URL=/d' .env
sed -i '/^FRESHRSS_USER=/d' .env
sed -i '/^FRESHRSS_API_KEY=/d' .env

# Add FreshRSS credentials
echo 'FRESHRSS_URL=THE_URL_HERE' >> .env
echo 'FRESHRSS_USER=THE_USERNAME_HERE' >> .env
echo 'FRESHRSS_API_KEY=THE_API_KEY_HERE' >> .env

Step 4: Install Plugin

cp -r ${CLAUDE_PLUGIN_ROOT}/files/ plugins/freshrss/

Step 5: Plugin Configuration

Ask the user which groups should have access to this plugin:

• All groups (default) -- every group's agent can use this
• Specific groups only -- e.g., only main

If restricting, update plugins/freshrss/plugin.json to set "groups" to the list of group folder names.

Also ask about channel types. Leave "channels": ["*"] for all, or set to specific types (e.g., ["whatsapp"]).

Step 6: Test the API Connection

source .env
AUTH=$(curl -s "$FRESHRSS_URL/api/greader.php/accounts/ClientLogin" \
  -d "Email=$FRESHRSS_USER&Passwd=$FRESHRSS_API_KEY" | grep -oP 'Auth=\K.*')

if [ -n "$AUTH" ]; then
  UNREAD=$(curl -s "$FRESHRSS_URL/api/greader.php/reader/api/0/unread-count?output=json" \
    -H "Authorization: GoogleLogin auth=$AUTH" | python3 -c "
import sys, json
r = json.load(sys.stdin)
total = sum(int(f.get('count', 0)) for f in r.get('unreadcounts', []))
print(f'OK - {total} unread articles')
")
  echo "$UNREAD"
else
  echo "FAILED - Could not authenticate. Check URL, username, and API password."
fi

If the test fails:

• Empty auth token: Wrong username or API password (not the web login password)
• Connection refused: Check FreshRSS URL and that the instance is running
• 404: FreshRSS API may not be enabled -- check Settings > Authentication > Allow API access

Step 7: Build and Restart

npm run build
nanotars restart  # or launchctl on macOS

Verify

Send a WhatsApp message like "what's in my RSS feeds?" or "give me a news summary".

Existing Installation (Per-Group Credentials)

If this plugin is already installed and you want different credentials for a specific group (e.g., a work account for one group, personal for another):

1. Check which groups exist:

   ls -d groups/*/
   

2. Ask the user which group should get separate credentials.

3. Collect the new FreshRSS credentials for that group.

4. Write to the group's .env file (creates if needed):

   echo 'FRESHRSS_URL=https://other-freshrss.example.com' >> groups/{folder}/.env
   echo 'FRESHRSS_USER=username' >> groups/{folder}/.env
   echo 'FRESHRSS_API_KEY=api-key' >> groups/{folder}/.env
   

   These values override the global .env for that group's containers only.

5. Restart NanoTars:

   nanotars restart
   

Remove

1. rm -rf plugins/freshrss/
2. Remove env vars from .env:

   sed -i '/^FRESHRSS_URL=/d' .env
   sed -i '/^FRESHRSS_USER=/d' .env
   sed -i '/^FRESHRSS_API_KEY=/d' .env
   

3. Rebuild and restart