Skip to main content
Moved to App Settings in v0.129.0

The tuning values on this page are configured in the in-app App Settings screen (sidebar footer, sliders icon) and stored in app_settings.jsonc -- not in .env. A value left in .env is ignored and named once in the startup log; run chatwalaau settings migrate --write to carry an existing configuration across. Feature enable-gates and secrets stay in .env. See Configuration -> Application settings.

Chat & UI

ChatWalaʻau talks to AI agents over the AG-UI protocol (SSE streaming) and renders replies in a clean, modern chat surface.

Rich message rendering​

  • Markdown, code blocks, math (KaTeX), and Mermaid diagrams -- math accepts both the $...$ / $$...$$ and the LaTeX \(...\) / \[...\] delimiter styles. $$...$$ and \[...\] render as a centred display block, $...$ and \(...\) render inline
  • LLM reasoning visualization -- collapsible "thinking" blocks for reasoning models
  • Web search with inline citations -- OpenAI hosted web search for OpenAI-family models, Anthropic hosted web search for Claude (stray citation markers are removed)
  • Multimodal image analysis -- attach images by file picker, drag-and-drop, or URL for vision models
  • Attach a PDF and analyze it -- an attached PDF is given to the model as context, the same way an image is. On Azure OpenAI / OpenAI / Foundry it is attached natively (the model reads text, tables, even scanned pages); on providers whose connector can't take a PDF (e.g. Anthropic) the text is extracted and included instead. Controlled by PDF_ATTACH_MODE (auto / native / text); the text path is capped by PDF_INLINE_MAX_CHARS (default 20000), and a scanned/image-only PDF there suggests the RAG pipeline
  • Images are served privately -- attached and generated images load through an authenticated request (your session cookie), so an image URL only opens for a signed-in user and gives an authentication error to anyone else. When web login (AUTH_USERNAME) is enabled this holds even on localhost and behind a dev/reverse proxy; with no web login configured, local (loopback) use stays open with no configuration

Paint a drawing​

Open Paint from the "+" menu next to the message box to compose an image right in the chat, then attach it like any other picture.

  • Full-screen canvas -- draw freehand strokes, lines, arrows, rectangles, ellipses, and text; select, move, and scale/rotate each object with handles
  • A page on a workspace -- the drawing has a fixed size (the artboard) and floats on a grey backdrop; anything you draw outside it is dimmed, so it is always obvious what will end up in the exported image
  • Pick a canvas size -- presets for 16:9, 4:3, and 1:1 (up to 4K), a Swap orientation button, Fit to window, or a Custom size with an optional aspect-ratio lock. A new drawing starts at 1280x720, so the same drawing exports at the same size on every machine. Sizes are capped at 4096 px per side and 12 megapixels total, and an over-budget size is refused as you type it rather than when you try to attach it
  • Pan and zoom -- the Hand tool (H), or hold Space and drag, or drag with the middle mouse button, or use the wheel (Shift+wheel scrolls sideways). Ctrl+wheel zooms where your cursor is. Zoom spans 5%-800%, with Fit (Ctrl+0), 1:1 (Ctrl+1), and Zoom to selection. The view opens fitted to the artboard and re-fits whenever the drawing area changes size, until you zoom or pan yourself -- after that your view is kept, and Fit hands it back to automatic framing
  • Arrows and lines that stick to your shapes -- draw an arrow between two boxes and it stays attached when you move them, re-aiming at the facing edges. Choose the shape (straight / elbow / curved) and the head at each end (none / arrow / triangle / diamond / circle / bar). Drag an endpoint near a shape and it snaps; hold Alt to place it freely. Arrows are edited by dragging their two endpoints, which is what you actually want on a diagonal, and deleting a shape leaves the arrow where it is rather than making it vanish
  • Layers -- reorder objects front-to-back and toggle visibility or lock per object
  • Duplicate and copy/paste objects -- right-click an object on the canvas, or its row in the Layers panel, for Duplicate / Cut / Copy / Paste, front-and-back ordering, lock, hide, and delete. Ctrl+D, Ctrl+X, Ctrl+C, Ctrl+V work too, and pasting from the canvas menu drops the copy where you clicked
  • Bring in art from anywhere -- drag-and-drop or paste an image to place it on the canvas; paste SVG markup and it is detected automatically and added as editable vector shapes. Pasting from another app always wins over the internal object clipboard, so this keeps working exactly as before
  • Load an image from your device or the coding workspace -- the Import button offers From this device and, when the coding workspace is enabled, From workspace (a picker that browses the workspace for images) -- handy where local file uploads are restricted. Only image files (png/jpg/jpeg/gif/webp/bmp/svg) are offered, and a loading indicator runs until the image is on the canvas
  • Undo/redo while you work
  • Download or attach -- save your drawing as a PNG, or attach it straight to the message. The exported image is the artboard and nothing else, and it looks the same whatever your current zoom and scroll position
  • Re-edit later -- an attached drawing keeps an editable copy, so you can reopen it from the thumbnail before sending, or from a sent message (which starts a fresh, editable attachment) and keep working. Drawings saved before this release reopen at the size they were saved with

Reading long conversations​

  • Conversation navigator -- a floating right-edge rail of your questions in long chats; click to jump straight to any of your messages (shown on the full-page chat when the window is wide enough)

  • A two-row message box (since v0.167.0) -- the text area has the first row to itself at full width, and every control sits on the second: attach, the agent icon, voice input, Live conversation (since v0.169.0) and Send. Each icon names itself on hover, and that is the same name a screen reader announces. The text area is about 15% wider than before, so long messages wrap fewer times

  • Choose the agent from the message box -- the icon on the control row shows the KIND (a robot for an agent, a graph for a workflow, a hammer for a harness agent). Hover it to read which one, and click it to open the agent picker. Since v0.167.0 the picker opens on a desktop too, not only on a phone, and it highlights the agent you are on. To create, edit or delete an agent, use "Manage agents..." at the foot of the picker, or the Declarative Agents icon in the sidebar footer

  • Step through messages -- previous / next buttons beside the scroll-to-bottom control move you one message at a time, through both your messages and the assistant's. They appear whenever the conversation is long enough to scroll, and the arrow that no longer applies is hidden at the very top or bottom

  • Context window warning -- since v0.167.0 the message box itself tells you when the window is filling up, and stays quiet otherwise. Below 80% there is nothing to see, including on a chat that has not answered yet. At 80% the message box outline turns amber; at 95% it turns red and a warning icon appears beside Send. Hover the message box (or let a screen reader read it) and it states the percentage in words, so the warning never depends on colour alone. The measurement is unchanged: it is what the next message will carry as context, including prompt tokens served from cache, and after Declarative Workflow turns it is an estimate, because a workflow's reply becomes history for your next chat turn.

    Before v0.167.0 this was a progress bar above the input showing 62% (124K / 200K) at all times. The number now lives in the per-turn dialog below -- click the in / out counts under the last answer. The bar was a permanent element that was actionable for about a fifth of its life, and on a new chat it reported 0% (0 / 200K) forever

  • Per-turn token usage -- input/output token counts on each assistant message. Click the counts to see the whole turn's breakdown: how many model calls it made, uncached input, cache reads and writes, output and the reasoning tokens within it. A turn that uses tools makes several model calls, so the total can be far larger than the counts on the label. A Declarative Workflow reply (since v0.154.0) shows the whole run's total instead, and its breakdown lists every node that ran and the context occupancy of the node that came closest to its model's window. Since v0.145.0 the same figures are also written to a durable ledger, readable through the Usage Statistics API -- so deleting the chat no longer takes its spending record with it. Since v0.157.0 you can browse it in the app on the Token Usage Dashboard

  • Collapse long messages -- a long message you sent is shown trimmed to about five lines with a Show more / Show less toggle, so the transcript stays easy to scan

  • Smooth large sessions -- opening a long conversation stays responsive; only the streaming message re-renders, so scrolling and typing do not slow down as the message count grows

Message actions​

Hover any message for copy, edit, regenerate, branch, and delete. On a touch screen the actions are always shown.

  • Edit opens a full-screen editor (a modal covering ~80% of the window), so revising a long message is comfortable. Editing a question re-runs the conversation from that point; editing an answer updates it in place. Cmd/Ctrl+Enter saves, Esc cancels.
  • Branch starts a new chat that holds the conversation up to that message. The new chat keeps the original's title and folder, appears in the sidebar right away, and has its own copy of the images -- deleting the original chat later does not affect it. A branch is never pinned, even when the original is. See Branched chats.
Every reply is saved before you continue

When an answer finishes, it is saved before the chat accepts the next message. If the server cannot save it right away, the chat is locked and a Saving the reply... indicator appears in the middle of the screen while it retries (after 1, 2 and 4 seconds). If it still cannot save, an error tells you the reply will be missing after a reload. A chat whose history cannot be read is shown as This chat could not be loaded with a Retry button -- never as an empty chat. (Since v0.157.1.)

Layouts and language​

  • Three layout scenarios -- Chat, Popup, and Sidebar
  • Multilingual chat -- browser auto-translation is suppressed so multilingual content renders correctly

On a phone​

The chat screen and the chat list adapt to a phone-sized screen (narrower than 768 px).

  • The chat list opens as a drawer from the menu button and closes when you pick a chat, tap outside it, or press Esc.
  • One header row holds the menu, Privacy Screen and Temporary Chat, so nothing covers the first message. The composer stays above the on-screen keyboard.
  • Everything a conversation needs is there: the agent icon (which is also where the model and reasoning effort are chosen), the context-window warning on the message box itself, token usage, image and PDF attachment, voice input, workflow progress, and every message action.

Choose the agent​

Since v0.167.0 this is the same on a phone and on a desktop. Before that, the control opened this picker on a phone and the full Declarative Agents & Workflows modal on a desktop -- which spent the heavier screen on the action you take most often.

The icon on the message box's control row says which KIND of run-target answers, and hovering it names the one you are on. Tap or click it to open a list of everything that can answer -- the built-in agent, your agents, workflows and harness agents -- with a search box for long lists. Tap one to switch.

The same sheet carries the built-in agent's model and reasoning effort, so a phone can change how it thinks without a desktop. Structured Output is set on the desktop.

  • A workflow or harness agent applies at once, on this device only.

  • An agent (including the built-in one) applies to the whole application: every browser and every chat, not only your phone. That switch asks you to confirm first and takes a moment while the agents are rebuilt.

  • An entry that cannot run is greyed out with the reason. Fix it on a desktop, where creating and editing live.

  • To go back from a workflow or harness agent, pick the built-in agent (or any agent).

  • Administration stays on the desktop. The managers and editors (Declarative Agents, Pipeline jobs, Webhooks, Cron, File Explorer, Agent memory, Ontology, App Settings, Paint, the image editor, prompt templates, the workflow diagram) and the MCP tools and Skills controls are not shown. Hiding them switches nothing off: what you selected on the desktop keeps working, and the agent can be switched from the composer (above).

  • On a phone-sized screen, Enter inserts a newline -- send with the send button. On wider screens (including touchscreen laptops and tablets) Enter sends as usual.

  • On any touch screen, hover-only controls are always visible.

  • The page fits what the browser shows, so on iPad and iPhone the composer is never hidden under Safari's tab bar or toolbar. It stays in place when the keyboard opens and re-fits after you rotate the device.

  • Folders cannot be drag-reordered on a phone; use Move to folder in the chat menu. File links in answers keep Download.

To reach ChatWalaʻau from a phone, the server must listen on your network with sign-in enabled -- see Authentication. Voice input needs HTTPS on a LAN address; localhost is always allowed.

Stray citation markers​

A model that searched the web sometimes writes its own internal citation marks instead of the source links it was asked for. They look like empty boxes around text such as citeturn0search0 and mean nothing to a reader.

Those marks are removed from the answer before it reaches you, so they are not shown, not stored with the conversation, and not returned by chat search. When a turn contained them, a small grey note appears next to the message actions -- for example Citation markers removed: turn0search0 (1) -- so you can tell which answers were affected; hovering it shows the run id, which the server log records on the same line.

The note belongs to the live turn only: reloading the chat shows the clean answer without it. Answers written before v0.159.0 keep whatever they stored.

Temporary Chat​

A Temporary Chat is an "incognito-style" throwaway conversation, started from the top-right of the chat screen.

  • It does not appear in your history or search, and cannot be resumed -- closing, leaving, or reloading discards it.
  • It runs de-personalized: the agent uses only its base Identity and never reads or writes your saved preferences, while all other tools stay available.
  • The input turns dark while active.
  • For safety it is briefly retained server-side (TEMPORARY_CHAT_RETENTION_DAYS, default 30) and then auto-deleted -- "not in your history", not "never stored".

It is also available on the API via an opt-in temporary flag (default off).

Privacy Screen​

Presenting from your real instance? Privacy Screen scrambles the private side of the screen so you can share it. Toggle it with the eye-with-a-slash icon at the top right of the chat screen, just left of Temporary Chat.

While it is on:

  • Chat history, your own messages, folder names, and attached filenames render as scrambled text. Line breaks and character widths are kept, so nothing on the page moves when you toggle it.
  • Images and PDFs in past messages become placeholders, and they are not downloaded at all while the mode is on.
  • Search still works, but results are scrambled and matches are not highlighted.
  • Copying a message of yours copies the scrambled text, so the original cannot reach your clipboard by accident.
  • Editing a message and renaming a chat are unavailable -- both would have to put the original text back on screen in an editable box.

The setting survives a reload, so refreshing mid-presentation will not un-scramble your screen. The amber Privacy pill is always visible while it is on, so you can tell at a glance.

What it does not cover​

Privacy Screen hides your side of the conversation, not the whole app. It does not hide:

  • the agent's replies -- and if a reply quotes your message, that text is visible;
  • tool call arguments, saved memory, prompt templates, workspace files, scheduled jobs, or your account name;
  • whatever you type live -- the message box and the search field are yours to control.

For a demo where none of that can appear, present from a chat prepared for the purpose.