Skip to content

Uni for AI Agents ​

Uni is a single Scala 3 library (org.wvlet.uni) that covers object wiring, logging, JSON/MessagePack serialization, reactive streams, HTTP client/server, typed RPC, MCP servers, and unit testing, and the same code runs on the JVM, Scala.js, and Scala Native. It is the Scala 3 successor of Airframe.

This page is written for AI coding agents (Claude Code, Codex, Cursor, Copilot, and others) and for the people who configure them. It sums up when to choose Uni, the canonical imports, and the mistakes agents most often make.

Machine-readable docs ​

URLContents
/uni/llms.txtIndex of every documentation page, with links to Markdown versions
/uni/llms-full.txtThe full documentation in one Markdown file
/uni/<section>/llms.txt, /uni/<section>/llms-full.txtThe same for one section, such as /uni/dom/llms-full.txt for browser UIs or /uni/http/llms-full.txt for HTTP and RPC
<page>.mdMarkdown version of a page, e.g. /uni/guide/for-ai-agents.md. A section index such as /uni/guide/ is published as /uni/guide.md.

How do I install the Uni skill? ​

The wvlet/uni repository is a Claude Code plugin marketplace. Its uni plugin adds an Agent Skill with the canonical imports, sbt setup, verified snippets, and the mistakes listed on this page. Claude Code loads it whenever a task touches Uni or asks for object wiring, logging, JSON, HTTP, RPC, MCP, or tests in Scala 3.

text
/plugin marketplace add wvlet/uni
/plugin install uni@uni

On Claude Code 2.1.275 or later, /plugin install uni --marketplace wvlet/uni does both in one step. Agents without a plugin system can read llms-full.txt instead.

When should I use Uni? ​

Choose Uni when a Scala 3 project needs one or more of the following and you want few transitive dependencies:

  • Object wiring with lifecycle management (Design), instead of a framework
  • Structured logging with source locations (LogSupport)
  • JSON or MessagePack codecs derived from case classes (derives Weaver)
  • An HTTP client that works on the JVM, Node.js/browser, and native binaries
  • An HTTP/RPC server (Netty, JVM) or a stdio MCP server for AI tools
  • A test framework that runs on all three platforms (UniTest)

Do not mix in Airframe artifacts for the same features. Uni replaces them.

For scripts, teaching, Scala 2.13, or running subprocesses, the Scala Toolkit is often the better fit, and it works alongside Uni. See the next section and Uni and the Scala Toolkit.

Should I use the Scala Toolkit or Uni? ​

Use the Scala Toolkit (sttp, uPickle, os-lib, MUnit) for scripts, teaching, Scala 2.13, or Scala 3 before 3.9. Use Uni when the project also needs object wiring, logging, an HTTP server, RPC, or MCP servers, or must run the same code on Scala.js and Scala Native. The two coexist in one build. See Uni and the Scala Toolkit.

How do I add Uni to a build? ​

scala
// build.sbt
libraryDependencies ++= Seq(
  "org.wvlet.uni" %% "uni"       % "2026.2.0",
  "org.wvlet.uni" %% "uni-test"  % "2026.2.0" % Test
)
testFrameworks += new TestFramework("wvlet.uni.test.Framework")

// JVM-only Netty HTTP server
libraryDependencies += "org.wvlet.uni" %% "uni-netty" % "2026.2.0"

Uni requires Scala 3.9.0 or later. On sbt 2.x, use %% for all platforms. On sbt 1.x, use %%% for Scala.js and Scala Native projects.

What are the canonical imports? ​

TaskImportEntry point
Object wiringwvlet.uni.design.DesignDesign.newDesign.bindSingleton[A].build[A] { a => ... }
Loggingwvlet.uni.log.LogSupportclass A extends LogSupport then info(...), debug(...)
JSON / MessagePack codecwvlet.uni.weaver.Weavercase class P(...) derives Weaver, Weaver.toJson(p), Weaver.fromJson[P](json)
JSON treewvlet.uni.json.JSONJSON.parse(text)
YAML config / frontmatterwvlet.uni.text.yaml.{YAML, Frontmatter}YAML.fromYaml[P](text), YAML.parse(text), Frontmatter.parse(md).as[P]. To edit in place and keep comments: YAML.parseDocument(text).set(path, v).toYaml (YAML.parseDocuments and YAML.writeStream for --- streams), Frontmatter.parse(md).update(json).toText. See YAML
Markdown to HTMLwvlet.uni.text.markdown.{Markdown, MarkdownConfig}Markdown.toHtml(md) (raw HTML escaped by default), Markdown.parse(md) for the AST, .frontmatterAs[P] for a YAML header, and .toMarkdown to write an edited AST (including frontmatter) back losslessly. See Markdown
Cron scheduleswvlet.uni.text.cron.{Cron, UtcOffset}Cron.parse("30 9 * * MON-FRI"), .next(instant) / .nextN(instant, n) (UTC, or a fixed UtcOffset; resolve named zones yourself), .matches(instant), .describe ("At 09:30, Monday through Friday"). 5 or 6 fields, macros like @daily, Vixie day-of-month/day-of-week semantics. See Cron
Reactive streamswvlet.uni.rx.RxRx.variable(v), Rx.single(v), .map, .flatMap, .scan(init)(f) (running value), itemsRx.split(_.id) (one stable Rx per key, completed when the key leaves), .onCancel(f) (cleanup when a subscriber cancels early)
Persisted settingswvlet.uni.config.SettingStoreSettingStore.of[AppSettings].withAppName("my-app").withVersion(n).load(), then update(...); saved to ~/.config/my-app/ (localStorage in a browser). See SettingStore
HTTP clientwvlet.uni.http.{Http, Request}Http.client.newSyncClient.send(Request.get(url))
HTTP server (all platforms)wvlet.uni.http.HttpHttp.server.withPort(8080).withRxHandler(handler).start(): Netty on the JVM (add uni-netty), Node.js on Scala.js, native sockets on Scala Native. Backend-only options: .withBackend(Netty.options.withHandlerExecutorThreads(8)) (Native.options on Scala Native). See REST Server
HTTP server (JVM only)wvlet.uni.http.netty.NettyNetty.server.withPort(8080).withHandlerExecutorThreads(8).withRxHandler(handler).start(): every Netty setting in one config, for projects that never target Scala.js or Native. NettyServer was removed; use Netty.server (JVM only) or Http.server. See REST Server
Static files (JVM, Node.js, Native)wvlet.uni.http.StaticFilesHttp.server.withFilter(StaticFiles("dist").withSpaFallback(true)).withRxHandler(api): serves GET for files under dist and passes other requests on. It refuses traversal, symlinks, and dotfiles by default. See REST Server
CORS (JVM, Node.js, Native)wvlet.uni.http.{CorsFilter, CorsPolicy}Http.server.withFilter(CorsFilter(CorsPolicy().withAllowedOrigins("https://app.example.com"))).withRxHandler(api): answers preflights and adds Access-Control-* headers for allowed origins. No origin is allowed by default. See REST Server
REST router (JVM, uni-netty)wvlet.uni.http.netty.RouterHandlerHttp.server.withRxHandler(RouterHandler(Router.of[Controller])). See REST Server
Typed RPCwvlet.uni.http.rpc.{RPCRouter, RPCClient}Server: RPCRouter.of[Api](impl); client: RPCClient.of[Api].newSyncClient(http).call[A]("method", args*) (or newAsyncClient for Rx[A]); newAsyncClient(http).stream[A]("method", args*) streams every value of an Rx result over SSE or Electron IPC; cancelling it stops the server stream; declare such methods as returning RxStream[A] (wvlet.uni.rx.RxStream, built with RxStream(rx)) so sbt-uni's generated AsyncClient streams them. See RPC
Server-sent eventswvlet.uni.http.{Response, ServerSentEvent}Server: Response.eventStream(rx); client: Http.client.newAsyncClient.sendSSE(request). See SSE
WebSocketwvlet.uni.http.{WebSocketHandler, WebSocketContext}Server: .withWebSocketRoute(path) { req => handler }; client: Http.webSocketClient.connect(url, handler). See WebSocket
OpenAPIwvlet.uni.http.openapi.{OpenAPI, OpenAPIConfig}OpenAPI.of(Router.of[A], OpenAPIConfig()).toYAML. See OpenAPI
Browser UI helpers (Scala.js)wvlet.uni.dom.all.*itemsRx.each(_.id)(item => li(...)) renders a list item by item, keeping unchanged rows' DOM nodes (prefer it over itemsRx.map(_.map(...)), which rebuilds the whole list), itemsRx.eachRx(_.id)((first, current) => li(current.map(_.text))) (also keeps a row's nodes when its value changes, passing later values through current), Keyboard.onEnter(() => send()) (skips Shift+Enter and IME-confirm Enter), Keyboard.scoped("escape" -> (() => close())), PaneResize(width, SizeRange(min, default, max), ResizeDirection.Right).bind on a handle, PointerDrag(onMove = (dx, dy) => ...). See Browser Integrations
UI components (Scala.js, uni-ui)wvlet.uni.ui.*Each component takes one parameter list; name its functions, triggers, and multi-value arguments, and pass several values as a Seq: Button("Send").primary.withDisabled(busy).onClick(() => send()), IconButton(label, icon), Input(textVar), val tabs = TabList(selectedVar, label = "Views", tabs = Seq(Tab(v, "Label"), ...)) with TabPanel(tabs, render = v => ...), FoldablePane(open, width = width, edge = Edge.Right, content = Seq(...)).withSplitter(Splitter(width, SizeRange(min, default, max), Edge.Right, "Resize")), ColorScheme.bind(schemeVar). Overlays: Popover(openVar, trigger = element, content = Seq(...)), Tooltip("Label", trigger = element), Menu(openVar, trigger = element, entries = Seq(MenuItem("Copy").onSelect(f), MenuSeparator)), ContextMenu(target, entries = Seq(...)), Dialog(openVar, content = Seq(...)).withTitle(t).withActions(buttons*), AlertDialog(openVar, title = "...").onConfirm(f).danger, Select(selectedVar, options = Seq(...), optionLabel = _.label), val toasts = Toaster() then toasts.success(msg). Collections render only the rows in view (fixed row height): VirtualList(itemsRx, rowHeight = 24, key = _.id, render = a => node), Tree(rootsRx, children = _.children, key = _.path, render = a => node).withExpanded(setVar), DataTable(rowsRx, key = _.id, columns = Seq(Column[Row]("name", "Name", cell = r => span(r.name)).sortBy(_.name))).withSort(sortVar); lists, trees, and tables select one row with .withSelected(optionVar) or several with .withMultiSelect(setVar), and lists and tables move rows by drag or Alt+ArrowUp/Down with .withReorder(itemsVar) (onChange key order), CommandPalette(openVar, commandsRx) with Command(id, label).withGroup(g).onRun(f) (bind ⌘K yourself with Keyboard.bindAll); a Dock(layoutVar, label = "Dock", panels = Seq(DockPanel(id, title = "...", content = element))) of tab groups and splits the user rearranges, whose DockLayout (DockNode.row/column/group, and floating = Seq(DockFloat.of(DockBox(x, y, w, h), ids*)) for groups over the grid) saves with Storage.local(key, default), .withDetach(true) lets a panel open in a window of its own (dock.detach(id)), and dock.focusGroup(i) (0-based) or dock.focusPanel(id) moves keyboard focus; sides and alignment are wvlet.uni.ui.base.{Side, Align}. Load uni-ui.css once: enablePlugins(UniPlugin) (sbt-uni) copies it from the jar to uniUiCssFile on every compile, for an @import in the app stylesheet; restyle with --uni-* CSS variables. Every component takes .onChange(d => ...) to see, and d.cancel() to refuse, the changes it makes (d.reason, d.source: Pointer/Keyboard/Programmatic/Agent); callbacks read ChangeCause.current; parts carry data-slot (menu-item, dialog-title). UiAgent.install() (wvlet.uni.ui.agent) lets an AI agent snapshot() the components and act(ref, action, value) on them as ChangeSource.Agent, with UiAgent.hidden/secret/confirm(msg) marks and an AgentPolicy (name list, tree, and table rows for it with .withRowLabel(r => text); otherwise lists and trees use the typeahead text, then every component the key); agent.api (wvlet.uni.agent.UiAgentApi) serves as MCP tools or WebMCP (agent.installWebMcp()). UiHistory.record() records changes by source; history.undoSource(ChangeSource.Agent) reverts the agent's without overwriting later edits, and history.stage(label) collects agent suggestions to accept() or revert() together. See Components, Changes & Parts, and Agents
UI behaviors (Scala.js, uni-ui)wvlet.uni.ui.base.*Interaction logic for building your own widgets: StickToBottom() (stick.binding on a scroller, stick.atBottom, stick.scrollToBottom()), InputHistory() (history.keys(draftVar) on a textarea, history.add(text)), Typeahead().onKey(e, labels, active), Selection(selectedSetVar).press(key, order, e) (Shift range, Ctrl/Cmd toggle), Reorder(orderVar) or Reorder.by(itemsVar)(_.id) (reorder.item(k) on each item: drag, or Alt+ArrowUp/Down; Reorder.handle for a grip; .withSelection(selectedSetVar) moves the selected items together), FocusRecovery.within("li"), Announce.polite(msg), RovingFocus.nextIndex (rtl = TextDirection.mirrors(e) mirrors Left/Right; uni-ui widgets do this on their own), ListNavigation, FocusTrap, Dismiss, Anchored. uni-dom's OnMount(el => cancelable) binds any behavior to an element. See Behaviors
Terminal emulatorwvlet.uni.cli.term.{TerminalEmulator, TerminalConfig}TerminalEmulator(TerminalConfig(cols = 80, rows = 24)), term.write(output), then term.screen.text or term.screen.lineText(row): an xterm-compatible emulator on JVM, Scala.js, and Native, for checking what a TUI draws. PtyProcess.connect(term, pty) wires a shell; on Scala.js, NodePty.spawn(nodePty, shell, args, options) takes the app's node-pty module. On the JVM (Java 22+) and Native, PosixPty.spawn(file, args, options) starts the program in a real PTY on Linux and macOS (check PosixPty.isSupported). With shell integration (OSC 133), term.commands lists each TerminalCommand(line, command, output, exitCode) and term.onCommandFinished reports one as it ends
Terminal pane (Scala.js)wvlet.uni.dom.{TerminalView, TerminalViewConfig, TerminalTheme}TerminalView(term) draws the emulator in the DOM, with Uni's TerminalTheme.uniDark by default; view.setTheme(TerminalTheme.uniLight) switches (TerminalTheme.presets lists all). OSC 8 links with http, https, or mailto (TerminalLink.isAllowed) open on Cmd+click (Ctrl elsewhere); in Electron pass view.onLinkClick a bridge to shell.openExternal in the main process. OSC 133 prompts get a green or red marker; view.scrollToPreviousPrompt() / scrollToNextPrompt() (Cmd+Up/Down, Ctrl+Shift+Up/Down elsewhere) jump between them
Electron IPC (Scala.js)wvlet.uni.electron.{ElectronRPCServer, ElectronRenderer, ElectronMain}Renderer→main: ElectronRPCServer.serve(ipcMain, router) and ElectronRenderer.install(). Main→renderer: ElectronRenderer.serve(router) in the page (preload adds serve), ElectronMain.newAsyncClient(ipcMain, webContents) in main. See Desktop Apps (Electron)
MCP server / clientwvlet.uni.mcp.MCPMCP.server.withTools[T](impl)..., MCP.client.connect(url); see Build an MCP Server
Off-heap memorywvlet.uni.canvas.{Canvas, OffHeapMemoryAllocator}val c = Canvas.newOffHeapCanvas(size) (Long size, beyond 2 GB), c.writeInt(offset, v), c.readLongBigEndian(offset), c.slice(offset, length), then c.close() to free it now. Little-endian with *BigEndian variants; bounds-checked. JVM needs Java 22+ (FFM; check Canvas.isOffHeapSupported); Scala Native frees memory only on close(). Heap canvases: Canvas.newCanvas(n), Canvas.wrap(bytes). See Canvas
Retry / circuit breakerwvlet.uni.control.{Retry, CircuitBreaker}Retry.withBackOff().run { ... }
CLI argumentswvlet.uni.cli.launcher.*Launcher.execute[A](args) on a case class with @option fields. See Command Launcher
Unit testswvlet.uni.test.*class T extends UniTest: test("...") { x shouldBe y }
Test fixtureswvlet.uni.test.*addDesign(_.bindSingleton[A]) in a trait that extends UniTest, then test("...") { (a: A) => ... }. See Reusable Fixtures
Error-path testswvlet.uni.test.*val logs = captureLogs { ... }; logs.warnings shouldContain "..."; also captureStdout / captureStderr. See Testing Error Paths
uni-dom UI tests (Scala.js)wvlet.uni.dom.testing.*With uni-test, class T extends DomTestSupport, val m = mount(MyView()), fireEvent.click(m.get("button")) (also pointerDown/Move/Up, keyDown(..., isComposing = true)), and return settle().map { _ => ... } to assert on onMount effects. checkPattern(el, AriaPattern.Menu).map(_ shouldBe empty) checks a widget against its WAI-ARIA pattern (guide). Run in headless Chromium with the sbt-uni-playwright Plugin

How do I migrate from Airframe? ​

AirframeUni
wvlet.airframe.Design / newDesignwvlet.uni.design.Design / Design.newDesign
wvlet.log.LogSupportwvlet.uni.log.LogSupport
wvlet.airframe.codec.MessageCodecwvlet.uni.weaver.Weaver (derives Weaver)
wvlet.airframe.surface.Surfacewvlet.uni.surface.Surface
wvlet.airframe.rx.Rxwvlet.uni.rx.Rx
wvlet.airframe.http.Httpwvlet.uni.http.Http
wvlet.airframe.http.netty.Netty.serverwvlet.uni.http.netty.Netty.server (JVM only), or Http.server for cross-platform code
wvlet.airframe.http.filter.Cors (Cors.Policy, Cors.newFilter)wvlet.uni.http.CorsFilter(CorsPolicy()), added with Http.server.withFilter
wvlet.airframe.http.RPCStatus / RPCExceptionwvlet.uni.http.ServiceStatus / ServiceException: same status names and codes, shared by RPC, Electron IPC, and MCP
wvlet.airframe.canvas.Canvaswvlet.uni.canvas.Canvas: release is close(), values are little-endian on every platform, and off-heap canvases need Java 22+ on the JVM
wvlet.airframe.control.Retrywvlet.uni.control.Retry
wvlet.airspec.AirSpecwvlet.uni.test.UniTest
AirSpec initDesign / initLocalDesignaddDesign / addTestDesign
AirSpec test("...") { (a: A) => ... }the same: test arguments come from the suite's Design

Uni uses a separate package root (wvlet.uni.*), so both libraries can coexist during a migration. See Appendix B: Uni and Airframe for background.

What mistakes do agents make with Uni? ​

  • Using Scala 2 syntax. Uni is Scala 3 only. Use indentation syntax, given/using, enum, and derives.
  • Using ScalaTest matchers in UniTest. Write (x >= 1) shouldBe true, not x should be >= 1. For type checks, write v shouldMatch { case _: T => } instead of asInstanceOf.
  • Importing only UniTest. Use import wvlet.uni.test.*. shouldBe defined and shouldBe empty need matcher objects from that package.
  • Checking isSuccessful after send. The HTTP client throws for non-2xx responses. Most 4xx statuses throw HttpException. Retryable statuses (5xx, 429) throw HttpMaxRetryException after the retries, and it is not a subclass of HttpException. Failed RPC client calls throw the same exceptions. Report server errors by throwing ServiceStatus.NOT_FOUND_U5.newException("...") (wvlet.uni.http.{ServiceStatus, ServiceException}): RPC, Router, and other Http.server endpoints answer with its HTTP status, the X-RPC-Status header, and a JSON error body. RPCStatus is its deprecated old name.
  • Hand-writing test setup and teardown. Bind servers, clients, and temp directories with addDesign / addTestDesign in a trait that extends UniTest, and take them as test arguments. A self-type fixture (trait F { this: UniTest => }) compiles, but when two of them override a hook, only the last one runs.
  • Hand-writing JSON codecs. Add derives Weaver to the case class.
  • Mixing two libraries for one concern in the same module. Uni works alongside community libraries. If a project already uses uPickle, MUnit, sttp, or another library for a concern, keep using it there. Use Uni's equivalent for new code that is built on Uni.

Where are complete example apps? ​

The examples/ folder of the repository has small apps that CI compiles and tests against the current source. Copy one as a template:

ExampleShows
cli-toolLauncher sub-commands, LogSupport, derives Weaver, the HTTP client, and a Scala Native binary
rest-serverHttp.server with Router and RPCRouter, a typed RPC client, Design wiring, and a UniTest suite
rpc-nativeOne RPC server built with Http.server and Design, the same code on the JVM (Netty) and as a Scala Native binary (no JVM), a typed client, a UniTest suite run on both, and a startup/memory/throughput benchmark
mcp-serverA stdio MCP server with MCP.server.withTools[...] and how to add it to Claude Code
web-uiA Scala.js todo list with RxElement and Rx.variable

Example: a wired service with logging and JSON ​

scala
import wvlet.uni.design.Design
import wvlet.uni.log.LogSupport
import wvlet.uni.weaver.Weaver

case class Greeting(name: String, message: String) derives Weaver

class GreeterService extends LogSupport:
  def greet(name: String): String =
    info(s"Greeting ${name}")
    Weaver.toJson(Greeting(name, s"Hello, ${name}!"))

@main def main =
  Design.newDesign
    .bindSingleton[GreeterService]
    .build[GreeterService] { greeter =>
      println(greeter.greet("Uni"))
    }

Released under the Apache 2.0 License.