@reddapi/dsh-reddit-radar

A dsh plugin that periodically scans
reddapi.dev for new Reddit leads matching a one-sentence
ICP description, drops the ones you've already seen, and writes the new ones
to a dated markdown report in your workspace. It also forwards reddapi.dev's
six read-only search/lookup MCP tools so the agent can query Reddit on demand
between runs.

What it's reading

Why this beats a keyword alert

Keyword alerts return thousands of irrelevant mentions and still miss the ones
that matter, because people asking for what you sell rarely use your words for
it. Nobody writes "I need a Reddit lead-gen tool for B2B SaaS". They write "how
do you all find customers without spending on ads".

reddapi.dev matches on meaning, not spelling. Your ICP sentence is embedded
into the same 1024-dimensional space as every indexed post, so a post lands in
your report when it means the same thing, whether or not a single keyword
overlaps. On top of that sits intent scoring: every lead is scored 0-100 on
signal strength and auto-tagged with lead type, sentiment and industry, so
what reaches your report is the handful of people ready to buy rather than
everyone who happened to say a word. The demo set on reddapi.dev's homepage
averages a 96% intent score.

That is the whole point of the scheduled scan in this plugin: you write one
sentence about who you sell to, and a dated markdown file appears with the
people who described that problem this week, in their own words, with a link
to reply.

What it does

• Scheduled lead scan. On a cadence you pick (weekly / daily / hourly
  / manual), it calls reddapi.dev's /api/v1/leads with your ICP as the
  query, filters out leads it has already reported, and writes the rest to
  <outDir>/<date>.md.
• A manual tool, reddit_radar_run, that runs one pass immediately instead
  of waiting for the schedule.
• Six forwarded tools — reddit_semantic_search, reddit_vector_search,
  reddit_list_subreddits, reddit_get_subreddit, reddit_get_trends,
  reddit_find_leads — thin shells over reddapi.dev's own MCP endpoint, so the
  agent can search Reddit directly instead of only seeing scheduled digests.
• A one-line notice at the start of the next session when a run found new
  leads, hit a quota wall, or the API key was rejected.

Install

npm install @reddapi/dsh-reddit-radar

Then add it to your cordis.yml (see the full example below).

⚠️ Three things you must know before configuring this

1. days has to track schedule, or you'll re-scan the same week forever

The default is schedule: weekly with days: 7 — each run looks at the last
7 days of Reddit activity, and the next run is roughly 7 days later, so the
scanned windows line up back-to-back.

If you tighten schedule to daily (or hourly), you must shrink days
to match (days: 1 for daily). If you leave days: 7 while running daily,
every single run re-scans the same rolling week — you'll see mostly leads
you already reported, and burn quota re-fetching data you've already seen.
days only accepts 1 | 7 | 30 | 90 (reddapi.dev's whitelist); pick the value
closest to your actual cadence.

2. Free-tier quota is shared with MCP tool calls — 3 per 7 days, not per month

Free reddapi.dev accounts now have full API access, same as every paid tier,
so a free account's key works with /api/v1/leads and this plugin out of the
box — no subscription required.

What free accounts get instead of a blanket block is a small, shared
quota: 3 requests per fixed 7-day window — the window resets every
Thursday 00:00 UTC. This is not a calendar month and not a rolling
window. That pool is
shared across the reddapi.dev website search UI, every /api/v1/* endpoint,
/api/leads, and MCP tools/call — i.e. one counter for everything you do
with a free key.

At the default weekly / days: 7 cadence, radar's own scheduled scan
consumes 1 request per window. What the rest of the pool goes to is
entirely up to you — the counter does not care where a call came from.

⚠️ This is the part most likely to bite you: the six forwarded MCP tools
(below) count against this same pool. MCP protocol methods —
initialize, tools/list, resources/list, prompts/list — are free
handshake calls and don't consume quota, but every actual tools/call
does — including reddit_semantic_search, reddit_find_leads, and the
other four tools this plugin forwards. If your agent calls even two or three
of them in one conversation, that alone can burn through the entire 3-per-week
free allowance. The next scheduled radar run in that window will then fail
with a 429 (see Troubleshooting) instead of writing a report. That is the
mechanism, not a recommendation — how you spend the three requests is your
call, just know that scheduled scans and ad-hoc tool calls draw down the
same counter. Paid plans
(Lite and above) have much larger, plan-specific monthly/daily quotas with no
such shared-with-MCP collision risk — see
reddapi.dev/pricing.

3. There is no "every Monday at 9am" — only a cadence tier + heartbeat

dsh 0.1.0-rc.6 doesn't give third-party plugins a cron facility. The only
scheduling primitive a plugin can use is a fixed-interval timer — there's no
cron expression and no wall-clock target time.
(@deepseek-ai/dsh-schedule looks like it might fill that gap, but it's
actually an agent-scoped, session-level "remind me" tool bound to a
specific root agent's event log — not something a plugin can register a
background job against.)

So schedule: weekly doesn't mean "every Monday at 09:00" — it means a
cadence tier plus a persisted heartbeat: every hour (or every tick, if the
tier is shorter than an hour), the plugin checks how long it's been since the
last run and only runs if that's ≥ the tier's duration. Consequences:

• Restarting the host process does not trigger an extra run — the last
  run time is persisted and survives restarts (in the host's own storage when
  available, or a .state.json file in outDir otherwise).
• If the host was off for a while, the next heartbeat after startup will catch
  up with exactly one run (not one run per missed tick).
• The actual time-of-day a weekly run lands on will drift with whenever the
  host happens to be running when a tick lands ≥7 days after the last run —
  it is not pinned to a specific day or hour.

If you need a run at a specific time, use schedule: manual and trigger
reddit_radar_run yourself (e.g. from your own external cron hitting the
agent, or via dsh-schedule's session-level reminders).

Config reference

Full cordis.yml example

- id: reddit-radar
  name: '@reddapi/dsh-reddit-radar'
  config:
    apiKey: rk_live_xxxxxxxxxxxxxxxx   # get one at https://reddapi.dev (Account → API Keys)
    icp: We sell a Reddit lead-gen tool to B2B SaaS founders
    schedule: weekly                  # weekly | daily | hourly | manual
    days: 7                           # 1 | 7 | 30 | 90 — keep in sync with `schedule`
    outDir: .dsh/reddit-radar
    maxPerRun: 10

Get an API key at reddapi.dev — log in and open
/account; a key is minted automatically, free accounts included. See
"Free-tier quota is shared with MCP tool calls" above for what a free key can
realistically sustain (3 requests / 7-day window, shared with the six
forwarded MCP tools) versus a paid plan's larger, unshared quota.

A weekly scan costs 1 search per week, so any paid tier leaves the rest of the
month's quota for the agent's own ad-hoc searches. Current figures live at
reddapi.dev/pricing.

Forwarded MCP tools

These six tools are registered as thin shells that forward directly to
https://reddapi.dev/api/mcp's tools/call, reusing the same apiKey from
your config. Their argument schemas are pulled live from reddapi.dev's own
tools/list at plugin startup — this plugin does not hardcode or duplicate
them, so they can't drift out of sync with the live API:

Each call to one of these six tools is a tools/call against
reddapi.dev's MCP endpoint, which on a free account draws from the same
3-per-7-days pool as the scheduled radar scan itself — see "Free-tier quota
is shared with MCP tool calls" above. initialize/tools/list (used once at
plugin startup to fetch the schemas) are free protocol handshakes and don't
count.

If reddapi.dev's tool list can't be fetched at startup — network hiccup,
a rejected apiKey (invalid, mistyped, or revoked — not a plan-tier issue
anymore, every plan including Free has API access), or reddapi.dev being
briefly unreachable — these six tools are simply not registered for that
session. This is silent by design past a single warning: the scheduled
radar (the plugin's actual job) does not depend on them and keeps running
normally either way. If you don't see these tools available, check that
apiKey is valid and reddapi.dev is reachable, then reload the plugin.

Troubleshooting

401/403 and 429 mean very different things to this plugin, and it handles
them very differently — don't treat them as the same "it's broken" signal.

"your reddapi.dev quota is used up" (429) — the common one on a free account

All plans, including Free, have API access now, so a correctly-configured
key normally never sees a 401/403 at all. What a free account is much more
likely to hit is a 429: the shared 3-per-7-days quota (see "Free-tier
quota is shared with MCP tool calls" above) ran out — usually because the
six forwarded MCP tools were used in the same 7-day window as the scheduled
radar scan.

This plugin treats a 429 as a quota problem, not an auth error, and does
not stop the timer for it. The scheduled radar keeps ticking; the next
run (per your schedule cadence) will simply try again, and by the time a
weekly run comes back around the 7-day quota window has normally reset
anyway. Nothing needs to be reloaded or
reconfigured. The on-screen notice text ("...Upgrade at
reddapi.dev/pricing to resume") is shared boilerplate with paid-plan
overages — on a free account, upgrading is optional, not required: waiting
for the next 7-day window resets the same 3 requests for free. Upgrade only
if you want the radar scan and the six MCP tools to stop competing for the
same small pool.

"the configured reddapi.dev API key was rejected" (401/403) — schedule stopped

This is the notice reddit-radar shows after an actual 401 or 403 from
/api/v1/leads. Unlike a 429, this plugin treats both as one auth-error
outcome and deliberately stops the timer, so it doesn't keep failing forever
in the background. Since every plan tier now has API access, this is
essentially always a genuine credential problem, not a plan issue:

1. Check for a typo, extra whitespace, or a key that was rotated/revoked in
   the account dashboard.
2. Confirm the key was copied from the same reddapi.dev account you expect —
   /account mints one key per account.
3. Once the key is fixed, reload the plugin — the timer was torn down and
   won't come back on its own; a config reload re-registers it. (A 429 never
   requires this step — only 401/403 tears the schedule down.)

Development

npm install
npm test          # vitest, 69 cases
npm run build      # tsc -p tsconfig.build.json → dist/

The pure decision logic (which leads are new, what a run outcome means, how a
report gets rendered) has no dsh or network dependency and is unit-tested in
isolation; a separate suite covers the scheduling/heartbeat/tool-registration
wiring against a minimal fake host; another verifies the actual build output
loads under real Node ESM (not just that the build exits cleanly).