PUSHD(1)PUSHD manualPUSHD(1)
~/pushd$man pushd

How it works.

Seven parts, plain words. What PUSHD does, how fast it is, and where it stops.

01  THE WATCHER

It reads public GitHub activity.

PUSHD ranks crypto token projects by their public GitHub activity every hour and watches the 25 most active right now, out of 140 in the pool. It only reads what anyone can already see. Anyone else on GitHub can still be looked up on demand.

Each check is a conditional request. When nothing changed, GitHub answers "304, not modified" and the check costs nothing against the rate limit. That lets PUSHD ask often.

  • new repos
  • first pushes and pushes
  • releases
  • public gists
  • renamed or newly public repos
github.com public activitywatcher top 25filter + heat scoreone line -> the feedIf-None-Match304 = freeask again~95% droppedbumps, CI, typos+ link + heat
fig 1. the loop, the 25 most active projects
02  THE HEAT SCORE

Heat is a guess, shown as a bar.

Most activity is boring: dependency bumps, CI changes, typo fixes. About 95% is dropped before it reaches the feed.

What is left gets points for things that tend to get shared: a new repo, a fun name, words like coin or token, images, a joke README, a first push after a long silence. The total becomes a bar from low to very high.

lowmediumhighvery high
kept . @kaiwren / frog-oracle . Sample
new repo+3
fun name+2
joke README+2
emoji in the description+2
heat 9/10very high
dropped . Sample
chore: bump deps to 4.2.1drop
ci: fix workflow cachedrop
fix typo in READMEdrop
03  THE SUMMARIES

One plain line, from the repo only.

A small AI model reads the README, the file names and the first commit, then writes one line a non-developer can read.

It is told to use only what is in the repo. When there is little to go on, the line says less, not more. Every line comes with the link, so you can check it yourself in one tap.

in: README.mdSample
# frog-oracle
Ask it a price. It answers in frogs.
This is a joke. Please do not use it for anything.
| pushd summarize --one-line
out: feed linekept
A price feed that answers in frog emojis, as a joke.
04  THE 5 MINUTE DELAY

The public feed runs 5 minutes behind.

Everyone gets the same lines and the same summaries. The public site shows them 5 minutes after the watcher does.

$PUSHD holders sign in with MetaMask and see the feed live, with their own watchlist and browser alerts. Holding is read from the chain. Nothing is paid or staked.

What holders get
T+0push landsT+ seconds to 1 minholders see it+5:00 laterpublic sees it5 min public delay
fig 2. one push, two views
05  HONEST LIMITS

Where it stops.

PUSHD is fast, not magic. These are the limits, said plainly.

E_LAG

A few seconds to a minute behind

GitHub's public activity has its own delay, and PUSHD reads each project in turn: the most active every 2 min with a GitHub token, the rest less often. Without a token, GitHub allows so few requests that reads are hours apart.

E_RATE

GitHub sets limits

GitHub limits how often anyone can ask. Conditional requests keep most checks free, but a very busy hour can slow things down.

E_SCOPE

Public, and the list first

PUSHD watches public activity of the list as it happens. Anyone else is read only when someone looks them up. Private repos are out of view.

E_GUESS

Heat and summaries can be wrong

Heat is a score from simple signals. Summaries come from the repo's own words or a small AI model and can miss the point. Always open the link.

06  FEEDS AND WIDGET

Take the public feed anywhere.

The same lines as the public site, with the same 5 minute delay: as RSS for any reader, as JSON Feed for your own tools (PUSHD's fields are under _pushd), and as a small widget for any web page.

The widget takes a few options in its address: how many lines (n, 3 to 20), one camp (group), a heat floor (heat) and a light theme.

embed.htmlpaste anywhere
<iframe
  src="https://pushd.fun/embed?n=6&heat=medium"
  width="380" height="480"
  style="border:0;border-radius:12px"
  title="PUSHD feed"></iframe>
terminalJSON Feed 1.1
$ curl -s https://pushd.fun/feed.json | jq '.items[0].title'
"toly created dts02-6502-signer"
07  KEYBOARD

Built for the keyboard.

Ctrl K (or /) opens a palette that jumps to any builder, repo or page. On the feed, j and k move through the lines and o opens one. g then a letter goes to a page, t flips the theme, s turns the sound mode on or off, and ? lists them all.

Sound mode is off until you turn it on: a soft tick for each new line, a brighter one for hot lines. It is remembered in this browser only.

keysanywhere on the site
Ctrl K  search and jump
j / k   next / previous line
o       open the line
g f     feed        g p  pulse
g r     replay      g b  brief
g c     catches     g w  top 100
t       theme       s    sound
?       all of them