Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
The ship log: release notes joined to the code that shipped them
Every project keeps two records of the same work.
The commit log is complete and unreadable. The changelog is readable and incomplete. On three.ws both are published, both are pushed to the community Telegram channel, and until now neither knew the other existed. The same afternoon's work reached the same channel twice, in two voices, with nothing saying it was the same work.
The ship log is the join. Live at three.ws/ship, served as data at /api/ship/feed, and computed by an open-source package, @three-ws/shipfeed, that works on any repository.
It answers two questions no changelog and no git log can answer alone:
- Which commits produced this release note?
- What shipped that nobody ever wrote up?
How it works
GitHub /repos/nirholas/three.ws/commits public/changelog.json
(through fetchUpstream: deadline, (baked into the running
retry, breaker, last-good) image by every deploy)
│ │
└──────────────┬───────────────────────────┘
▼
@three-ws/shipfeed
parse ──▶ classify ──▶ link ──▶ group ──▶ render
│
┌──────────────┼───────────────────────┐
▼ ▼ ▼
/api/ship/feed /ship page the community Telegram lanes
(JSON, MD, RSS) (provenance footer + noise filter)
1. Parse
Full Conventional Commits 1.0.0, plus revert subjects, GitHub's merge subjects, and git trailers. feat(resilience): ... becomes a headline a reader can parse ("Feature · resilience") instead of the raw type prefix the commit feed used to print. A subject that follows the older Avatar Studio: 122 sliders house style keeps that convention; a subject with no convention at all is reported honestly rather than mangled.
2. Classify
Each commit gets an audience and a signal score from 0 to 1, with a reason attached to every point:
| audience | who it is for |
|---|---|
holder |
someone who uses or owns a piece of the product |
developer |
someone who builds against it |
internal |
someone who works on it |
Merge commits, chore(deps): bumps, and lockfile-only changes come back noise: true.
3. Link
Provenance without metadata. A Changelog: <slug> trailer in the commit always wins, and almost no commit has one, so the fallback has to earn its answer from four signals:
- A time window. A release note is written the day its work lands, so only commits within
windowDays(default 4, plus one day of lead) are candidates. - IDF-weighted term overlap. Shared rare words ("meshopt", "settle", "fingerspelling") carry weight; shared common ones ("agent", "the", "fix") carry almost none. The similarity blends how much of the entry a commit covers with how much of the commit the entry contains, so a one-line commit can still explain a paragraph.
- Tag agreement. An entry tagged
fixprefers afix:commit. - Proximity. Same-day work outranks work three days out.
A commit belongs to at most one entry; an entry may claim many. On this repository the default threshold (0.26) links roughly two thirds of visible commits, and the reasons behind every link are published with it.
4. Group
Everything unclaimed is clustered into ships: bursts of commits separated by 90 minutes of quiet, each headlined by its own strongest commit. That section is the interesting one. It is the work that shipped and was never announced.
The page
three.ws/ship renders the whole feed:
- four live counters (commits read, release notes, percentage linked to code, unannounced work) and a daily-commit sparkline
- an audience filter: everything, developers, or product news only
- every release note with its commits folded underneath, each showing its short sha, headline, audience, and a
why 41%control that expands the exact reasons the link was made - an Unannounced section for the ships nothing claimed
The API
GET /api/ship/feed
Public, no auth, cached for 5 minutes.
If GitHub cannot be read (rate limit or outage) and an earlier response exists, the endpoint serves that last-good feed (kept up to 24 hours) with "stale": true instead of failing.
| param | values | default |
|---|---|---|
limit |
1 to 500 commits | 200 |
audience |
holder, developer, internal |
internal (everything) |
format |
json, markdown, rss |
json |
explain |
a 7 to 40 character commit sha | none |
curl -s 'https://three.ws/api/ship/feed?limit=100&audience=holder' | jq '.stats'
{
"commits": 100,
"hidden": 22,
"releases": 24,
"linked": 53,
"orphans": 25,
"coverage": 0.679,
"byAudience": { "holder": 62, "developer": 27, "internal": 11 },
"velocity": [{ "date": "2026-08-27", "count": 61 }]
}
Each release carries its commits, and each linked commit carries the receipt:
{
"shortSha": "2771f41",
"headline": "Feature · forge",
"summary": "three more independent concept-image rungs",
"audience": "holder",
"signal": 0.86,
"confidence": 0.41,
"why": ["shared terms: painter, concept, providers", "type \"feat\" matches tag", "before the entry by 0.4d"]
}
GET /api/ship/feed?explain=<sha>
One commit's full reasoning: every scoring rule that fired, and the release note it was attached to (or a plain statement that nothing claimed it).
curl -s 'https://three.ws/api/ship/feed?explain=65f3fe5' | jq '.classification.reasons'
A heuristic nobody can interrogate is a heuristic nobody should trust, which is why this endpoint exists alongside the feed.
Feed formats
curl -s 'https://three.ws/api/ship/feed?format=markdown' > RELEASES.md
curl -s 'https://three.ws/api/ship/feed?format=rss' # a feed reader, with commits inline
What changed in the Telegram channel
Two lanes post to the community channel, and they now share this one join.
Release announcements (/api/cron/changelog-push, every 20 minutes) carry a provenance footer:
Update: Text-to-3D now has five independent image sources behind it
Every text-to-3D generation starts by painting a concept image...
shipped in 4 commits ← links to the GitHub compare view for the range
three.ws/changelog/2026-08-27-text-to-3d-... · 2026-08-27 · #fix #infra
The footer is best-effort by design: if GitHub cannot be read at that moment, the announcement goes out without it rather than not going out. Entries are keyed by date and title, and repeats of one key within a batch are collapsed before sending, so a duplicated line in data/changelog.json never reaches the channel twice.
The same cron also replies to the @trythreews X thread with every entry that passes data/changelog-x-filter.json (no wallet, payment, key, outage or security internals, and nothing that is only a fix). That lane is isolated from Telegram, so one failing never blocks the other, and its tweets carry no provenance footer: just the title, summary and changelog link inside the 280-character budget.
The raw commit feed (/api/cron/commit-feed-push, every 5 minutes) reads its headline from the same parser, so a scoped commit now says "Feature · resilience" rather than "feat(resilience)", and it skips commits the classifier calls noise: merges, chore(deps): bumps, and lockfile-only changes. A skipped commit still advances the lane's state, so nothing is ever re-read, and the tick reports { posted, skipped } so the drop is visible in the logs rather than silent. If GitHub's rate limit is exhausted the lane returns { skipped: 'github_rate_limited' } and retries on the next tick (a 200, not an error). Any other failure reading GitHub answers 502 { ok: false, error } and releases the lane lock; state lives in app_settings, so the next tick resumes where this one stopped.
Use it on your own repository
The package is standalone and dependency-free.
npx @three-ws/shipfeed --repo your/repo --changelog https://your.site/changelog.json
npx @three-ws/shipfeed explain <sha>
npx @three-ws/shipfeed stats
npx @three-ws/shipfeed --local --markdown > RELEASES.md
import { shipfeed } from '@three-ws/shipfeed';
const feed = await shipfeed({
repo: 'your/repo',
changelogUrl: 'https://your.site/changelog.json',
productScopes: ['checkout', 'search'],
});
The full reference, including the linking internals exported for tuning, is in the package README.
Where the code lives
| Piece | File |
|---|---|
| The package | packages/shipfeed/ |
| Feed endpoint | api/ship/feed.js |
| Provenance for the changelog lane | api/_lib/ship-provenance.js |
| The page | public/ship/index.html |
| Release announcements | api/_lib/changelog-push.js |
| Raw commit feed | api/_lib/commit-feed-push.js |
Known limits
- GitHub's unauthenticated rate limit is 60 requests an hour per IP. Set
GITHUB_TOKENon the service to raise it. Without one, a busy hour leaves the feed serving its last-good copy (markedstale), the commit-feed lane skipping ticks, and the Telegram footer absent. - Linking is a heuristic, and it publishes as one. Every link carries a confidence and its reasons; a release note that legitimately found no code says so on the page rather than silently showing nothing.
- A commit older than the window can never be linked, however well it matches. That is deliberate: the alternative is a note claiming work from a month it had nothing to do with.