chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
place.hud.hudkit 0.3.0 Latest 5 packages
Working on HUD
For every agent working here: CLAUDE.md is this file, imported. What HUD
is and how it is run is in README.md and the pages in docs/.
Layout
crates/hud-core: everything that is not HTTP: configuration, the outbound client and its address filter, identity resolution, lexicons, PDS reads, XRPC queries (xrpc.rs: services, params and answers checked against lexicons), blob-ref rewriting, the audio blob cache, views (their validation, the component catalog, the join engine, summaries), the kit each tree is fitted to (kit.rs: the renderer's version a client says, a view's gates on it, what stands for a component newer than it, andhud check's warnings for an app's oldest kit), the tools, the three that write (writes.rs, a text's facets made byrichtext.rs, a composer's writes template filled bycompose.rs), a link's card (cards.rs) and places (places.rs) for a composer, the procedures a trusted view calls (procedures.rs), the operator's apps and views (operator.rs,HUD_APPS, checked as the bundled views' tests check them, with the lexicons they ship and the HUD versions they run on), the JSON Schemas of an app file and a view (schema.rs), the workspace's canvases (canvas/: the engine, each person's tabs and live stream, placement on the strip of columns instrip.rs, theStoretrait and its file backend, the space backend inspace.rs, withHUD_SPACES=on, the tools), apps' icons (icons.rs: favicons, kept on disk), the workspace's themes (theme.rs: HUD's, people'splace.hud.themerecords, their contrast check, and each person's choice of one), what HUD keeps of a person and its deletion (account.rs), the space client (space.rs:com.atproto.space.*as the account), the scope sign-in asks for (scope.rs: atproto's permissions, built from the trusted views, through the permission sets their app files name, and whether a sign-in is behind them), and sign-in (oauth/: the MCP authorization server inissuer.rs, the atproto OAuth client inclient.rs, sessions on disk instore.rs, MCP sessions and the workspace's web sessions alike, and their offline tests against a fake PDS intests.rs, its spaces and the space backend's tests intests/spaces.rs).crates/hud-server: the HTTP surface:POST /mcp(and its sign-in challenges),GET /blob/{did}/{cid},GET /_health, the terms, privacy policy and guidelines,GET /{terms,privacy,guidelines}(policies.rs, each page's HTML inpolicies/), HUD's icon,/favicon.svg, the playground,/playground(playground.rs), HUD's methods,/xrpc/place.hud.*(xrpc.rs, its tests through the router inxrpc/tests.rs: the playground's andsearchActorsanyone's, the workspace's with sign-in on alone), and apps' icons,/icon/{domain}(icon.rs); and with sign-in on/oauth/*and/.well-known/oauth-*(oauth.rs, with the sign-in page MCP clients see), the workspace's page,/workspace(where/goes; signed out, the landing), the sign-in dialog's app logos,/workspace/atmo/*(crates/hud-server/atmo/), the landing's picture,/workspace/hero/*(crates/hud-server/hero/, made byjust hero), and its sign-in, switching and sign-out,/workspace/{signin,switch,signout}, its sessions' cookieshud_sessionandhud_accounts(workspace.rs); withHUD_WEB, the operator's web app's pages,/, the icons and every request no route takes, handed on and streamed back (web.rs, its tests against a fake app inweb/tests.rs); itsbuild.rsembedsweb/dist/index.html,web/dist/workspace.html,web/dist/playground.htmlandweb/dist/favicon.svg.crates/hud: the binary,hud serve;hud resolve, which gives a recorded answer its_meta.ui, for the harnesses;hud check <dir>, which loads a directory of apps ashud serveloadsHUD_APPS, naming every problem; andhud schema app|view.web/renderer(@hud/renderer): the renderers as Svelte components, with no dependency on MCP, so another app can reuse them, drawn on a server (svelte/server) as in the browser: nothing touches a browser's globals as it loads or draws, nothing is kept on a server, and the browser's first drawing is the server's (Tree'snow, dates fixed until mounted). Its server test,web/renderer/test/ssr.mjs(cd web && npm run ssr), draws Grain's trees inweb/renderer/test/trees(made byjust ssr-data,harness/ssr/data.mjs) in Node and hydrates them in happy-dom.web/renderer,web/shellandweb/sharedare HUD's web packages, published (docs/sdk.md): each package'ssrcbuilt bysvelte-packageinto itsdist(cd web && npm run package), which its exports name; insideweb/they resolve tosrcby the@hud/sourcecondition (vite.config.ts,tsconfig.json, the server tests' builds). Code inweb/imports one by its name (@hud/shared/result), never by a path into it.web/shell(@hud/shell): an app drawn as a web app from its app file (docs/views.md, "The frame"):Shell, its frame (the tabs as a bar, a rail or a sidebar by the window's width, decided in CSS,frame.ts) and each tab's nav stack of tool results drawn with the renderer, server-rendered and hydrated as the renderer is; and@hud/shell/server, what an app's server reads for a page, and its sessions at HUD (session.ts: the browser's accounts, sealed in a cookie,seal.ts,accounts.ts; signing in as HUD's MCP client,oauth.ts). Its host gives it its router and routes its endpoints (Grain'snext/). Its server test,web/shell/test/ssr.mjs(innpm run ssr), draws a sample app at three widths and hydrates it;npm run unitits unit tests.web/src: the view, which talks to its host through@modelcontextprotocol/ext-appsand draws with the renderer.web/workspace: the workspace's page, which calls its own server's/xrpc/place.hud.*and draws with the renderer, and the playground's (web/playground.html,Playground.svelte), built of the same components: a view written beside what it draws (previewView);web/shared(@hud/shared), what it, the view and the shell share: reading a tool result (result.ts), a person's interactions (interactions.ts) andResult.svelte;web/public/favicon.svg, HUD's icon, which Vite copies intoweb/distas it is.web/dev: a dev host for the view (just dev), againstjust serve.lexicons/: the bundled lexicons, written byjust lexicons; never edited by hand.schemas/: our own lexicons (place.hud.*: the records, the workspace's methods,defs, andui, the resolved tree a result's_meta.uiholds, whichhud_core::ui::checkholds the resolver's trees to in its tests), written by hand, embedded beside them;just lexiconsnever touches it.schemas/json/: the JSON Schemas of an app file and a view (hud_core::schema), no lexicons, written byjust json-schemasand held current by a test.harness/: checks beside cargo's, each a node script whose header says what it checks and how to run it, run by the Justfile:lexicons.mjs,answers.mjsandschemas.mjs(just lex),layers.mjs,contrast.mjsanddocs.mjs(just lint),look.mjs(just look),scroll.mjs(just scroll, a long feed scrolled, page inharness/scroll/),gallery.mjs(just gallery: every drawing HUD makes as a tile, side by side, from the answers inharness/gallery/given their trees byjust gallery-data; the iOS app draws the same file, Debug builds' Settings → Development → Gallery).cd harness && npm cionce. Against a PDS of HUD's own:pds.mjs(the reference PDS and PLC, alice, bob and carol), the e2e world over it (e2e/world.mjs,just e2e), and the same kept running with a browser at it, and with--iosthe app on a simulator, to try by hand (local.mjs,just local). HUD is served there athud.harness.internalwith a certificate of the checkout's own authority (tls.mjs, kept in.local/tls/), which a simulator is told to trust. Each takes the spaces alpha with HUD_DEV_ENV (harness/spaces;just e2e-spaces,just local --spaces), where HUD keeps canvases in people's spaces.just local-setuponce per checkout and Mac: the packages, the authority, and that hostname in /etc/hosts.views/: the bundled views, one JSON file per view, named as its id, each aplace.hud.viewdocument; embedded by hud-core and checked by its tests. An operator's views (HUD_APPS) replace or add to them at startup, held to the same checks (view::trusted_problems,view::conflicts).docs/: the docs, one page per topic, each fact in one page, written and checked (harness/docs.mjs) asdocs/_style.mdasks, which says which page owns what;README.mdpoints at them. A change to a tool, a default or a mechanism changes the page that owns it.themes/: HUD's own themes, one JSON file per theme, named as its key, each aplace.hud.defs#theme: light and dark, HUD's own look, with no palette, and the rest each a palette; embedded by hud-core, checked by its tests, and handed to the page and the iOS app bygetWorkspace, so no client keeps a copy. People's are records in their own repositories (place.hud.theme), held to the same contrast.ios/: the iOS app.ios/HUDKit, a Swift package: the renderer in SwiftUI, a port ofweb/renderer(Tree/draws the tree the server resolved,Embed/its embeds), whatweb/shared/src/result.tsandinteractions.tsdo (Data/), the client that calls the tools over/mcp, an operator's app file's routes and push for an app built on HUDKit (Data/Routes.swift,Data/Push.swift: the device registered as itspushsays, a tapped notification opened as a route), and the workspace's client and model (Workspace/: its XRPC methods and event stream as the signed-in account, by Bearer, and its theme,Theme.swift); its tests inTests/. A palette reaches the views throughSupport/Surface.swift(.hudTheme, andHUDColor, a role's colour or the native one): a colour a palette names is never a system colour in a view.ios/App, the app around it: signed in, the workspace (canvases as tabs, a strip of columns, one a screen on a phone, each tile a tool call), Home and Settings (accounts, theme) sheets over it; signed out, signing in by handle; its icon inApp/Assets.xcassets, the same as the favicon, square, as iOS masks it.ios/project.ymlmakes the Xcode project (just ios; the project is gitignored);just ios-testruns HUDKit's tests.android/: the Android app, a Gradle project.android/hudkit(place.hud.kit): the renderer in Jetpack Compose, a port ofios/HUDKitas that is ofweb/renderer:tree/draws the tree the server resolved (TreeView.kt'sResolvedNode, a component a function),parts/andembed/its pieces,data/whatweb/shared/src/result.tsdoes,support/the surfaces by role (Surface.kt'sHudColors, a palette's colour or Material's), type, icons (Glyphs.kt, the web's own paths) and pictures (Coil); its tests insrc/test, on the JVM under Robolectric, reading iOS's fixtures.android/app, the app around it: for now the gallery, the sample tiles ofjust gallery-dataa debug build carries (just android <entry>;just android-testruns hudkit's tests).
A new crate goes in crates/<name>, named as its directory, with its
versions in the root Cargo.toml's [workspace.dependencies].
Versioning
HUD has one version, its SDK's: the crates', the web packages',
HUDKit's and hudkit's (knope.toml names every file that holds it). A
pull that changes what an app built on HUD sees (a component, a prop,
what a tree draws, a tool's shape) adds a change file under
.changeset/, as knope document-change writes one: default: patch,
minor or major in its front matter, then a heading and a line for
the app's authors. release-pull.yml, asked for at main, turns them
into the version and CHANGELOG.md in a Release <version> pull;
release.yml, asked for at main once that lands, publishes every
package. Never bump a version by hand. docs/sdk.md has the rest.
Rules
- Cargo through rustup:
rustup run stable cargo(the Justfile'scargo). Node is the version.node-versionnames;cd web && npm cionce. just checkis what a change must pass: rustfmt, clippy with warnings denied, the tests underjust cov's gate, svelte-check, the renderer's server test (npm run ssr),just lintandjust lex. The runner (runner.knotless.dev) runs the same on pushes to main and pulls into it (.knotless/workflows/):check,testandwebas the merge queue's pre-flights,lexicons,docs,e2e(just e2e) ande2e-spaces(just e2e-spaces).maintakes pulls only through the merge queue, each once review.knotless.dev has reviewed its head, and each push to it deploys hud.place (deploy, on ci.knotless.dev). A workflow's shared steps are pinned in.knotless/uses.lock(knotless workflow pin).just covfails under 100% of lines or functions, workspace-wide: a line no test runs is a case nobody checked, so test it with what a consumer would notice, never lower the gate or hide code from it. Where no test can sensibly reach a line, write it so the path does not exist:cargo fmtcan put a?on a line of its own, which counts as a line never run (bind the value first), and since Rust 1.100 coverage counts the closing}of anifwith noelseas the path where the condition is false, and each match arm on its own. Thehudbinary counts too: its tests run it (CARGO_BIN_EXE_hud), and stophud serveby SIGTERM so its profile is written.- A lexicon in
schemas/follows the Lexicon Style Guide (https://atproto.com/guides/lexinomicon) and passesjust lex: goat's lint (less the warningsharness/lexicons.mjskeeps, each with why),knownValuesnotenum, objects in arrays, open unions, a description on everymainsaying whether it needs auth, amaxLengthon every string without a format people write, accounts by DID; and only grows from main's once published. Every answer the server's tests receive is held to its method's lexicon (harness/answers.mjs), so a method's tests call it through the router (xrpc/tests.rs'sask). - The server keeps no database: caches only, in memory, and the lexicon,
audio blob and apps' icon caches on disk under
HUD_CACHE_DIR; and, with sign-in on, sign-ins underHUD_DATA_DIR/oauth/(hud_core::oauth), the workspace's canvases and each person's index of them and their tabs underHUD_DATA_DIR/canvas/(hud_core::canvas), and each person's theme underHUD_DATA_DIR/theme/(hud_core::theme), each file mode 0600 and written whole; withHUD_SPACES=on, a canvas its owner alone is in goes in their own space instead. The one database is the operators' copy of the log, withHUD_LOGS=on:HUD_DATA_DIR/logs.db(hud_core::logs), SQLite, mode 0600, holding the lines stderr has and nothing more, so never a token, a query's secret, a header or a body; read byHUD_OPERATOR_DIDSalone. Lines are logged throughhud_core::telemetry(docs/observability.md), every outbound call throughhud_core::net. Never log a token, or keep one of HUD's own (a web session's cookie too) but as its SHA-256. Thequerytool calls queries alone, never a procedure; a caller goes throughxrpc::Caller, as no one or as the signed-in account through its PDS, the one place they differ. Writes go throughcreate_record,apply_writesanddelete_recordalone, as the account, to its own repository, each record checked against its lexicon first (its{"$facets": key}fields made the text's facets before), and a composer's pictures throughplace.hud.uploadBlobalone, to the account's PDS, never logged; but a procedure a trusted view calls (Action'scall,Messages'send), or an operator's app file registers a device for push with (itspush), throughcall_procedure(hud_core::procedures) alone, the view's, sent through the account's PDS only if a trusted view or app file calls that method of that service, its input checked against its lexicon first, neither input nor answer logged; what a trusted view'sdeletesplans (anAction's), throughcall_procedurealone too, its query asked as the account only if a trusted view deletes by it, its deletes committed in oneapplyWritesof the account's own repository, each of a collection the scope asks to write or delete (Hud::delete_planned); and the canvases' records throughhud_core::space, as the account, to its own repo in its own spaces, each checked against its lexicon (schemas/) first. The space scope stays one constant (config::SPACE_SCOPE), never asked for by default. - A tool that needs an account answers
Refusal::SignInwithout one, which/mcpturns into the HTTP 401 challenge, never a tool error. No OAuth or MCP SDK crates: sign-in is built on theatprotocrate'sjoseandkeys. - Anything a DID document, lexicon or service says is untrusted. Outbound
requests go through hud-core's client, which refuses non-public
addresses, but for the operator's own web app (
HUD_WEB), its origin the operator's, reached through a client of its own for it alone (net::Web); a service's answer is checked against its query's lexicon; lexicondescriptions reach the view only, as plain text, never a tool'scontent, description orstructuredContent(describe_collectionanddescribe_methodstrip them). - A tool's text
contentis a short summary a person could read; its data isstructuredContent; what only the view needs is_meta. - The view loads nothing but its own inline code, and images and audio
from the server's blob proxy, and public records' images from the image
CDN (
HUD_IMAGE_CDN), and public posts' videos from Bluesky's video service and CDN (HLS); it reaches the server only through its host's tool calls. Nofetchfrom the view but aMap's vector tiles, fromcatalog::MAP_TILESalone (in the CSP'sconnectDomains). blobs::rewriteis told whether what it rewrites was read where anyone can (Visibility::Public:com.atproto.repo.*, the AppView) or not (Private: a space, a service's answer to the account): a private record's blobs never get a CDN URL.- The workspace's page reaches its own server alone, its XRPC methods as
its web session; their procedures by the cookie carry
X-HUD: 1, and the server takes them from its ownOriginonly. A HUD access token asBearercalls them too, as an app of the person's would. A canvas tile names a read tool and its arguments, never a result: the page calls the tool (callTool) to draw it. Tiles are placed on the server (canvas::strip), so a person and an agent place them alike. - A change to a tool, its shapes or the view's renderers changes both sides in one change.
- Views are data. No code names a collection a bundled view draws: a
record type gets its own drawing by a view in
views/, written with the catalog's components, not by a renderer of its own. Where a query draws a record richer (a post's thread), the record opens as that query: its method view names the collection inrecords, and no collection view draws it. Collections themselves are never shown: a profile shows apps, sections and activity, never a list of collections. - A tile is one thing. A view draws what belongs to its subject in
itself, by a join: a post's replies, a gallery's photos and comments,
an issue's conversation. It opens a new tile (
open) only for another thing: another record, account, feed or app. - An account opens where it is read: a name in a bundled view's drawing
opens their page in that view's app (
ui::Ctx::people), else their profile across apps (describe_repo), which a tile's @handle opens too. A view names an account byhref, never by an app's own query. - Only the bundled views and the operator's (
HUD_APPS,hud_core::operator) are trusted, and HUD refuses to start unless the operator's pass what the bundled views' tests hold them to, through the same code. Every read of them goes throughview::bundled(), the bundled views as the operator's replace and add to them. No HUD code names an operator's app. A view given inline is checked exactly as a bundled one is, but may name onlyoriginsa trusted view names (so it never widens the CSP), and its description reaches no tool description or instructions. A result says which it is (_meta.ui.trusted): the view asks the person to confirm an untrusted view'sActionbefore it writes. - Views are resolved on the server: a view's layout is read against its
data in
hud-core/src/ui/into_meta.ui, a tree the clients only draw (no client binds a view or fetches for one). The component catalog lives in four places that change together: the Rust constant (hud-core/src/catalog.rs), which validates layouts and is whatdescribe_collectionanddescribe_methodhand a model, with the resolver (hud-core/src/ui/) that reads it into the tree; and the three that draw the tree,web/renderer(src/tree/),ios/HUDKit(Tree/) andandroid/hudkit(tree/). A component or prop added to the catalog says the version it arrives in (since): a build of an older kit is sent its children, its fallback or nothing in its place (hud-core/src/kit.rs). A look is the platform's own, but the surfaces are one: a grey canvas, a tile's body lighter in front of it, a card in a tile that body's colour inside a hairline (iOS'sHUDKit/Support/Surface.swift, Android'ssupport/Surface.kt).
Web pages
The workspace (web/workspace) follows knotless's web practices
(~/code/knotless/web/AGENTS.md, its ui skill):
- Layers: components live in
web/workspace/lib/{atoms,molecules, organisms,templates}; each uses its own layer and those below, never one above (harness/layers.mjs, injust lint). Pages inweb/workspace/*.sveltefill the template; modules inlib/(state, the stream,xrpc.ts) belong to no layer. - Tokens: every value in its CSS is a token from
web/workspace/tokens.css(knotless's, by the same names), a colour by its role, never its hue, aslight-dark(); add one there when none fits. The renderer's MCP Apps host variables are set from them inapp.css, so tiles and chrome are one look, and a theme's palette (lib/theme.ts) is written over them, so it colours both. Every text colour reads at 4.5:1 in light, dark and every palette:harness/contrast.mjschecks the pairsharness/contrast.jsonnames in light and dark, andhud_core::theme::problemsitsPAIRSin a palette; a new colour that is text goes in the first, and in the palette and the second if a theme colours it. - Icons: Lucide's, through
lib/icons.ts, one per thing, the same everywhere; an icon without its word has anaria-label. An app's icon is its favicon (AppIcon, HUD's/icon/<domain>), its kind's Lucide icon where it has none. - Data: the page reaches only its own server's XRPC methods, typed
by
npm run lex(gitignoredlib/lexicons), throughlib/xrpc.ts. - Words and menus: sentence case, labels without a full stop, empty
states that say what is empty where the rows would be, one primary
button a view; a menu that opens is a
<details class="popover">, a sheet on a phone. - Memory: what a page holds follows what is on screen
(
docs/memory.md). A tile keeps its answer as read ($state.raw, a page more replacing it, never mutating it) and draws it only whilelive; a component's state a person changes (a like, a reveal) is kept withremembered(rendererview/remember.svelte.ts), as it is unmounted and drawn again; a long list goes throughListWindow(view/window.ts); a picture drawn small takessource(…, 'small'), a blob'sthumbor a URL by the view'sthumbnails, andPicturefalls back once to a blob'sproxy; media load nothing until played. A server cache is acache::Ttl, bounded by entries and bytes, its share ofHUD_CACHE_MEMORY_BYTES. Check a change withjust memory, and one to a long list's drawing withjust scroll(no long tasks while scrolling, p95 frame under 20 ms, no blank frames). - Looking:
just look <name> [--set …] [--events …] [--click …] [--press …]draws the workspace fromweb/distin front ofharness/look/(no PDS, no server: each answer given its_meta.uibyhud resolve) intotarget/look. Look at every state you touch, desktop light and phone dark, and have the pictures critiqued by an agent that did not write them.
atproto's primitives
DIDs, handles, NSIDs, record keys, CIDs and DID documents' services come
from the atproto crate (knotless.dev/chadtmiller.com/atproto), published
to that repository's Cargo registry, which .cargo/config.toml names. A
primitive HUD needs that the crate lacks goes there first, as a new version.