Initial configuration

uuldana-cli works without any configuration. It finds the agents installed on your machine by itself and starts them. Without a config.json, or with one that has no permissions entry, the ceiling is ask_for_risky, unrestricted, allowed: the agents ask before risky actions as they normally do, and uuldana-cli adds no restriction of its own.

Create a config.json to choose the order, add a second account, or set a tighter ceiling. Agents you do not rank are tried after the ones you do, in the order of their ids, and none is preferred over another. You can also set the order from inside a session with /agent, which creates the file for you. This guide creates a minimal file; Configuring agents describes all available fields.

1. Choose a configuration location

Create the uuldana directory if it does not exist, then save your file at the location for your platform. Set UULDANA_CONFIG to use another file.

2. Save your agent list

Copy this example into config.json. Replace the provider entries with the agents you have installed and signed in to, in the order you want to use them:

{
  "version": 1,
  "permissions": {
    "approval": "ask_for_risky",
    "filesystem": "unrestricted",
    "network": "allowed"
  },
  "providers": [
    { "id": "claude" },
    { "id": "codex" }
  ]
}

The order of providers is the order uuldana-cli tries them. An id is the name of the agent’s program without its extension, as uuldana providers lists it. The example tries claude before codex because they appear in that order; you choose your own order. An entry that matches no agent found on the machine is left out, with a notice. Installed agents that are not listed follow after the listed ones, so an agent you install later is found without editing the file. Set "auto_detect": false to use only the listed agents.

With this ceiling, which is also the default, every agent that was learned can start, because each has at least its own default way of running, assumed to ask before acting. See Configuring agents.

3. Check agent availability

uuldana providers

Each agent found on the machine is listed as installed, with its version and path and what was learned about it; a provider described by a manifest that is not installed is listed as not installed. Check that at least one agent in your configuration is installed before starting a session.

This command checks agent availability. Starting uuldana reads your configuration: if a provider id is unknown, it exits with an explanation. If the file is missing, uuldana-cli starts with the agents it finds. If no agent is installed at all, it says so and exits with code 2.

Next: start a session

Open a terminal in the project you want to work on and follow First session.

Where data goes

Session journals and the cooldown table are stored in the data directory: UULDANA_DATA if set, otherwise %LOCALAPPDATA%\uuldana on Windows and $XDG_DATA_HOME/uuldana (or ~/.local/share/uuldana) elsewhere. Journals are in sessions/.