Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions ui/apps/chat/.storybook/manager-head.html
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,10 @@
'brand-colors-primitives--primitives': 'llama-ui-foundations-colors--primitives',
'brand-logo-app-icons--splash-screens': 'llama-chat-foundations-brand--splash-screens',
'brand-logo-usage--splash-screens': 'llama-chat-foundations-brand--splash-screens',
'introduction-design-philosophy--design-philosophy': 'philosophy-design--design',
'philosophy--design': 'philosophy-design--design',
'philosophy--ideology': 'philosophy-ideology--ideology',
'philosophy--product': 'philosophy-product--product',
'introduction-design-guidelines--docs': 'agents-design-guidelines--docs'
};

Expand Down
6 changes: 5 additions & 1 deletion ui/apps/chat/.storybook/preview.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ const preview: Preview = {
},

options: {
// sidebar sections: the introduction and the guidelines for agents, then the two layers as the code has them.
// sidebar sections: the introduction, the guidelines for agents, the philosophy and the architecture, then the two layers as the code has them.
// Llama UI is the library (ui/lib/ui): its foundations, base components, app components, Model UI and mockups.
// Llama Chat is the app (ui/apps/chat): its own foundations, then one folder per src/lib/components/app/<area>,
// the full chat screen leading Chat. The brand and communications are in llama-brand's Storybook
Expand All @@ -35,6 +35,10 @@ const preview: Preview = {
'Introduction',
'Agents',
['Design guidelines'],
'Philosophy',
['Ideology', 'Product', 'Design'],
'Architecture',
['Stack', 'Chat', 'Extensions', 'Channels'],
'Llama UI',
[
'Foundations',
Expand Down
3 changes: 2 additions & 1 deletion ui/apps/chat/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
These add to the repository's [AGENTS.md](../../../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](https://github.com/ggml-org/llama-brand), with their own Storybook.

- **Design:** [DESIGN.md](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.
- **Why:** Storybook's **Philosophy** section explains the reasons, for people: **Ideology** ([Ideology.svx](tests/stories/philosophy/Ideology.svx)), **Product** ([Product.svx](tests/stories/philosophy/Product.svx)) and **Design** ([Design.svx](tests/stories/philosophy/Design.svx)).
- **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.
- **Components:** the `SKILL.md` next to a component folder (such as [src/lib/components/app/SKILL.md](src/lib/components/app/SKILL.md)) holds that folder's conventions.

Expand All @@ -12,7 +13,7 @@ Anything that is mostly content (a doc, an overview, a showcase or a Storybook p

- 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.
- 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` and `architecture/Stack.stories.svelte` do. 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
Expand Down
5 changes: 4 additions & 1 deletion ui/apps/chat/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -780,7 +780,10 @@ conversations and traces, so the UI never assumes a cloud account or hides which
The service need not be on the same machine: a server can be run by one person and shared by
many (a family, a team, a community), so the UI should make clear which server a model runs on.

This file is the how, written for agents first. Its principles, as rules to apply here:
This file is the how, written for agents first. The why, written for people, is
**Philosophy › Design** in Storybook (`tests/stories/philosophy/Design.svx`), next to
**Philosophy › Ideology** (what we stand for) and **Philosophy › Product** (how the products fit together).
Its principles, as rules to apply here:

- **Function first.** Every element has a job and takes its measurements from a shared role
(control heights, corners, icon sizes, type roles); never give one component its own.
Expand Down
2 changes: 1 addition & 1 deletion ui/apps/chat/tests/stories/DesignGuidelines.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ export const [, tokens, guidelines] = designMd.split(/^---$/m);

<div className="callout">

**Written for agents first.** This is the how of Llama UI, in a form an agent can follow when it builds or changes the UI: the tokens, the roles and the rules, precise rather than persuasive. People can read it too.
**Written for agents first.** This is the how of Llama UI, in a form an agent can follow when it builds or changes the UI: the tokens, the roles and the rules, precise rather than persuasive. People can read it too, but the why behind it is in the **Philosophy** section.

</div>

Expand Down
19 changes: 19 additions & 0 deletions ui/apps/chat/tests/stories/architecture/Channels.stories.svelte
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<script lang="ts" module>
import Page from './Channels.svx';
import Frame from './Frame.svelte';
import { defineMeta } from '@storybook/addon-svelte-csf';

const { Story } = defineMeta({
parameters: {
controls: { disable: true },
layout: 'fullscreen'
},
title: 'Architecture/Channels'
});
</script>

<Story asChild name="Channels">
<Frame>
<Page />
</Frame>
</Story>
92 changes: 92 additions & 0 deletions ui/apps/chat/tests/stories/architecture/Channels.svx
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
<!--
Architecture › Channels: how one build of Llama Chat ships bundled in llama-server, as npx llama-chat and at
chat.llama.app, how the three differ, and the release flow. Set in the Editorial, through Frame.svelte.
-->

<script>
import Callout from './lib/components/ui/Callout.svelte';
import ConnectFigure from './lib/components/channels/ConnectFigure.svelte';
import LocalhostFigure from './lib/components/channels/LocalhostFigure.svelte';
import ReleaseDiagram from './lib/components/channels/ReleaseDiagram.svelte';
</script>

<p class="kicker">Architecture · Distribution · <a href="/chat/">Llama Chat</a></p>

# One build, three channels

Llama Chat is a SvelteKit app built with `adapter-static`: plain HTML, JS and CSS in one `dist` folder. Each release builds it once and ships the same folder three ways. Only the thing serving it changes.

<Callout title="npx llama-chat and chat.llama.app are the client only">
They carry the UI and nothing else: no llama-server, no models, no inference. On first open they are connected to nothing; you add a llama-server by URL, or pair one through Llama Connect, before you can chat. Only the bundled channel comes with its own server.
</Callout>

<ReleaseDiagram />

## How the channels differ

The app works out its mode at runtime: if same-origin `/props` answers as llama.cpp it runs bundled; otherwise it runs hosted and opens on "add a server or pair one through Llama Connect". No build flags.

| | Bundled in llama-server | npx llama-chat | chat.llama.app |
| --- | --- | --- | --- |
| Served by | llama-server, or `llama serve` in the macOS and Windows apps (the same server) | a static file server in the package (UI only) | the static host |
| Origin | the server's own address | `http://localhost:<port>` | `https://chat.llama.app` |
| Comes with a server | yes, it is the server | no: UI only, add a llama-server | no: UI only, add a llama-server |
| Needs | llama-server, or a native app | Node | a browser |
| Reaches servers | its own, same origin; others via Providers | localhost and plain `http://` LAN servers by URL | `https://` and localhost by URL; anything else through Llama Connect |
| Response headers | set in `server-http.cpp` | set by the CLI | what the host allows |
| Chats stored | per server address | per localhost port | at chat.llama.app |
| Best for | "I run llama-server" or a native app | a server elsewhere on my network, offline use | trying it with no install, phones, Llama Connect |

## Llama Connect

Llama Connect pairs an app with a llama-server it cannot reach by URL: one started with `--connect` shows a code or QR, the app scans or types it, and the two talk directly over WebRTC. It is how chat.llama.app reaches a server behind a home router, and how a phone reaches the laptop next to it.

Conversations come with it. Chats stored on the device that runs the server, a laptop say, can be shared through Llama Connect and continued on a phone, then picked up again on the laptop.

<ConnectFigure />

## The npx command

Why npx still matters next to the hosted site: a llama-server on the LAN usually answers on plain `http://`, and an `https://` page cannot call it (browsers block it as mixed content). The same UI served from `http://localhost` can.

<LocalhostFigure />

Bare `npx llama-chat` starts it. One job, no verb, like `npx serve` or `npx http-server`; a required `start` would turn many first runs into a help screen.

```bash
# serve and open the browser
npx llama-chat

# connect to a server on launch
npx llama-chat --server http://192.168.1.20:8080

# reachable from other devices, no browser
npx llama-chat --host 0.0.0.0 --port 3000 --no-open
```

| Flag | Default | What it does |
| --- | --- | --- |
| `--server <url>` | `http://127.0.0.1:8080` | The llama-server the UI talks to. Today the CLI forwards the app's API calls to it; once the app can add servers by URL, it adds and selects that server instead, and without the flag the UI opens on the add-server screen |
| `--port <n>` | `3000` | Fixed, so the origin and the chats stored under it stay the same between runs |
| `--host <addr>` | `127.0.0.1` | `0.0.0.0` to open it to the LAN |
| `--open` / `--no-open` | open | Opens the default browser once it listens |
| `--version`, `--help` | | As usual |

- **Package:** `@ggml-org/llama-chat` with `"bin": {"llama-chat": "./bin/cli.js"}`, plus an unscoped `llama-chat` that depends on it at the same version and only runs its CLI, so `npx llama-chat` stays short.
- **What it runs:** a static file server (`node:http`) for `dist`, no dependencies: no llama-server, no models, no Vite or SvelteKit. Until the app can add servers by URL, paths with no file in `dist` go to the `--server` llama-server, without an `Origin`, as the Vite dev proxy sends them; the hash router needs no fallback.
- **Headers:** the same set llama-server sends, so the app behaves the same in both.
- **Later verbs** (`doctor`, `update`) keep the bare command as the default; `start` is an accepted alias, not the documented form.

## The hosted site

The static `dist` deploys as is: relative paths and the hash router work at the domain root. The host sends the same response headers llama-server does, so the app behaves the same in every channel; hashed assets can be cached for good, while `sw.js`, the manifest and `version.json` are never cached.

## Release flow

One CI job per llama.cpp release, after the build:

1. Upload `dist` to the Hugging Face bucket `ggml-org/llama-ui` (`b<build number>`), which llama-server's CMake build embeds.
2. Publish `@ggml-org/llama-chat` and `llama-chat` to npm: `dist` plus the CLI, versioned with the release.
3. Deploy `dist` to chat.llama.app.

chat.llama.app always runs the latest UI against servers of any version, so it needs feature detection through `/props` and a minimum-server-version message.
19 changes: 19 additions & 0 deletions ui/apps/chat/tests/stories/architecture/Chat.stories.svelte
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<script lang="ts" module>
import Page from './Chat.svx';
import Frame from './Frame.svelte';
import { defineMeta } from '@storybook/addon-svelte-csf';

const { Story } = defineMeta({
parameters: {
controls: { disable: true },
layout: 'fullscreen'
},
title: 'Architecture/Chat'
});
</script>

<Story asChild name="Chat">
<Frame>
<Page />
</Frame>
</Story>
103 changes: 103 additions & 0 deletions ui/apps/chat/tests/stories/architecture/Chat.svx
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
<!--
Architecture › Chat: Llama Chat as the reference app on Llama UI, its areas, how a message travels, its layers and
where each lands, and what it hands to the library. Set in the Editorial, through Frame.svelte.
-->

<script>
import Cards from './lib/components/ui/Cards.svelte';
import Card from './lib/components/ui/Card.svelte';
import MessageFlow from './lib/components/chat/MessageFlow.svelte';
import Layers from './lib/components/chat/Layers.svelte';
import Layer from './lib/components/chat/Layer.svelte';
</script>

<p class="kicker">Architecture · ui/apps/chat · <a href="/stack/">on the Llama UI stack</a></p>

# Llama Chat

<p class="lead">The first app on Llama UI, and the reference for the line between library and app. It runs local models through llama-server, with tools, MCP servers, projects, a prompt library, a models manager and several servers.</p>

## Its areas

<Cards>
<Card title="Chat">

`/chat/[id]`

Tabs, branching, regenerate, reasoning blocks, right-click message actions, expandable composer.

</Card>
<Card title="Projects">

`/projects/[id]`

Instructions, context files, a working directory; chats inside.

</Card>
<Card title="Library">

`/library`

Prompts: reusable system messages.

</Card>
<Card title="Models">

`/models`

Manager, Discover from Hugging Face, downloads, configuration pane.

</Card>
<Card title="Servers">

`/servers`

llama.cpp servers by URL or through Llama Connect, paired by code or QR.

</Card>
<Card title="MCP · Settings · Search">

`/mcp-servers …`

MCP servers and resources, settings sections, conversation search.

</Card>
</Cards>

## How a message travels

The agentic loop runs in the browser, through [Llama Harness](/stack/) (`@ggml-org/llama-harness`, in `ui/lib/harness`). It streams from the active server and runs any tool the model calls: in the browser, on llama-server, or on an MCP server. Chat gives the harness its chat service and its tools, each behind the permission gate, and stores the messages it reports.

<MessageFlow />

## Layers in the code

`ui/apps/chat/src` runs one way: routes, components, hooks, stores, services, then storage or the server. Tags show where each layer lands: UI and UX go to `ui/lib/ui`; everything that decides what happens stays in `ui/apps/chat`.

<Layers>
<Layer name="Routes" tag="ui/apps/chat" kind="new"><code>/</code> <code>/chat/[id]</code> <code>/projects/[projectId]/chat/[id]</code> <code>/library</code> <code>/models</code> <code>/servers</code> <code>/mcp-servers</code> <code>/settings</code> <code>/search</code></Layer>
<Layer name="App components" tag="ui/apps/chat" kind="new">chat (ChatScreen, ChatForm, ChatMessages, ChatTabs), navigation, projects, models (manager, Discover, configuration), servers, mcp, settings, dialogs. Their presentational parts (model selector, model card, badges, quant rows) move to the library as Model UI.</Layer>
<Layer name="UI components" tag="ui/lib/ui" kind="reuse">shadcn-svelte on bits-ui: alert, button, card, context-menu, dialog, drawer, dropdown-menu, input, popover, select, switch, table, tabs, tooltip and more.</Layer>
<Layer name="Hooks" tag="split" kind="mix">use-chat-screen-active-model, use-processing-state, use-context-gauge, use-models-selector, use-tools-panel. Interaction hooks go with their components; hooks that read app stores stay in the app.</Layer>
<Layer name="Stores" tag="ui/apps/chat" kind="new">chat, conversations, agentic, tools, permissions, mcp, models, models-discover, servers, remote-access, projects, groups, prompts, tabs, settings.</Layer>
<Layer name="Agentic loop" tag="ui/lib/harness" kind="reuse">Llama Harness: streams a turn, runs the tools the model called, repeats until it answers without one. The agentic store drives it and keeps the tools, permissions and storage.</Layer>
<Layer name="Services" tag="ui/apps/chat" kind="new">chat, models, props, database, mcp, tools, sandbox, servers, huggingface, settings, conversation-transfer.</Layer>
<Layer name="Styles" tag="ui/lib/ui" kind="reuse">"Matte Glass" tokens in three tiers: primitives, semantic (light and dark), components. Documented in <code>DESIGN.md</code> and Storybook.</Layer>
<Layer name="Storage + API" tag="outside" kind="ext">IndexedDB for conversations, projects, groups, prompts; localStorage for settings and permissions; llama-server <code>/v1</code>, <code>/props</code>, <code>/models</code>, <code>/tools</code>, <code>/slots</code>.</Layer>
</Layers>

## What Chat keeps, what it hands off

<Cards>
<Card title="Keeps">All business logic: conversations, tabs, groups, search, tools and permission gates, projects, the models manager, Discover, downloads, model configuration and Servers. MCP is the first feature that plugs in as an [extension](/extensions/).</Card>
<Card title="Gives the harness">The agentic loop, as `@ggml-org/llama-harness`: headless, no UI. Chat keeps the tools and the approval gate above it.</Card>
<Card title="Gives the library">Presentation only: thread, composer, tool-call blocks, permission prompt, model selector, model card, capability badges. They take data in and report what the user did out.</Card>
</Cards>

## Parts other apps reuse

<Cards>
<Card title="Thread + composer">Any app with a conversation reuses the thread and composer, and the Markdown renderer and editor with them.</Card>
<Card title="The loop + tool-call UI">An app runs the same loop through Llama Harness, or puts its own behind the same interface, and shows tool calls and permission prompts with the same library components.</Card>
<Card title="Model UI">The model selector, model card and badges serve every app and llama.app. Other apps call llama-server's OpenAI-compatible endpoints themselves; the full manager and Servers stay in Chat.</Card>
</Cards>
19 changes: 19 additions & 0 deletions ui/apps/chat/tests/stories/architecture/Extensions.stories.svelte
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<script lang="ts" module>
import Page from './Extensions.svx';
import Frame from './Frame.svelte';
import { defineMeta } from '@storybook/addon-svelte-csf';

const { Story } = defineMeta({
parameters: {
controls: { disable: true },
layout: 'fullscreen'
},
title: 'Architecture/Extensions'
});
</script>

<Story asChild name="Extensions">
<Frame>
<Page />
</Frame>
</Story>
Loading
Loading