Kitpicks

Custom Source Scripts

Kitpicks lets you add a custom source by providing an ingestion binary — a small executable that generates Markdown. The binary is registered with the reservoir and run periodically so its output appears in your feed alongside regular RSS sources.

Security warning

Your ingestion binary will be run periodically and autonomously with access to your machine. Only drop binaries you trust. Do not install binaries from untrusted sources.

How it works

In the Add Source screen, switch to the Custom script tab and drop your executable. Kitpicks registers it with the reservoir, creates a source for it, and the reservoir runs it on its fetch schedule. Every Markdown file the binary writes to its outs/ directory becomes a content item.

If the script's name collides with an existing custom source, the Add Source screen flags the conflict and links you to edit the existing source instead of creating a duplicate.

Updating a script

To update an existing custom source's binary, open its Edit Source screen and re-drop the new executable. The updated binary replaces the script in place, so the source keeps its name and continues to be fetched on the same schedule.

The executable contract

  • The binary must be executable (the executable bit is set).
  • It is launched from a fresh temporary directory containing an outs/ folder.
  • The RES_CHANNEL_ID environment variable is set to the channel id.
  • Extra fetch parameters are passed as key=value CLI arguments.
  • Write one .md file per item into outs/. Optional supplementary files go in a same-named subdirectory.

Frontmatter requirements

Each Markdown file's frontmatter should include a pubDate so the item becomes a Kitpicks entry. A url is optional — when omitted, the entry links to the item's own Markdown file (as a file:// link). The title frontmatter property (or the first # Heading in the body) is used as the entry title.

Example

A minimal Node script that writes one Markdown file to outs/: 

#!/usr/bin/env node
import { writeFileSync, mkdirSync } from "node:fs";
import { join } from "node:path";

mkdirSync("outs", { recursive: true });

const item = `---
url: https://example.com/weather/2026-09-02
pubDate: 2026-09-02T12:00:00Z
title: Today's Weather
---

Sunny with a high of 72°F.
`;

writeFileSync(join("outs", "weather.md"), item);

See the working example at res/examples/weather-fetcher.mjs in the repository.

Agents authoring ingestion binaries can also fetch the guide at skills.md.