The feed

A per-viewer read model of what happened on the forge, ranked, each item with one sentence saying why it is there.

GET /api/v1/feed?limit=&cursor= → { items, next_cursor }, for the signed-in viewer only. An item is { id, kind, app, actor, at, link, what, reason, score }; kind is run | ask | pull | decision | map | cost | tell | reply | look | milestone | choose | release. what is the post in its own words; reason the sentence for why it is there. Strings are plain text, not HTML: whatever renders them escapes them. The MCP tool feed { limit, cursor } answers the same.

POST /api/v1/feed/interactions { item, kind, app? } records what the viewer did (opened dwelled steered told swiped shipped shared dismissed muted). Same-origin checked for browser sessions, rw for tokens. An event: item names its own repo and actor; any other item names its app as owner/name. Anything the viewer cannot read is a 404.

Where items come from (src/feed/items.ts)

(a deploy, check or agent run; a costly agent run is a cost item, shown only to those who may see owner facts), pull.opened|merged|reviewed, look.taken (a look: a full set of pictures), app.serving, issue.blocked|unblocked (map changes), issue.opened (a tell, in its title's words; see Bursts fold) and issue.commented|pull.commented (a reply, in its own words).

item each and only when there is something new: how far it is and what merged since they last opened it, that it landed, or that it was dropped or split. Its id carries its progress, so the item is replaced, never repeated, as the milestone moves. Not muted with its app.

decision item for each of their origins that needs re-authorizing with mirrors behind it ("octo at codeberg.org needs re-authorizing; 2 mirrors are frozen"), and one for each of their mirrors whose origin was disconnected ("alice/widgets is frozen; reconnect its origin"). Each goes the moment it is fixed (docs/ORIGINS.md, "When a token expires").

Runs already announce themselves on the outbox (run.*); looks did not, so look.taken was added.

Bursts fold (src/feed/fold.ts)

When one author opens 3 or more issues in one repository within 2 minutes, foldBursts replaces them with one post, planned N issues in owner/name, ranked where the newest would be and linking to the repository's map. The first 3 titles ride on it as lines ({ text, link }), the rest as more; the web card draws them as a .list of rows, MCP feed and GET /api/v1/feed return them. One or two issues keep their own posts. The fold runs after the viewer's filters and before paging, so chip counts and cursors see the folded posts. A new kind of burst is a row in FOLDS.

Ranking (src/feed/rank.ts, affinity.ts)

score = urgency + 1.5·affinity + recency − repeats. Urgency: asks 6–10, a failed run 4. Recency halves every 6 hours. Affinity is a decayed count (half-life 7 days) per app and per actor, seeded from ownership, pins, crew, the viewer's own merges/proposals/tells and ledger outcomes, then moved by interactions; a dismissal is −4, a mute −8 and hides the app. Each item already placed from the same app costs 1.2, from the same actor 0.6. The reason is the sentence for the largest term; for every kind it is one plain sentence, never empty, at most 120 characters, with no raw id in it (plainWords in plain.ts swaps an id for "an id", and a long plain number stays; boundReason, test/feed-reasons.test.ts).

Muting hides an app's items except asks: what waits on a person is never muted away. Dismissing hides one item. The cursor is score|id of the last item; the feed is recomputed per request and resumes by id (or by score if that item has gone).

The page (src/web/studio/feed.ts)

/ for a signed-in viewer is the feed (#599): the composer on top (a tell to one of your apps; through the outbox to POST /api/v1/feed/tells, or POST /tell without a script), then the first 20 items as posts, server-side; your apps and what is on you in a narrow column on a desk, a tab away on a phone. The app rows and the cost line are /apps. /live/feed answers the timeline region for the live-regions client (etag, 304). A post: who did it, what it says as a link into the thing, a small line of why, Steer (run cards, posts to the run's steer) or Tell the crew (everything else, posts to the app's tell), Dismiss and Mute app (the interactions API, same-origin). Reply (#8211): a post whose link is an issue or a pull (/:owner/:name/issues/:n or /pulls/:n) also offers Reply, a plain form posting the comment to that page's own /comments handler with back=feed, so the same-origin check, body limit and escaping apply; it returns to /feed with the flash "Reply posted." (a fixed word, never a URL from the form); an empty or refused reply returns there too, with the reason. Reply is the card's one primary button; Tell drops to plain beside it. Only a signed-in viewer who can read the repository sees it (src/feed/reply.ts, the comment action's own rule). In the terminal, Feed in the palette lists the same posts and r replies through the same addCommentThrough. Keys: j/k/Enter are the shell's, x dismisses the focused card. The choose card comes from src/feed/choose.ts, a run card offers Stop (src/web/studio/cards.ts), and ?cursor= pages past the first 20 (src/web/studio/feed.ts).

Offline (src/web/sw.ts, outbox.ts)

kept copy when the network fails, with data-stale="1" so the note above the feed says "Offline: this feed is from 12 min ago". The stylesheet, /assets/ and icons are cache-first. Nothing else is touched: the API, /events, /live/ and every POST go to the network. Signing out clears the cache and the outbox.

localStorage (200 at most), each with an Idempotency-Key made when it is queued, and are flushed on open, on online and after each add. No Background Sync (Safari has none). Entries leave on any 2xx or a final 4xx; a network error, 5xx, 408, 429 or 401 keeps them in order.

to the person (as tokens' are to the token): a replay returns the first answer. POST /api/v1/feed/tells { app, text } (answers { issue, says }) is the JSON tell the outbox sends. from (optional) is the page the tell was told from: a path on this forge, at most 512 characters; anything else is a 400 invalid_from and opens nothing. The issue reads "Told from <link>". variants (an integer, 1 to 4; anything else is a 400 and opens nothing) opens that many issues from the one tell, each handed to a builder run, all in one server-made group their pulls carry (variant_group), kept when a run is queued again. With more than one, the 201 also carries issues (the numbers opened), assigned (those handed to a builder) and variantGroup; a plain tell has none of the three.

on the stream, and on online, and refreshes every region once.

updating the kept / from live swaps (it is the page as last navigated), swipes (no swipe UI yet), push, and anything native.

Sharing (src/feed/share.ts, core/shares.ts)

POST /api/v1/share { item, to?, note? } (rw, same-origin for sessions) and the MCP tool share are one verb. to is up to 10 usernames. The sender must see the item (it is looked up in the sender's own feed sources); the answer is { sent: [{ to, outcome }] }, outcome one of delivered queued steered told duplicate skipped unreachable. A name that does not exist and one who may not see the item are both unreachable.

only if none of those is someone else, the people who pinned the app (inside the org when an org owns it). A named target is always added.

very item among their own candidates, or they are unreachable.

told (an issue routed to a builder) through the existing actions, as the sender, so the sender's own rights apply.

boosted by 3 × sender weight; it replaces the plain item. Their mute of the app makes the share skipped; dismissing the item hides the share.

best-weighted first as room frees (checked on each feed read), and dropped after 48 hours; a waiting share's worth falls linearly with its age.

shares to people, clamped 0.2–2; an open is the recipient's opened of the item or its share. A sender nobody opens sinks, a trusted one rises.

Clearing what is on you in one move

The home's one On you list (what asks you, and what is assigned to you) takes a set: tick boxes, or Select all, a kind, or a repository, then one verb for all of it — close (one reason, written on each as "Closed: …"), mute (the repository goes quiet in your feed and On you; asks are never muted away), ship, or on asks decline (dismiss) and hand back. It is one POST /api/v1/asks/bulk (action, items, reason, preview: false); items are ask ids (assigned:<id> for something assigned to you; issue:<id> still names one). The list swaps in place and the top bar's count follows. One undo link (POST /api/v1/asks/bulk/<id>/undo) is kept for a day. The MCP's asks_act takes the same set, verb and reason; it also undoes, with action: undo and operation (a dry run refuses an operation that is not yours with not_found), and returns the same receipt sentence.

The composer keeps your draft

What you type in the home composer is saved in the browser's localStorage (per signed-in user and page, at most once a second) and is back after a reload. Sending clears it; a send the forge refuses puts the words back and keeps them; signing out clears every draft. It lives in the feed's existing script (no new script, no dependency). Not covered: the "the forge" thought target posts as a plain form, so its draft is dropped on submit, and the lean client home has no feed script, so no draft.

Likes

A like is a signal written to the decision ledger (#7751, #10389), the same for a person and an agent. Every like or unlike is one row of feed_signal (who, what, when; seq orders them), never edited and never deleted. Taking a like back is a new unlike row; asking for the state already held (a second like) writes nothing and answers the same. feed_like is the current state, kept in step in the same transaction (setLike in src/feed/likes.ts), so a post's likes equals ledgerCount for it; test/feed-like.test.ts asserts that after a like, an unlike and a repeat.

Doors, all through setLike and the readInteraction check: the Like button (POST /feed/like, a same-origin form carrying act = like or unlike), POST /api/v1/feed/interactions with kind: "liked" or "unliked", and the MCP tool feed_like ({ item, act: like | unlike | history }). A write needs a session with a same-origin POST, or a token with rw scope; an anonymous caller gets 401 naming /signin; a token meets the ordinary per-token rate limit, so an agent cannot flood likes.

To read it back: GET /api/v1/feed/likes?item=event:… (or feed_like with act: "history") answers { item, ledger: [{ seq, who, act, at }] }, newest first, 50 a page, for any item the caller may read (more: true says older rows remain; &before=<seq of the last row> reads them); or SELECT * FROM feed_signal WHERE item_id = ?. An item of GET /api/v1/feed carries likes and liked once anyone likes it (absent means 0 and false), and every card draws a Like button with the count. A like does not move the ranking. An item the viewer cannot read is a 404, as for every act.

In the terminal, the Feed screen (ssh in, then Ctrl-K and "Feed") marks a liked post ♥ n and one others like ♡ n; l on the post under the cursor likes it and a second l takes it back. It runs the same readInteraction check as the page and writes through setLike (toggleLike only picks the act from the current state), and the write moves the forge's write clock, so web viewers see it on their next live refresh. h on a post lists its ledger there (who, act, when, newest first; m for older rows), behind the same check.

The how-to, the decisions and what was left out: docs/features/feed-like-ledger.md.

Budget (#13581)

The signed-in home (/), the feed page (/feed) and GET /api/v1/feed answer their first page on a forge with 5,000 events inside a stated budget, proved by test/home-feed-budget.test.ts:

(timeline.ts), walks an index: no SCAN, no TEMP B-TREE in its query plan.

at about a third of that).

and the row count are the judges; the clock is a generous second check.

Newer posts line (#13599)

The head's reserved #feed-newer line reads N newer posts as a link to the top of the feed, from the last-visit count on load and and on a poll the sticky "N new posts" button takes over the count while the link steps aside (one control at a time). See docs/features/feed-new-count.md.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs