lmchatkit

LMChatKit

A self-contained chat UI + backend protocol that mounts into any Go HTTP server. The host implements the Host interface to provide an LLM completion stream and (optionally) MCP tools, prompts, and resources; lmchatkit owns the frontend bundle, the streaming chat protocol, persona loading, and slash-command loading.

Built for — and extracted from — paularlott/llmrouter, with the contract shaped so other OpenAI-compatible hosts (e.g. paularlott/knot) can mount the same UI without forking it.

Features

• Streaming chat over a custom SSE protocol (delta / tool_call / done / error events). Not OpenAI-shaped — designed for chat UIs, so tool-call confirmation, per-tool disable, and "always allow this tool in this chat" all live in the frontend without server-side session state.
• Persona loading from a watched TOML directory (system_prompt, default_model, [params] table). Hot-reloads on file change. A built-in Default persona is always offered even when the dir is empty.
• Slash commands from a watched markdown directory. help.md → /help. $ARGUMENTS in the body is spliced with whatever the user typed after the command.
• MCP pass-through for tools, prompts, and resources via the Host interface — the host decides where they come from.
• MCP Apps rendering: a tool result linked to a ui:// resource (SEP-1865) mounts in a sandboxed, auto-resizing iframe instead of plain text — no host code beyond the Host interface's existing CallTool/ReadResource.
• Tool-call confirmation flow with per-session auto-allow, persisted in browser sessionStorage. The server owns the tool list; the browser only handles approval (Allow / Always Allow / Deny).
• Bundles its own HTML/CSS/JS — the host just calls Mount(mux). The frontend reuses the host's bundled Alpine + Tailwind; lmchatkit doesn't ship a copy.
• Auth is host-owned — pass an AuthMiddleware in Config and it wraps every lmchatkit handler.

Install

go get github.com/paularlott/lmchatkit

Go 1.26+. The package has three direct dependencies: fsnotify/fsnotify, paularlott/cli, paularlott/logger.

Host contract

Implement Host:

type Host interface {
    // Models returns the models the chat user may select from.
    Models(ctx context.Context) ([]Model, error)

    // Complete streams a chat completion. Emit EventDelta / EventToolCall
    // values onto events, then return. If you emit tool calls, the frontend
    // will execute them via CallTool and resubmit the conversation.
    Complete(ctx context.Context, req CompleteRequest, events chan<- Event) error

    // MCP pass-through. May return nil/empty if the host has nothing to offer.
    ListTools(ctx context.Context) ([]Tool, error)
    CallTool(ctx context.Context, name string, arguments json.RawMessage) (ToolResult, error)
    ListPrompts(ctx context.Context) ([]Prompt, error)
    GetPrompt(ctx context.Context, name string, args map[string]string) (PromptResult, error)
    ListResources(ctx context.Context) ([]Resource, error)
    ReadResource(ctx context.Context, uri string) (ResourceResult, error)
}

Host must be safe for concurrent use — lmchatkit is stateless and one Server may serve many simultaneous sessions across many users.

Optional interfaces

Hosts may implement additional interfaces for extended behaviour:

StandardHost implements SystemPromptAugmenter via a function field (nil = passthrough).

Persona & slash-command sources

Personas and slash commands each come from a pluggable source. Two builtin implementations cover the common cases; hosts with a different backing store (e.g. a database, or a single hard-coded system persona) supply their own.

type PersonaSource interface {
    Personas(ctx context.Context) ([]Persona, error)
}
type CommandSource interface {
    Commands(ctx context.Context) ([]SlashCommand, error)
}

The source is consulted on every request, so a DB-backed source always reflects the current row set without a watcher.

For knot's "one persona, one model, no per-user commands" case:

srv, _ := lmchatkit.New(lmchatkit.Config{
    Prefix: "/chat",
    Host:   knotHost,
    PersonaSource: lmchatkit.StaticPersonas{{
        ID: "knot", Name: "Knot", SystemPrompt: knotSystemPrompt, DefaultModel: "knot-1",
    }},
    // CommandsDir / CommandSource left nil — slash commands disabled.
    HostJSFile:  "/assets/knot.js",
    HostCSSFile: "/assets/knot.css",
})

When the host returns exactly one persona AND one model, the chat UI skips the persona/model picker entirely and drops the user straight into a conversation. (They can still hit "New Chat" to come back to the picker.)

Mount

import "github.com/paularlott/lmchatkit"

srv, err := lmchatkit.New(lmchatkit.Config{
    Prefix:       "/chat",
    PersonasDir:  "/etc/myapp/personas",
    CommandsDir:  "/etc/myapp/commands",
    Host:         myHost,
    AuthMiddleware: authMiddleware,  // wraps every handler; nil = no auth
    History:      historyStore,      // nil = browser sessionStorage fallback
    Events:       eventBroadcaster,  // nil = no SSE push (browser polls)
})

Conversation history (pluggable persistence)

By default (when Config.History is nil), conversations live in browser sessionStorage — ephemeral, per-tab, cleared on browser close. No server-side storage, no cross-tab sync.

When Config.History is set to a HistoryStore implementation, lmchatkit mounts conversation CRUD endpoints and the browser switches to server-side mode automatically:

The browser detects server-side mode on init by probing GET /api/conversations. If it returns 200, all conversation CRUD goes through the API. If 404 (HistoryStore not configured), it falls back to sessionStorage. No configuration needed on the browser side.

HistoryStore interface

type HistoryStore interface {
    List(ctx context.Context) ([]ConversationSummary, error)
    Get(ctx context.Context, id string) (*StoredConversation, error)
    Save(ctx context.Context, conv *StoredConversation) error
    Delete(ctx context.Context, id string) error
}

ConversationSummary is the lightweight sidebar entry (id, title, persona, model, timestamps). StoredConversation embeds it and adds Messages and EnabledTools. For per-user stores (knot), extract the user from the context.

llmrouter implementation

Uses snapshotkv (the same persistent store as MCP server config, but with a separate key prefix):

All three share one snapshotkv database file but use distinct key prefixes, so they never collide. The FindKeysByPrefix scans are prefix-scoped. Memory-only mode (no --storage-path) falls back to an in-memory map — conversations work during the process but don't persist across restarts.

SSE event stream (cross-tab sync + push notifications)

When Config.Events is set to an *EventBroadcaster, lmchatkit mounts GET {prefix}/api/events — a single SSE endpoint per browser tab. The server pushes:

This replaces polling — no fetch-on-done, no timers. Changes are pushed the instant they happen. The browser uses EventSource (native SSE client) which auto-reconnects on disconnect.

That registers:

| Route                              | Purpose                                            |
|------------------------------------|----------------------------------------------------|
| `GET /chat`                        | HTML shell (server-rendered; the rest is Alpine)   |
| `GET /chat/api/personas`           | Persona list (incl. built-in `Default`)            |
| `GET /chat/api/commands`           | Slash-command list (incl. rendered markdown body)  |
| `GET /chat/api/models`             | Models from `Host.Models`                          |
| `POST /chat/api/chat`              | Streaming completion (SSE response)                |
| `POST /chat/api/tools/call`        | Execute one tool (after user approval, or `source: "app"` from a mounted view — see [MCP Apps](#mcp-apps-rendering-interactive-tool-uis)) |
| `GET /chat/api/prompts`            | Prompts from `Host.ListPrompts`                    |
| `POST /chat/api/prompts/get`       | Render a prompt                                    |
| `GET /chat/api/resources`          | Resources (static + templates) from `Host`         |
| `POST /chat/api/resources/read`    | Read one resource                                  |
| `GET /chat/assets/*`               | Embedded `chat.js` bundle                          |

## Chat protocol

`POST /chat/api/chat` streams Server-Sent Events. Each event is one JSON-encoded [`Event`](types.go) prefixed with `data: ` and terminated by `\n\n`:

data: {"type":"delta","delta":"Hello"}

data: {"type":"reasoning","reasoning":"Let me think about this..."}

data: {"type":"tool_call","tool_call":{"id":"call_1","name":"search","arguments":{"q":"x"}}}

data: {"type":"done","finish_reason":"tool_calls"}

Event types: `delta` (visible text), `reasoning` (thinking/reasoning text, rendered in a collapsible Thinking disclosure), `tool_call` (model requests a tool), `done` (stream complete), `error`.

The frontend reads with `fetch` + `ReadableStream` (not `EventSource` — `EventSource` can't POST). On `tool_call`, the UI prompts the user; on approve it `POST /api/tools/call`s the tool, appends the result to the conversation, and re-`POST /api/chat`s to continue. On `done` or `error` the turn finalizes.

### Tool management

The server owns the tool list entirely. On each `/api/chat` request, the server calls `Host.ListTools` to get available tools, injects the virtual `lmchatkit__get_skill` tool if skills exist, and forwards everything to the LLM. The browser never sees the tool list — it only handles the approval flow (Allow / Always Allow / Deny) when tool calls arrive as SSE events. Tool enable/disable is managed at the MCP server level (e.g. via the admin UI), not per-conversation in the browser.

This protocol is intentionally **not** OpenAI-shaped — the host's `Complete` implementation is free to call OpenAI, Anthropic, a local llama.cpp, or anything else. The reference implementation in `llmrouter` does a loopback HTTP call to its own `/v1/chat/completions` and translates OpenAI's SSE format into lmchatkit events (including `delta.reasoning_content` / `delta.reasoning` → `EventReasoning`).

The chat request body is minimal — `{model, persona_id, messages, params}`. The server derives the system prompt from the persona (looked up by `persona_id` in the in-memory persona cache), builds the tool list from `Host.ListTools`, and injects virtual tools (`lmchatkit__get_skill`). The browser never sends system messages or tool definitions.

## MCP Apps (rendering interactive tool UIs)

When a tool result's `ui` field carries a `resourceUri` — [SEP-1865](https://github.com/modelcontextprotocol/ext-apps), the "MCP Apps" extension — the frontend renders that tool call's linked `ui://` resource instead of (or alongside) its plain-text result. No `Host` interface change is needed: `ToolResult.UI` and `ResourceResult.UI` ride along on the existing `CallTool`/`ReadResource` methods, so any host whose backing MCP server declares `_meta.ui` on a tool gets this for free.

### How it works

1. `executeToolCall` sees `data.ui.resourceUri` on a `POST /api/tools/call` response and fetches that resource via the existing `POST /api/resources/read`; the fetched content is stored on `call.appResource`.
2. Once `call.appResource` resolves, the template mounts a container element, whose `x-effect` calls `mountAppView(call, container)` (`web/src/chat.js`) — this builds a CSP `<meta>` tag from the resource's `ui.csp` hints, injects it into the HTML, and renders it into a `<iframe sandbox="allow-scripts allow-forms">` via `srcdoc`.
3. `mountAppView` then plays the **host** side of the extension's `postMessage` protocol: it replies to the view's `ui/initialize` with `hostInfo`/`hostCapabilities`/`hostContext` (including `containerDimensions: { maxHeight: 700 }`, letting the view size itself up to that cap instead of the host guessing a fixed height); after `ui/notifications/initialized` it pushes `ui/notifications/tool-input` (the call's arguments) and `ui/notifications/tool-result` (`content`/`structuredContent`/`isError`); and it proxies any further `tools/call` / `resources/read` the view sends to this server's own `/api/tools/call` / `/api/resources/read` routes and relays the reply.
4. The view reports its own content height via `ui/notifications/size-changed`; `mountAppView` applies it directly to the iframe's `style.height`, so the card grows or shrinks to fit instead of a fixed guess. Only `height` is applied — `width` stays under the iframe's own `w-full` CSS, deliberately, to avoid a resize feedback loop with content that itself reacts to container width (e.g. a Chart.js canvas with `responsive: true`).
5. A tool call an app-only view makes itself (`resolveAppToolName` maps its bare tool name to this call's own `namespace__`-prefixed one, so an app's own script doesn't need to know the federation prefix) round-trips through the same `/api/tools/call` route as a model-initiated call, tagged `source: "app"`. It does **not** go through the model-call approval dialog — an app-driven action (a form submission, a "claim" button) executes as soon as the user interacts with the mounted view, the same way clicking a button in any other web app doesn't ask "are you sure" a second time. What *is* enforced, server-side, on every call regardless of source: [MCP Apps visibility](https://github.com/modelcontextprotocol/ext-apps) (`_meta.ui.visibility`) — a `source: "app"` call may only reach a tool whose visibility includes `"app"`, and a model-approved call may only reach one whose visibility includes `"model"` (`handleCallTool`'s `toolVisibilityAllows`, checked against `Host.ListTools`' full, unfiltered result — not the model-facing list below, which already excludes app-only tools).
6. `Host.ListTools` itself returns every tool regardless of visibility (needed for step 5's lookup); the tool list actually sent to the model goes through `FilterToolsForModel` first, which drops anything whose visibility excludes `"model"` — an app-only action tool is never offered to (or callable by) the model in the first place.
7. `call.ui`/`call.structuredContent`/`call.appResource` persist on the stored `call` object (same mechanism as `call.result`), so reloading the page or switching conversations remounts the same app deterministically instead of losing it.

A note on the trust model: `source: "app"` and `via` are protocol data the *caller* supplies, not authentication — they're honest when they arrive through the view bridge (the bridge hardcodes both; the view can't influence them through `postMessage`), but a direct HTTP client with page credentials could set them to anything. The layers that actually contain a malicious view are structural: the iframe is `srcdoc` with an opaque origin (no `allow-same-origin`, so no access to host DOM/cookies/storage) and a CSP built from the server's declared domains only, and cross-origin `fetch` from the view to `/api/*` fails preflight (no CORS headers). The role/ownership checks narrow what a *spec-conforming* view can reach; the sandbox is what bounds a non-conforming one. Put a real authentication layer in front of `Mount`'s routes for anything exposed beyond localhost — `source`/`via` checking is not one.

See the [MCP Apps guide](https://github.com/paularlott/mcp/blob/main/docs/guides/mcp-apps.md) in `paularlott/mcp` for the server-side half of the contract (`_meta.ui`, CSP metadata, `containerDimensions`/`size-changed`), and `paularlott/mcp`'s `examples/mcp-app-host-harness` for a minimal standalone implementation of the same host-side bridge outside of lmchatkit.

## Personas

One TOML file per persona. The filename stem becomes a stable identifier; the `name` field is the display name. See `examples/personas/` for ready-to-use examples.

```toml
# examples/personas/coder.toml
name = "Code Assistant"
description = "Helps with code review, writing tests, and debugging."
system_prompt = """You are a senior software engineer with decades of experience.
Always prefer readable, maintainable code over clever one-liners.
When suggesting changes, explain WHY, not just WHAT."""

[params]
temperature     = 0.2     # randomness (0 = deterministic, 1 = creative)
top_p          = 0.95    # nucleus sampling threshold
top_k          = 40      # top-k sampling (llama.cpp / Ollama)
repeat_penalty  = 1.1     # penalise repeated tokens (llama.cpp / Ollama)
context_length  = 8192    # max context window in tokens
reasoning_effort = "low"  # reasoning models: low, medium or high

All fields are optional except name (which falls back to the filename stem if omitted). default_model is also optional — when omitted, the user picks a model from the picker. [params] is a free-form map merged into every completion request — standard OpenAI params (temperature, top_p, max_tokens, frequency_penalty, presence_penalty, reasoning_effort) and llama.cpp/Ollama params (top_k, repeat_penalty, context_length) are all forwarded to the host, which passes them through to the underlying API. The server merges the persona's params into every request, so ones the chat UI has no field for still reach the model; values set in the UI win.

The directory is watched with fsnotify; adding or editing a persona takes effect on the next request without restarting the server.

When no PersonasDir is configured, the chat still works — a single built-in Default persona with no system prompt is offered.

Slash commands

One Markdown file per command. The filename (minus .md) is the command name, lowercased. Use $ARGUMENTS in the body to splice whatever the user typed after the command. See examples/commands/ for ready-to-use examples.

Commands support optional YAML frontmatter at the top of the file (Claude CLI style):

<!-- examples/commands/review.md -->
---
description: Review code and suggest improvements
argument-hint: <paste-code-or-describe-changes>
---

Review the following code or changes. Focus on:

1. **Correctness** — bugs, edge cases, logic errors
2. **Readability** — naming, structure, comments

Code or description to review:

$ARGUMENTS

Frontmatter fields:

• description — shown in the slash command dropdown
• argument-hint — placeholder hint shown after the command name (e.g. <github-handle>)
• allowed-tools — comma-separated tool names to auto-approve for this session when the command runs (Claude CLI style; patterns like Bash(git:*) are stripped to just the tool name)

Rules:

• Filenames beginning with _ are drafts (skipped).
• Names are restricted to letters, digits, -, _ (so they stay unambiguous in chat input and shell-safe).
• /Help and /help both resolve — the name is lowercased before lookup.
• The directory is watched; commands hot-reload.

When no CommandsDir is configured, slash commands are disabled entirely. Typing /anything is then sent to the model as a literal user message.

MCP prompts (slash commands from the MCP server)

MCP prompts merge into the same / namespace as file-based slash commands. The user invokes them identically — there's no separate /prompt prefix. File commands take precedence on name collision.

How it works

When the user types /explain concept=recursion level=simple:

1. The frontend checks file-based commands first — no match for explain
2. Falls through to MCP prompts — finds explain with declared args concept (required) and level (optional)
3. Parses arguments: key=value pairs, or positional shorthand for single-arg prompts (/summarise some text → {text: "some text"})
4. Calls POST {prefix}/api/prompts/get with the name and parsed args
5. The host's GetPrompt renders the prompt and returns messages
6. Those messages are injected into the conversation and a completion turn starts

Autocomplete

Typing / shows a unified dropdown of file commands and MCP prompts. MCP prompts are marked with a purple bolt icon and show their argument names (e.g. concept* level) in the hint column. Arrow keys navigate, Enter/Tab selects.

Discovery

• /list-prompts — renders an info card listing all available MCP prompts with their argument signatures
• /list-resources — renders an info card listing all available MCP resources with their URIs

Prompt arguments

Arguments are parsed from the text after the command name:

/explain concept=recursion level=advanced
/summarise this is a long block of text that goes to the single "text" arg
/review code="print('hello')"

If the prompt declares exactly one argument and the input has no = signs, the entire remainder is assigned to that argument positionally. Otherwise, key=value pairs are extracted.

MCP resources (attach context with @)

MCP resources are data the user can attach to a message as context for the model. They appear as attachment chips (like email attachments) on the user's message bubble — the raw content is hidden from the transcript but sent to the model as prefixed context.

How it works

1. User types @ in the composer — a green dropdown shows matching resource URIs
2. Selecting a resource reads it immediately via POST {prefix}/api/resources/read
3. The content is added to a pending-attachments tray below the textarea (green chips with remove buttons)
4. On send, each attachment's content is prepended to the user's message text:

Resource docs://readme.md:
<full resource content here>

<user's actual message text>

1. The model sees the full resource text; the transcript shows only the chip.

Resource templates

Template resources (with {var} placeholders in the URI) appear in the dropdown marked as "template". The user types the variable part into the URI — e.g. selecting greeting://{name} and the frontend reads greeting://Ada (the @ autocomplete matches on URI substring, so typing @greet or @Ada finds it).

Multiple attachments

Multiple @resource selections can be attached to a single message. Each is rendered as a separate chip and its content is injected separately.

Skills (lazy-loaded context via virtual tool)

Skills are resources with a skill:// URI prefix that the model can retrieve on demand. Unlike @resource attachments (which the user manually adds), skills are model-driven — the LLM decides it needs a skill and calls a tool to get it.

How it works

1. On every /api/chat and /api/tools request, lmchatkit checks the host for skill:// resources
2. If any exist, a virtual tool lmchatkit__get_skill is appended to the tool list
3. The host's SystemPromptAugmenter (if implemented) appends skill names + descriptions to the system prompt
4. The model calls lmchatkit__get_skill with a skill URI (e.g. skill://golang)
5. lmchatkit intercepts the call and routes it to Host.ReadResource — never touches the MCP server
6. The skill content is returned as a tool result; the model reads it and continues

The tool is auto-approved by the browser (added to autoAllowTools on init) — skill loading is invisible to the user, no approval prompt.

Why lmchatkit__get_skill?

The lmchatkit__ prefix prevents collisions: local scriptling tools have no prefix, remote MCP tools get their namespace__ prefix. The tool is conditional — only appears when skill:// resources exist.

SystemPromptAugmenter (optional host interface)

Hosts can implement this to dynamically augment the system prompt on every chat request:

type SystemPromptAugmenter interface {
    AugmentSystemPrompt(ctx context.Context, current string) string
}

StandardHost implements it via a SystemPromptAugmenter function field (nil = passthrough). The returned string replaces the system prompt sent to the LLM. The stored conversation is not modified — augmentation is transient, recomputed on each request.

StandardHost also exposes the function directly:

host := &lmchatkit.StandardHost{
    SystemPromptAugmenter: func(ctx context.Context, current string) string {
        return current + "\n\n" + buildSkillIndex(ctx)
    },
    // ...
}

Skill sources

Skills work from any resource source because the virtual tool calls the standard Host.ReadResource — files (scriptling), remote MCP servers, databases, or custom providers. The source is transparent.

Frontend

The chat UI lives in web/:

• web/src/chat.js — Alpine data component (includes the markdown processor). Conversations persist to sessionStorage. The frontend does not bundle its own Alpine or Tailwind — it loads them from the host's bundled assets. This keeps lmchatkit free of CDN dependencies and version skew.
• examples/chat.html — reference template that hosts copy into their own template tree (where Tailwind can scan it during build).

Script-order gotcha

The host's bundle calls Alpine.start() synchronously at the bottom. start() immediately dispatches alpine:init — the only window in which Alpine.data(...) registrations are accepted. So chat.js must run BEFORE the host bundle. The shipped example template orders the two <script defer> tags accordingly; if you customise the template, preserve that order.

Auth

Auth is entirely the host's responsibility. lmchatkit takes an AuthMiddleware func(http.Handler) http.Handler in Config and wraps every handler with it. The host decides what auth means — session cookie, bearer token, mTLS, IP allow-list, anything. nil means no auth (rare; appropriate only for fully internal hosts).

The host's template provides whatever login/logout UI it wants — lmchatkit's JS has no knowledge of auth endpoints.

Testing

go test ./...

Coverage focuses on the protocol handlers (chat streaming, tool filtering, tool execution, prompt rendering, resource reading), the persona and command loaders (TOML parsing, hot reload, edge cases), and the SSE translator. The frontend is not unit-tested; verify changes manually.

License

See LICENSE.txt.