Files
llama.cpp/ui/apps/chat/AGENTS.md
T
Aleksander Grygier 97069ff6c4 ui: run Llama Chat with npx @ggml-org/llama-chat (#32524)
* ui: run Llama Chat with npx @ggml-org/llama-chat

Makes @ggml-org/llama-chat publishable: drops private, adds bin,
files, exports, repository and a prepack build. Its CLI serves the
prebuilt dist on localhost (3000 by default) and forwards every other
request to a llama-server (--server, default http://127.0.0.1:8080),
with the headers llama-server sends for the UI. A thin unscoped
llama-chat package in alias/ forwards to it, so npx llama-chat works.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: llama-chat revalidates service-worker.js and asks for a build before packing

SvelteKit 3 adds service-worker.js next to sw.js, and llama-server
revalidates it, so the CLI does too. The folder's .npmrc sets
ignore-scripts, so prepack never ran: it goes, and the publishing steps
build dist explicitly and check the packed file list.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: llama-chat keeps llama-server's DNS rebinding and cross-origin guards

The CLI called llama-server with its own Host and dropped every Origin,
so a rebound host name or another page got past the checks llama-server
makes when --cors-origins is not *. It now drops only its own page's
Origin, passes other Origins and Sec-Fetch-Site through, and, when it
listens on loopback, answers only to localhost and loopback addresses.
`start` on Windows gets its empty title verbatim.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: llama-chat build writes the app to a folder for any static server

`npx @ggml-org/llama-chat build [--out <dir>] [--force]` copies the
prebuilt app, without source maps, to ./llama-chat or the given folder,
so a plain file server can host it next to the CLI serving it. It
refuses a folder that is not empty unless forced, and the serving flags
and build flags refuse each other's command. The README shows serving
the folder with http-server forwarding the API to llama-server.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: publish Llama Chat to npm from CI when its version is bumped

ui-chat-publish.yml publishes @ggml-org/llama-chat and its llama-chat
alias the way ui-lib-publish.yml publishes @ggml-org/llama-ui: the
version is set by hand, and a commit that reaches master with a version
npm does not have builds dist, checks the packed files and publishes both
with trusted publishing. PRs that change the packages get a dry run.
npm-version-check.mjs takes the package folder, so both workflows share
it. ui/README.md says how releases work, and Chat's AGENTS.md says not
to bump versions unless asked to release.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: call the app Llama Chat in its README

The README's title and a few lines still called the app llama-ui or
Llama UI, the name of the library it is built on. They now say Llama
Chat, and the intro points to Llama UI in ui/lib/ui.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: llama-chat connects to llama-server's default port, 9931

The CLI's --server default and its examples used 8080, which is not
where llama-server listens. They now use 9931, its default port, so
npx llama-chat reaches a llama-server started without --port.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: a shorter Llama Chat README that matches the code

The README grew to nearly 900 lines, and its tables of components,
hooks, stores and services had drifted from the code. It now keeps what
a reader needs: running it with npx and self-hosting, a short feature
list, development commands, the architecture (the line between Llama UI
and the app, a table of the layers and where they live, a flowchart and
one sequence diagram for sending a message), a few patterns worth
knowing, cross-origin isolation, how the build is embedded in
llama-server, the project tree and publishing. The folders now carry the
detail the tables used to. ASCII replaces the unicode arrows.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: llama-chat serves only static files, without the API proxy

The CLI forwarded every request it had no file for to llama-server, from
loopback. With --host 0.0.0.0 that let any LAN client reach a llama-server
started on 127.0.0.1 as a local request, tools included, which llama-server
on its own refuses without an API key. The browser now talks to each
llama-server directly, so llama-server's own rules apply. --server is gone,
and anything that is not a file in dist is a 404, or a 405 for other methods.

Assisted-by: Claude (Opus 5.5 Medium)
2026-11-18 12:58:16 +01:00

4.1 KiB

Instructions for ui/apps/chat

These add to the repository's AGENTS.md for work in ui/apps/chat: Llama Chat, the chat client that llama-server bundles. Llama UI, the library, is ui/lib/ui (@ggml-org/llama-ui): Chat imports its tokens, fonts and base components from there (@ggml-org/llama-ui/ui/<name>) and keeps no copy of them. DESIGN.md and the Storybook live here; the brand book, BRAND.md, and the brand and communications pages are in ggml-org/llama-brand, with their own Storybook.

  • Design: DESIGN.md holds the tokens, roles and rules, written for agents. Follow it for anything visual. Its token sections (colors, typography, rounded) are generated from the CSS with npm run design:tokens, and CI checks they are current; the rest is written by hand, and when it and the CSS disagree, the CSS wins and DESIGN.md is updated.
  • Stories: a story lives with the code it shows. Llama UI's (its foundations, base components, app components and Model UI) are in ui/lib/ui/tests/stories, titled Llama UI/..., and run as the library's tests; this app's Storybook shows them too. Llama Chat's are in tests/stories/<area>, one folder per src/lib/components/app/<area> (chat/ has one per Chat folder), titled Llama Chat/<Area>/<Component>. An accessibility story sits next to its component's, as <Component>.a11y.stories.svelte, titled .../<Component>/Accessibility. The story helpers both Storybooks use (the Editorial the prose pages are set in, StateGallery) live with the library's stories and are imported here as $llama-ui-stories/...; reuse them rather than copying them here.
  • Releases: @ggml-org/llama-chat and @ggml-org/llama-ui are versioned by hand and published by CI when a new version reaches master (see Releases). Bump a version only when asked to release, never as a side effect of a change; Chat's version and its alias's (alias/package.json) always move together.
  • Components: the SKILL.md next to a component folder (such as src/lib/components/app/SKILL.md) holds that folder's conventions.

Content is Markdown, custom pieces are Svelte: .svx

Anything that is mostly content (a doc, an overview, a showcase or a Storybook page with prose) is written in Markdown, and whatever Markdown cannot express (a live example, a diagram, a real component) is a Svelte component placed in it. Together that is a .svx page, compiled by mdsvex.

  • Write the prose as plain Markdown, so it reads well as source, for people and for agents alike.
  • Put each custom piece in its own .svelte file and import it in the page's <script>. Keep logic and styles out of the .svx file.
  • Frame the page with a Svelte component that sets its typography, and show it in Storybook as a fullscreen story, as introduction/Introduction.stories.svelte does. Storybook's MDX is rendered with React and cannot hold Svelte components, so use MDX only for pages that are Markdown alone, such as Design guidelines.
  • Do not add another Markdown-to-HTML pipeline. Content goes through mdsvex; user and assistant messages go through MarkdownContent.

mdsvex versions

  • ui/apps/chat is on mdsvex 0.12.7, which only Storybook's .svx pages use. llama-brand's Storybook pages, the logo showcase and the type specimen among them, are on 1.0.0-next.3.
  • mdsvex 1.0 is the direction. Move ui/apps/chat to it, pinned to an exact next version, while it only serves Storybook pages; write new .svx pages so they work on both.
  • Messages: 1.0's @mdsvex/render can render a document as it streams in (@mdsvex/render/stream) and as Svelte (Node.svelte). The plan is to swap the unified/remark/rehype pipeline inside MarkdownContent for it, keeping MarkdownContent's API, so chat messages, the live-preview Markdown editor and the Notebook (which all render through MarkdownContent) switch together. Check parity first: GFM, math, Mermaid, the safe-HTML config, file-mention badges and the code-block actions, plus bundle size and streaming performance.