Wallhaven Random (pi extension)

A pi extension that:

• adds a get_random_wallpaper tool (pulls wallpapers from wallhaven.cc)
• supports extension-level defaults (global + project override)
• can show wallpapers while pi is working
• supports static and rotate working-image effects (with fade transition + preload of next image)

Features

• Tool: get_random_wallpaper
  • fetches wallpaper metadata + inline preview image
  • returns wallhaven page URL + full image URL
• Config layering
  • global config: ~/.pi/agent/extensions/wallhaven-random.json
  • project config: <repo>/.pi/extensions/wallhaven-random.json
  • project config overrides global config
• Interactive config command
  • /wallhaven-settings
  • /wallhaven-settings global
  • /wallhaven-settings show
• Thinking-time wallpaper widget
  • shows below editor while agent is running
  • workingImageEffect: "static" | "rotate"
  • in rotate, the next wallpaper is preloaded before fade/swap
  • rotate interval has minimum of 5000ms

Requirements

• pi with extension support
• terminal with image support for best experience (Kitty/Ghostty/WezTerm/iTerm2)
  • non-image terminals will gracefully show text fallback
• Wallhaven API key is optional for many SFW searches, but recommended
  • especially for NSFW/sketchy use cases

Repository contents

• wallhaven-random.ts - extension entry file
• wallhaven-random.example.json - sample config

Install

1) Clone this repo

git clone <YOUR_REPO_URL> wallhaven-random-pi-extension
cd wallhaven-random-pi-extension

2) Install globally (all projects)

Create extension + config directories if needed:

mkdir -p ~/.pi/agent/extensions

Copy extension:

cp wallhaven-random.ts ~/.pi/agent/extensions/wallhaven-random.ts

Copy default config (optional):

cp wallhaven-random.example.json ~/.pi/agent/extensions/wallhaven-random.json

Then run /reload in pi.

3) Install per-project (only current repo)

From your project root:

mkdir -p .pi/extensions
cp /path/to/wallhaven-random-pi-extension/wallhaven-random.ts .pi/extensions/wallhaven-random.ts
cp /path/to/wallhaven-random-pi-extension/wallhaven-random.example.json .pi/extensions/wallhaven-random.json

Then run /reload in pi.

4) Symlink workflow (easy updates)

If you prefer not copying files:

mkdir -p ~/.pi/agent/extensions
ln -sf /absolute/path/to/wallhaven-random-pi-extension/wallhaven-random.ts ~/.pi/agent/extensions/wallhaven-random.ts
ln -sf /absolute/path/to/wallhaven-random-pi-extension/wallhaven-random.example.json ~/.pi/agent/extensions/wallhaven-random.json

Now edits in this repo are picked up after /reload.

API key setup

You can set the key in either place:

Option A: environment variable (recommended)

export WALLHAVEN_API_KEY="your_api_key_here"

Add to your shell profile (~/.zshrc or ~/.bashrc) for persistence.

Option B: config file

~/.pi/agent/extensions/wallhaven-random.json (or project override):

{
  "apiKey": "your_api_key_here"
}

Verify in pi:

/wallhaven-settings show

You should see apiKey: set.

Configuration reference

Example:

{
  "apiKey": "<optional>",
  "query": "nature mountains",
  "searchType": "general",
  "purity": "sfw",
  "searchMode": "random",
  "topRange": "1M",
  "ratios": "16x9,21x9",
  "atleast": "1920x1080",
  "page": 1,
  "showWhileWorking": true,
  "workingImageEffect": "rotate",
  "rotateIntervalMs": 5000,
  "fadeDurationMs": 350
}

Keys

• searchType: general | anime | people | all
• purity: sfw | sketchy | nsfw
• searchMode: random | date_added | views | favorites | toplist
• topRange: 1d | 3d | 1w | 1M | 3M | 6M | 1y (toplist only)
• rotateIntervalMs: 5000..60000
• fadeDurationMs: 100..3000

Usage

In pi chat:

• “Get me a random wallpaper”
• “Use get_random_wallpaper with query=cyberpunk city, searchType=anime, purity=sfw”
• “Show me today’s toplist with 21:9 wallpapers”

Interactive settings:

• /wallhaven-settings (project)
• /wallhaven-settings global
• /wallhaven-settings show

Troubleshooting

No image shown, only text

Your terminal likely doesn’t support inline images. The extension still works; only rendering is downgraded.

NSFW/sketchy request fails

Set WALLHAVEN_API_KEY and ensure your Wallhaven account/API settings allow requested purity.

Extension not loading

• confirm file path is exactly one of:
  • ~/.pi/agent/extensions/wallhaven-random.ts
  • .pi/extensions/wallhaven-random.ts
• run /reload
• check for TypeScript syntax errors

Rotating too fast/slow

Adjust rotateIntervalMs in config. Minimum clamp is 5000 ms.

Update

If copied:

cp wallhaven-random.ts ~/.pi/agent/extensions/wallhaven-random.ts

Then /reload.

If symlinked, just pull latest and /reload.

Uninstall

Global uninstall:

rm -f ~/.pi/agent/extensions/wallhaven-random.ts
rm -f ~/.pi/agent/extensions/wallhaven-random.json

Project uninstall:

rm -f .pi/extensions/wallhaven-random.ts
rm -f .pi/extensions/wallhaven-random.json

Then /reload.