config.lua

config.lua is an optional Lua file loaded at startup before the UI appears. Use it for programmatic configuration — conditional settings, loading plugins, and anything that benefits from real code instead of TOML.

Global config:

• Linux / macOS: ~/.config/jjui/config.lua
• Windows: %AppData%/jjui/config.lua

Repo-specific config: You can create a .jjui/config.lua file in the root of any jj repo and it will override anything that was set by your global config.lua.

Custom config: You can also set a custom config directory with the JJUI_CONFIG_DIR environment variable. jjui will then load config.lua from that directory, and it will replace the global and repo configs, rather than just override them.

---

setup(config)

Define a top-level setup(config) function and jjui will call it at startup with a config object for registering actions, adding bindings, and setting colors.

function setup(config)
  -- register actions and bindings here
end

The config object exposes config.action(...) and config.bind(...) for registering actions and bindings. For the full API, see Actions and Bindings.

---

Editor support

If your editor uses LuaLS, jjui can install generated type metadata for the Lua API:

jjui --install-lua-types

This writes types.lua to your jjui config directory and creates .luarc.json if it does not already exist. Existing .luarc.json files are left unchanged.

---

Runtime values

These fields are available on config inside setup and are read-only:

Value	Type	Description
config.repo	string	Absolute path of the current repository
config.terminal.dark_mode	bool	Whether the terminal reports dark mode
config.terminal.bg	string	Terminal background color (hex, if detectable)
config.terminal.fg	string	Terminal foreground color (hex, if detectable)

---

Sharing helpers with config.toml

config.lua and [[actions]].lua scripts in config.toml run in the same Lua VM. Any global function defined in config.lua is available to TOML action scripts:

-- config.lua
function current_diff()
  return jj("diff", "-r", context.change_id(), "--git")
end

config.toml

[[actions]]
name = "copy-diff"
lua = '''
copy_to_clipboard(current_diff())
'''

---

Modules

require(...) resolves modules from your config directory in addition to the standard Lua path. Place Lua files under ~/.config/jjui/ and load them with require("plugins.name").

local my_plugin = require("plugins.my_plugin")

function setup(config)
  my_plugin.setup(config)
end

For practical examples, see the Lua Cookbook. For the full runtime API (context, revisions, jj, flash, etc.), see Lua Scripting.