Documentation

A quiet tech feed for your coding agents.

WaitFeed shows a rotating tech-news card while Claude Code, OpenCode, or Antigravity works. It disappears at idle. No LLM calls, API keys, or server.

3 hosts/4 channels/0 tokens
Install
$npx waitfeed init

Quickstart

One command wires every supported host. Start an agent, then read while it works.

1

Run the setup wizard

WaitFeed detects installed hosts, lets you choose agents and channels, stages each integration, and writes the shared config. Re-running is safe.

npx waitfeed init
2

Start an agent

Open Claude Code, OpenCode, or agy and give it a task. WaitFeed stays hidden until the agent starts working.

3

Read while it works

The card rotates above the prompt or in the statusline. Open /feed for the reader; press Ctrl+N in Claude Code or Ctrl+O in OpenCode to hide the card.

First fetch
A fresh install can stay empty for a few seconds while the first fetch cycle lands.

How it works

The pipeline is shared. Renderers only read the cache, and each host decides when the card is visible.

01
Sources
4 built-ins + RSS
02
Fetch cycle
30-min baseline
03
Shared cache
90 items · 36 h
04
Host gate
busy → show

Refresh

A fresh cache suppresses fetching for 30 minutes. Below 5 unread items, the pipeline refills early — at most once a minute.

Retention

Up to 90 items are carried for 36 hours, so a dead source never empties the rotation.

Locking

cycle.lock serializes concurrent hosts. A lock older than 10 minutes is stolen by the next run.

Visibility modes

ModeBehavior
auto
Shows the card only while the agent works.
hide
Keeps the card off, even mid-run.
show
Legacy alias of auto. It cannot pin the card at idle.
No LLM in the loop
Descriptions come from the feeds themselves. Items with thin descriptions are dropped rather than padded, and no prompt, API key, or model call is involved.

Claude Code

AbovePrompt band card and a /feed reader pane.

Appears in
Claude's AbovePrompt band, gated on the host's own isWorking state.
Read more
Type /feed for a reader pane: ↑/↓ move, Enter opens and marks read, Esc closes.
Toggle
Ctrl+N toggles just the card mid-run. init binds it unless the key is already taken.
Requires
Claude Code v2.1.295 or later.
  • The card disappears when the turn ends, when Claude waits on you, or when you press Esc.
  • init stages the scheduler and mod into ~/.claude/waitfeed/ and writes the SessionStart hook.
  • Re-running init prunes older WaitFeed statusline entries; foreign hooks stay untouched.

OpenCode

Above-prompt card and a native /feed popup.

Appears in
The composer's top slot, directly above the prompt, while the agent executes.
Read more
Type /feed. OpenCode's native popup handles search and scrolling; choose the Sources row to toggle channels.
Toggle
Ctrl+O hides or restores the card during a run. The dismissal lasts the current turn.
Requires
OpenCode with the v2 plugin API.
  • The TUI renders from cache.json; it never fetches feeds itself.
  • At idle, the prompt and footer stay completely untouched.
  • A disabled channel is not contacted by the next fetch cycle.
opencode.jsonc
{
"plugins": ["waitfeed"]
}

Antigravity

Statusline card for active agent states.

Appears in
The Antigravity statusline while agent_state is working, tool_use, or reviewing.
Read more
Ctrl+Click a headline link to open it. On macOS, use Cmd+Click.
Toggle
AGY has no keybinding API. Run npx waitfeed toggle (or hide / show / auto) from any shell.
Requires
Google Antigravity with the agy statusline.
  • Splash, idle, error, and unknown states print nothing.
  • init stages the statusline bundle and points ~/.gemini/antigravity-cli/settings.json at it.
  • The card shares the same cache and channel settings as the other hosts.

Channels

Four built-in sources, all enabled by default. Each one uses the same card format and shared cache.

Hacker News

Top stories and discussions from news.ycombinator.com.

news.ycombinator.com

Dev.to

Practical posts, tutorials, and writeups from dev.to.

dev.to

GitHub Trending

Repositories created in the last 7 days, ranked by stars.

github.com

Reddit r/programming

Community threads from reddit.com/r/programming.

reddit.com/r/programming

Turn channels on or off

  • In OpenCode, open /feed and choose the Sources row. Selecting a channel saves immediately.
  • From any host, edit sources in config.json. A disabled channel is not contacted by the next fetch.
  • All four are on by default; custom RSS feeds are configured separately.
RSS is a badge, not a channel
Custom feeds always run when configured. There is no fifth built-in channel toggle for RSS.

Custom feeds

Add RSS or Atom URLs for engineering blogs, newsletters, and release notes.

Put up to 10 URLs in rssUrls. They always run and render with the RSS badge.

~/.config/waitfeed/config.json
{
"rssUrls": [
"https://overreacted.io/rss.xml",
"https://jvns.ca/atom.xml"
]
}
  • The setup wizard accepts one URL; edit config.json for the rest.
  • Both RSS and Atom work. A failing feed is skipped, and cached items keep the rotation full.
  • Items with thin descriptions are dropped rather than padded.

config.json

One shared file at ~/.config/waitfeed/config.json. Hosts read it; init writes it.

~/.config/waitfeed/config.json
{
"setupDone": true,
"sources": {
"hn": true,
"devto": true,
"github": true,
"reddit": true
},
"rssUrls": [],
"dwellSeconds": 20,
"newsMode": "auto"
}
KeyTypeDefaultNotes
setupDone
boolean
false
Onboarding flag. init writes true; OpenCode also sets it when it saves a channel switch.
sources
object
all true
Per-channel switches: hn, devto, github, reddit.
rssUrls
string[]
[]
RSS or Atom URLs. Values beyond 10 are ignored.
dwellSeconds
number
20
Seconds each card stays while the agent works. Clamped to 5–120.
newsMode
"auto" | "show" | "hide"
"auto"
Default visibility. show is a legacy alias of auto; nothing renders at idle.
newsModes
object (optional)
—
Per-host overrides: opencode, claude, agy.
Safe to hand-edit
Unknown keys and invalid values fall back to defaults. A half-written file cannot break the ticker.

Local data

Everything lives in ~/.config/waitfeed/. Nothing is sent anywhere.

FileRoleHoldsLifetime
~/.config/waitfeed/config.json
Settings
Channels, RSS URLs, dwell time, and visibility modes.
Until removed
~/.config/waitfeed/cache.json
Story cache
Fetched items shared by every host.
90 items · 36 h
~/.config/waitfeed/reader-state.json
Reader history
read and glanced marks used to avoid repeats.
36 h
~/.config/waitfeed/cycle.lock
Fetch lock
Serializes fetch cycles across hosts.
Stolen after 10 min
  • The cache and reader history are shared by every host on the machine.
  • The only network calls are to the feed URLs you keep enabled.
  • npx waitfeed remove deletes this folder; --keep-data leaves it in place.

CLI

Run commands with npx, or install the package globally. The same switches work from any shell.

CommandWhat it does
npx waitfeed init
Detect installed hosts, choose agents and channels, stage integrations, and write config. Re-running is safe.
With no command, the CLI also runs init.
npx waitfeed show [host]
Restore the card: visible while the agent works.
show is an alias of auto.
npx waitfeed hide [host]
Force the card off, even mid-run.
npx waitfeed toggle [host]
Flip between hide and auto.
npx waitfeed auto [host]
Return to busy-only behavior.
npx waitfeed remove
Remove integrations and delete ~/.config/waitfeed/.
--keep-data keeps settings and cache.
npx waitfeed --version
Print the installed package version.

Host is one of opencode, claude, or agy. Omit it to change every host.

FAQ

Short answers about behavior, privacy, and removal.

WaitFeed is quiet at idle. Start a task in your agent and give the first fetch a few seconds. If you previously ran npx waitfeed hide, run npx waitfeed show or toggle.
No. There is no LLM call, no API key, and no telemetry. WaitFeed reads feed URLs and writes local files; it never reads your prompts or source files.
Yes. All hosts share ~/.config/waitfeed/. One fetch cycle fills the cache, and cycle.lock keeps concurrent hosts from racing.
Add up to 10 RSS or Atom URLs to rssUrls. The setup wizard accepts one URL; edit config.json for the rest. Custom items show the RSS badge.
Yes. npx waitfeed hide claude writes newsModes.claude; the other hosts keep their own mode.
No. auto and show only render while the agent is busy; hide forces it off. Every host is quiet when idle.
npx waitfeed remove removes WaitFeed's entries and staged files from each host, then deletes ~/.config/waitfeed/. Add --keep-data to keep the data folder. Other plugins and hooks are untouched.
Unknown keys and invalid values are ignored; missing values fall back to defaults. A hand-edited file cannot break the ticker.

MIT-licensed. Local-first. No accounts, API keys, or telemetry.