Uji is a terminal coding agent built around an unusually broad customization promise: users can replace modules at runtime, including the interface and core behavior. Its public repository describes a Rust-and-Lua project that starts small and adds functionality through plugins.
The key detail is where customization reaches. Changing a theme is familiar territory. Rewriting a view or replacing part of the agent’s behavior gives developers control over the working environment itself.
That makes Uji interesting as a coding-agent harness: the software around an AI model that manages interaction, tools and workflow. Its value will depend on how reliably those replaceable parts work together. The published documentation offers concrete configuration examples, but the available evidence is still primarily the project’s own description.
What Uji’s Swappable Modules Actually Mean
The README makes its central promise explicit:
“Swap any of them at runtime, even the core”
The repository also says every view is written in Lua and can be rewritten. The project website places themes, plugins and core customization in the same Lua-based configuration story.
These are different levels of control. A theme changes presentation. A custom view can change which information appears and how it is arranged. Replacing agent behavior reaches deeper, into how the environment responds to commands or coordinates a workflow.
For someone who wants a specific terminal layout, the practical implication is straightforward: the interface is part of the customization surface. You would not necessarily need to maintain an entirely separate application simply to change a view.
The runtime claim needs a careful boundary, though. The opened documentation does not explain the replacement procedure, how active tasks behave during a swap, or whether existing session state survives every kind of change. It supports the project’s claim of runtime modularity, not a guarantee of interruption-free replacement.
My view is that interface ownership is Uji’s clearest differentiator. Plenty of configuration options can still leave users working inside an interface they cannot substantially change. Uji’s documented design gives that interface to the same Lua customization layer as the rest of the agent.
How to Install Uji
Uji documents shell-script, Homebrew and Nix installation paths on its website. Choose one of these methods.
The shell installer downloads a script from the repository and passes it directly to sh:
curl -fsSL https://raw.githubusercontent.com/uji-labs/uji/main/install.sh | sh
That is convenient, but it executes downloaded code immediately. Reviewing an installer before running it is a sensible precaution, especially on a machine holding development credentials.
For Homebrew:
brew install uji-labs/uji/uji
For Nix:
nix profile add github:uji-labs/uji
These are the project’s published commands, not commands tested for this article. The opened pages do not provide enough detail to make broad claims about operating-system support or installation behavior on a particular machine.
The documentation introduction points users to getting-started instructions for installation and sign-in. Installing the application is therefore only part of setup; follow those instructions for authentication.
Uji’s Lua configuration lives at:
~/.config/uji/init.lua
That file is the starting point for loading defaults, adding plugins and changing behavior.
Lua Configuration Controls More Than Appearance
The documentation’s example configuration begins by loading built-in defaults and adding a plugin repository:
require("uji.builtin.defaults")
uji.pack.add({ "uji-labs/uji-plugins" })
require("statusline").setup({})
require("planmode").setup({})
This excerpt shows the beginning of the documented configuration, not a complete provider or authentication setup. It loads the defaults, registers the project’s plugin collection, and calls setup functions for the statusline and planmode modules.
The example is useful because it exposes the composition model. Defaults are loaded explicitly; extra modules are brought into the environment through Lua. Users can see which components their configuration asks to load.
The same documentation demonstrates several other controls:
- Plugin loading:
uji.pack.addadds a plugin source. - Tool policy:
uji.tool.policydefines rules for tools. The example includes an allow list forrun_command, containinggit statusand acargo test*pattern. - Keybindings:
uji.keymap.addmaps a key combination in normal mode to the models command. - Custom commands:
uji.command.addregisters a command whose Lua function submits a request throughuji.session.submit.
These examples show that Uji’s configuration reaches into workflow and tool permissions. The custom command in the documentation submits a request to summarize commits since yesterday, illustrating how a recurring prompt can become a named action.
The tool-policy example deserves particular attention. A command pattern is a policy setting, not evidence of a complete security boundary. The introduction does not explain matching semantics, precedence between rules or how commands outside the allow list are handled. Those details matter before using such rules in a sensitive repository.
Lua also changes the maintenance burden. A configuration file can contain executable logic, so users gain flexibility while taking on responsibility for that logic and its dependencies. A short configuration can be easy to inspect. A growing collection of custom modules can become a small software project of its own.
A Tiny Core Has Benefits and Costs
Uji’s repository says it starts small and lets users add plugins as needed. That is a useful alternative to accepting a large default environment, particularly for developers who already know which features they want.
The performance language is less conclusive. The project calls Uji fast and lightweight, but the opened materials provide no startup-time, memory-use or task-performance measurements. Rust and Lua describe the implementation; they do not supply a benchmark. Treat the speed claim as the developer’s positioning until comparable measurements are available.
The maturity tradeoff is also important. The repository snapshot showed 44 stars and six forks. Those figures describe visible GitHub activity at that moment, not reliability or active usage. The available sources contain no independent testing or adoption evidence.
There is also insufficient source evidence here for a feature-by-feature comparison with established harnesses. A more useful comparison is between the responsibilities each architectural choice places on the user:
Frequently Asked Questions
3 questions
1Is Uji a New AI Model?
No. Uji is a terminal coding agent and configurable harness. Its documented features concern the interface, modules, tools and workflow around model use.
