Skip to content

Stories row, notifications, offline, LAN

Stories row (SPEC §7.4)

GET /api/stories → {"stories": [Story]}, one per configured repo that has commits in the last 24 hours (wall clock), newest first:

{"repo": "storefront", "mascot": "otter", "mascot_image": "/assets/mascots/otter.png?v=<mtime>" | null,
 "commits": [{"sha": "<full>", "short": "abc1234", "ts": 1700000000, "author": "Alice Archer", "subject": "Fix ...", "files": 3}],
 "seen": false}
- At most 10 commits per repo, from git log --since=@<now-86400> on the repo ref (via gitq), cached per repo head sha. - seen is true when every commit sha was already viewed: POST /api/stories/seen {"repo", "shas": [...]} records them (table story_views(repo, sha, seen_at)). - The web shows a horizontal row of circles (mascot image or initial) at the top of the feed; unseen repos get a colored ring. Tapping opens a full-screen story viewer: one commit per page (subject, author, time, files count, short sha), tap right/left to move, swipe down or ✕ to close; viewing marks shas seen.

Notifications (SPEC §7.5)

Table notifications(id, kind, text, card_id, created_at, read_at) (exists). Generated by a server pass (in the learning worker loop, or its own worker) and gittok notify: - new_cards: "12 new cards from storefront" once per finished run with accepted > 0 (link: feed). - srs_due: "2 quiz cards are back for another try" when due SRS cards exist and no unread srs_due notification exists. The dedup key is a hash of the sorted due card ids, so it fires once per distinct due set. - hot_file: at most one per repo per UTC day, from the same commits used for stories. Files touched by ≥3 commits in the last 24 h count; paths under dot-directories (.github/, .claude/) do not. One file gives "auth.py was in 3 commits in the last 24 hours"; several give a digest, "Busy day in storefront: brief.py (11 commits), cli.py (10), api.py (7) and 4 more". Deduplicated on (repo, date). - new_kind: "A new Spot the Bug from billing/" when a card with story_type spot_the_bug lands (link: card). Only cards created in the last 24 hours count. - Dedup key per notification so passes are idempotent.

GET /api/notifications?unread=1 → {"notifications": [{"id", "kind", "text", "card_id", "created_at", "read"}], "unread": n}; POST /api/notifications/read {"ids": [...]} | {"all": true}. The web shows a bell with the unread count in the top bar and a /notifications list; tapping one with a card opens /card/{id}.

PWA and offline (SPEC §11)

  • web/static/manifest.webmanifest (name "GitTok", short_name, theme/background colors, display: standalone, icons 192/512 generated as PNG from an SVG at build time or committed), linked from app.html with apple-touch-icon and theme-color metas.
  • A hand-written service worker (web/src/sw.ts, built into sw.js by web/scripts/build-sw.mjs and registered from the layout when 'serviceWorker' in navigator): precache the app shell (build assets list) and cache-first for /assets/* images; network-first with cache fallback for GET /api/feed (the last successful batch is served offline) and /api/cards/*; never cache POSTs; queue POST /api/events while offline and replay on reconnect (Background Sync when available, else on next load).
  • An "Offline — showing your last batch" banner when the feed came from cache.

LAN access

  • LAN serving is on by default (server.lan: true), because the feed is made for a phone. gittok serve and gittok mcp --ui bind 0.0.0.0 and print the LAN URL(s) (first non-loopback IPv4 of each interface) next to the localhost URL. server.lan: false in local/settings.yaml, or --no-lan, binds 127.0.0.1. An explicit --host is used as given; --lan forces LAN serving.
  • The feed goes over plain HTTP. docs/install.md, "Phone access", says what that means on a network you do not trust.
  • The feed is token-protected. A LAN bind creates (or reuses) a random token in <data_dir>/lan_token (mode 0600). A paired device holds it in an HttpOnly, SameSite=Lax cookie cs_lan (long expiry). The token is never in a page, a link or a log line.
  • Pairing is by code only. The page for an unpaired device has a "Pair with a code" button: POST /pair/code makes a request in the pair_requests table, sets an HttpOnly cookie cs_pair with the request's secret id, and redirects to /pair/wait. That page shows a six-character code (no characters that look alike) and loads again every 3 seconds (/pair.js, a file of the server, because the CSP allows no inline script; a meta refresh when scripts are off). The user tells the agent "pair code ...", and the pair_device MCP tool (or gittok pair <code>) approves it in the database. The next load of /pair/wait sets cs_lan and redirects to /. A code lasts 10 minutes and works once; at most 20 codes wait at the same time, and at most 3 for one device address (429 after that). A device that asks again with its cs_pair cookie gets its waiting code back. Only a code that the user types approves a request: a device on the network can ask for codes but cannot approve one. An app on the home screen keeps its own cookies and pairs inside the app the same way; the web app's "not paired" message has the same button.
  • The feed address. The SessionStart line gittok url --hint gives it at the start of each session, and the feed_address MCP tool gives it on request ("pair my phone", "what is the feed address?"): the addresses where the running server answers, from a TCP connect to each one, and the notice about LAN serving. The set_lan MCP tool writes server.lan; the server must then start again.
  • Requests from non-loopback peers need the cookie, except /pair/code, /pair/wait, /pair.js (the Copy button of the wait page: "pair code XXXX-XX", with an execCommand fallback because plain HTTP has no navigator.clipboard) and the app icons and manifest (api.APP_ICON_PATHS: a phone takes the home-screen icon from what it can fetch when the user adds the app, and these files hold no user data). The pairing pages link the icon and the manifest too. Without it, /api/* returns 401 JSON and other paths return a small page with the "Pair with a code" button. Loopback peers never need the cookie. The token is compared in constant time.
  • The feed server has no MCP endpoint. The MCP server speaks stdio only, to the session that started it.
  • Request bodies are limited to 1 MB (413). POST /api/stories/seen takes at most 100 shas, each 7-40 hex characters. POST /api/events takes at most 500 events, and each event data must be 4 KB or less as JSON.
  • PWA install and offline mode need HTTPS: service workers do not register on plain-HTTP LAN origins. The feed still works in the browser over HTTP. GitTok serves plain HTTP only; docs/install.md, "HTTPS on a LAN", has two untested recipes with a second program.
  • settings.server.host is 127.0.0.1 by default; it is the bind address when LAN serving is off. A non-loopback --host (or server.host with server.lan: false) is token-protected too: the server makes the token, and devices pair by code as on the LAN.
  • Host allowlist (DNS rebinding). Every path (/api/*, /assets/*, /pair, the web app) answers only when the Host header, with or without a port, is 127.0.0.1, localhost, [::1], one of this machine's LAN IPv4 addresses, its host name (also the short name and <short name>.local), or a name in settings.server.allowed_hosts (a list, empty by default; use it for a VPN name or an IPv6 address). Any other or missing Host gets 421. The address list is read again after 30 s, and at most each 2 s when an unknown Host arrives, so a new LAN address works without a restart.
  • Origin check. A POST, PUT, PATCH or DELETE with an Origin header whose host is not in the same allowlist, or whose scheme and port differ from the request (the Vite dev port 5173 on a loopback name is the one exception; a proxied request is checked by host only), gets 403. A request without Origin passes.
  • Response headers on every response: X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer (same-origin on the page for an unpaired device and on /pair/wait: with no-referrer a browser posts the "Pair with a code" form with Origin: null, which the Origin check refuses), and a Content-Security-Policy: default-src 'self'; script-src 'self' 'wasm-unsafe-eval' <sha256 of each inline script in the built index.html>; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self'; worker-src 'self'; manifest-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'. The server computes the script hashes from index.html (again when the file changes), so the web build needs no CSP config. 'wasm-unsafe-eval' is for the code highlighter's WebAssembly regex engine; 'unsafe-inline' styles are for highlighted code and diagrams.
  • The uvicorn access log shows /pair?[redacted], never the token.

Characters that carry

  • Pages: /persona/<handle> (avatar, name, bio from personas.yaml or the voice, recent posts, recent comments) and /file/<repo>/<path> (commit count, last touched, top authors, cards that cite the path in sources, visual, depth panels or account). API: GET /api/personas/{handle}, GET /api/files/{repo}/{path}.
  • Card headers and comment names link to those pages; a code-account poster links to its file page.
  • Follow: POST /api/follows {repo, path, on}. Follows are stored in the prefs table under followed_paths. A follow shapes generation: the brief ranks the leads in the dir of a followed path (the path itself if it has no file extension) higher, by lead_score.followed in reward.yaml. The feed does not reorder cards that exist.
  • Comments: the card face shows two comments with avatars. On quiz cards a comment is a spoiler (hidden until answered) unless it sets spoiler: false.
  • Cast notes: get_packet returns cast_markdown, each packet persona's last 3 hooks or comments (trimmed), at most 800 bytes. Writers call back to running jokes.
  • Series: series is null or {key, part, of}. The face shows a "Part n/of" chip. The slotter holds a part back while an earlier part is unseen, orders parts, and spaces them SERIES_GAP (3).