Available APIs

Every function lives under the global uji table. A function that finishes later takes a callback as its last argument, which receives the result, or nil and an error message. Called without the callback from a slash command, a key binding or a timer, it waits and returns the result instead. A function that starts background work returns a function that stops it. Wrong arguments raise an error at the call.

Tools

Name	Does
`uji.tool.add(name, spec)`	Registers a tool the model can call, or replaces the tool with the same name.
`uji.tool.remove(name)`	Removes a tool and returns `true` if it existed.
`uji.tool.list()`	Returns the names of every registered tool.
`uji.tool.disable(names)`	Turns tools off. The model still sees them, and uji denies any call to them.
`uji.tool.enable(names)`	Turns tools back on after `uji.tool.disable`.
`uji.tool.policy(rules)`	Sets which tool calls run without asking, which ask first, and which uji refuses.
`uji.tool.confine(enabled)`	With `true`, limits `read_file`, `edit_file` and `write_file` to the working directory and the roots from `uji.tool.roots`.
`uji.tool.roots(paths)`	Replaces the directories the file tools may reach besides the working directory, and returns the list.

Commands

Name	Does
`uji.command.add(name, spec)`	Registers `/name`, or replaces the Lua command with the same name.
`uji.command.remove(name)`	Removes a Lua command and returns `true` if it existed.
`uji.command.list()`	Returns the names of the Lua commands in alphabetical order.

Keys

Name	Does
`uji.keymap.add(mode, key, binding)`	Binds a key in one mode, replacing what the key did there.
`uji.keymap.remove(mode, key)`	Unbinds a key in one mode, including a default binding.
`uji.keymap.reset()`	Restores the default bindings.
`uji.keymap.list()`	Returns one row per binding, with `mode`, `key`, and one of `action`, `command` or `unbound = true`.

Actions

Name	Does
`uji.action.add(name, handler)`	Registers an action.
`uji.action.remove(name)`	Removes an action you added and returns `true` if it existed.
`uji.action.list()`	Returns the names of every action, built-in and added, in alphabetical order.

Windows, pickers and appearance

Name	Does
`uji.ui.open_win(opts)`	Opens a window and returns its id.
`uji.ui.set_lines(id, lines)`	Replaces a window’s content.
`uji.ui.clear(id)`	Empties a window.
`uji.ui.set_size(id, size)`	Changes a window’s size to rows or columns, `"fill"` or `"auto"`.
`uji.ui.set_title(id, title)`	Sets the title in a window’s border, or removes it when `title` is `nil`.
`uji.ui.close_win(id)`	Closes a window and returns `true` if it was open.
`uji.ui.select(opts, on_done)`	Shows a list to choose from.
`uji.ui.pick(opts, on_done)`	Shows a fuzzy finder with a preview pane.
`uji.ui.prompt(opts, on_done)`	Asks for a line of text.
`uji.ui.exec(cmd)`	Hides uji, runs a program in the terminal, and comes back when it exits.
`uji.ui.configure(opts)`	Sets colours and screen behaviour.

Name	Does
`uji.status.provider()`	Returns the name of the current provider, or `nil` before one is set.
`uji.status.model()`	Returns the current model id, or `nil` before one is set.
`uji.status.effort()`	Returns the reasoning effort, such as `"medium"`, or `nil` when reasoning is off.
`uji.status.context()`	Returns a table with `used`, the estimated tokens in the conversation, and `window`, the model’s context size when uji knows it.
`uji.status.queue()`	Returns the messages you typed while the model worked, which uji has not sent yet.
`uji.status.state()`	Returns `"working"` while a turn runs and `"idle"` otherwise.
`uji.status.elapsed()`	Returns the seconds since the current turn started, or `nil` when idle.
`uji.status.loader_frame()`	Returns the loader frame to draw now, from `waiting.loader.frames` in `uji.ui.configure`.
`uji.status.add(name, render, opts)`	Registers a footer segment.
`uji.status.remove(name)`	Removes a segment and returns `true` if it existed.
`uji.status.list()`	Returns the segment names in priority order.
`uji.status.render()`	Calls every segment in priority order and returns the values that are not `nil`.

Model context

Name	Does
`uji.context.add(name, provide, opts)`	Registers a function that uji calls at the start of every turn.
`uji.context.remove(name)`	Removes a context function and returns `true` if it existed.
`uji.context.list()`	Returns the names of the context functions, in the order uji calls them.
`uji.context.configure(opts)`	Sets how long the provider caches the conversation, and when uji compacts.

Events

Name	Does
`uji.on(event, handler, opts)`	Adds a handler for an event and returns the handler’s name.
`uji.off(event, name)`	Removes the handler with that name and returns `true` if it existed.
`uji.emit(event, payload)`	Runs the handlers of any event with the payload you give.

Session

Name	Does
`uji.session.info()`	Returns a table with the session’s `id`, `title` and `directory`.
`uji.session.messages()`	Returns the transcript as a list of tables with `type` and `text`.
`uji.session.usage()`	Returns the tokens spent in this session.
`uji.session.set_title(title)`	Renames the session, saves the name, and fires `session_titled`.
`uji.session.submit(text)`	Sends a message as if you typed it.
`uji.session.interrupt()`	Stops the current turn, or the running `!` command.

Input line

Name	Does
`uji.input.get()`	Returns the text on the input line.
`uji.input.set(text)`	Replaces the text on the input line.
`uji.input.append(text)`	Adds text to the end of the input line.
`uji.input.clear()`	Empties the input line.
`uji.input.attach(path)`	Attaches an image file to the message on the input line.
`uji.input.capture(handler)`	Sends every key press to `handler` instead of the normal bindings, until `uji.input.release` runs.
`uji.input.release()`	Returns the keyboard to the normal bindings.

Providers

Name	Does
`uji.provider.add(spec)`	Adds a provider, or merges `spec` into the provider with the same `id`.
`uji.provider.remove(id)`	Removes a provider and returns `true` if it existed.
`uji.provider.list()`	Returns one table per provider with `id`, `name`, `wire`, `base_url` and `models`.
`uji.auth.configure(opts)`	Chooses between `auth.toml` and the system keychain for API keys and sign-ins.

Request formats

Name	Does
`uji.wire.add(name, spec)`	Registers a wire, or replaces the wire with the same name.
`uji.wire.remove(name)`	Removes a wire and returns `true` if it existed.
`uji.wire.list()`	Returns the names of the registered wires.

Processes

Name	Does
`uji.job.start(opts)`	Starts a process and returns a job table.

HTTP

Name	Does
`uji.http.request(opts, on_done)`	Sends an HTTP request and returns a function that cancels it.

Files

Name	Does
`uji.fs.read(path, on_done)`	Reads a whole file.
`uji.fs.lines(path, opts, on_done)`	Reads a range of lines from a text file.
`uji.fs.write(path, content, on_done)`	Writes a file, creating missing directories.

JSON

Name	Does
`uji.json.encode(value)`	Turns a Lua value into a JSON string.
`uji.json.decode(text, opts)`	Turns a JSON string into a Lua value.
`uji.json.array(table)`	Marks a table as a JSON array, so it encodes as `[]` even when empty.

Packs

Name	Does
`uji.pack.add(specs)`	Installs and loads packs.
`uji.pack.list()`	Returns every directory uji searches for modules and `plugin/` files, starting with your config directory.
`uji.pack.update()`	Pulls every installed git pack and records the new commits in the lock file.

Timers and notices

Name	Does
`uji.schedule(callback)`	Runs `callback` once the code that called it has finished.
`uji.defer(seconds, callback)`	Runs `callback` after a delay and returns a function that cancels it.
`uji.notify(message)`	Shows a notice in the transcript.

Runtime

Name	Does
`uji.task.spawn(fn, ...)`	Starts a function as a task that runs alongside the rest of uji.
`uji.sleep(seconds)`	Pauses the current task.
`uji.task.race(fn, ...)`	Runs functions at once and returns the first to finish.
`uji.task.timeout(seconds, fn)`	Runs a function with a time limit.
`uji.promise()`	Returns a promise that tasks can wait on.
`uji.net.request(opts)`	Sends an HTTP request and returns the answer.
`uji.net.open(opts)`	Sends an HTTP request and streams the answer.
`uji.net.listen(port)`	Accepts connections on a local port.
`uji.proc.spawn(argv, opts)`	Starts a process.
`uji.db.open(path)`	Opens a SQLite database.
`uji.os`	Reads the platform, the environment and the clock.
`uji.modules(namespace)`	Lists the modules inside a namespace.
`uji.keychain`	Reads and writes secrets in the system keychain.
`uji.clipboard`	Reads and writes the system clipboard, and reads images from it.
`uji.regex(pattern)`	Compiles a regular expression.
`uji.glob(pattern, opts)`	Compiles a glob.
`uji.fuzzy(query, items)`	Ranks strings against a query.
`uji.markdown(source)`	Parses Markdown into events.
`uji.width(text)`	Measures text in terminal columns.
`uji.lossy(data)`	Turns bytes into valid UTF-8.
`uji.base64`	Encodes and decodes base64.
`uji.toml`	Reads and writes TOML.
`uji.sha256(data)`	Hashes data.
`uji.random(count)`	Returns random bytes.
`uji.image.fit(data, edge, bytes)`	Checks an image and fits it to a size and a byte limit.

Keyboard shortcuts

uji