ua
==

ua is a minimal agent harness, providing a command-line interface to a
large language model accessed through an Open Responses API, and allowing
it to access local tools including a shell.


Installation and configuration
------------------------------

A single Python 3.12+ script 'ua' is provided. Ensure the #! path is
correct for your system before copying it to a directory on your path.
The tool has no dependencies beyond the standard library. It is configured
through the environment.

Set API, KEY and MODEL to the endpoint, bearer key and model ID, e.g.

  export API=https://openrouter.ai/api/v1/responses
  export KEY=sk-or-v1-xxx
  export MODEL=anthropic/claude-opus-4.6

ua appends to an NDJSON conversation log in LOG, defaulting to 'ua.log'.
If LOG is an empty string, /dev/null is used and the log is not locked.

If set, REASONING overrides the default reasoning effort for the model.

The shell tool is built-in and passes commands from the model to SHELL
on stdin. Change SHELL to wrap commands before execution: to authorise
them, drop to a less privileged user, sandbox within more restrictive
namespaces, or even run them on a different host. For instance, set
SHELL to the examples/confirm wrapper to preview and confirm commands on
the terminal before running them with bash. If SHELL is empty or unset,
the shell tool is disabled.

A directory of additional self-describing tool executables can be given
in TOOLS. Each of these should read JSON input on stdin then produce JSON
output on stdout. If stdin is empty, they should instead print their JSON
tool schema.


User input
----------

'ua system' and 'ua user' add a new system or user message to the log.
If stdin is a terminal, ua will get the message text via a text editor;
otherwise, it will read it directly from stdin.

Example system messages explaining how the shell tool might be used are
provided in examples/system.


Agent loop
----------

'ua agent' repeatedly calls the model, streaming assistant messages to
stdout and executing any tool calls. All generated items are appended
to the log. The loop terminates once the model has returned a finished
response to the user.


Other actions
-------------

'ua abort' aborts any pending function calls in the log. This is useful
if you want to interrupt the model to provide updated instructions,
and when prompting the model to fork copies of its own state.

'ua recap' will print the message history from the log to stdout.


Copying
-------

This software was written by Chris Webb <chris@arachsys.com> and is
distributed as Free Software under the terms of the MIT license in COPYING.