Early version
uuldana-cli is an early version. The newest release on npm is v0.1.0, and it uses provider contract 0.2, which is frozen. The contract number identifies the interface between adapters and the core. It is not a release version.
What is implemented
| Area | Status |
|---|---|
| Core contracts | Contract 0.2 frozen: session, capability, permission, lifecycle, and adapter interfaces. |
| Provider SDK | Adapter-facing re-exports and a complete example adapter. |
| Command line | uuldana, uuldana resume, uuldana providers, --version, --help, and --bypass-permissions. |
| Native terminal relay | The agent’s own UI in a pseudo terminal (ConPTY on Windows), with resize and graceful stop. On Windows, Shift+Enter and Ctrl+Enter start a new line, Ctrl+Backspace deletes a word, and pasted text, including several lines, arrives as one paste. A picture on the clipboard is offered to an agent that takes one. |
| Frame | Alternate screen, a header that stays at the top, a permanent bypass warning, and scrolling with the wheel. The wheel and the arrow keys keep working after the work moves to another agent. |
| Finding agents | No agent is known by name. Console programs on the search path are asked for --help once, and a program whose help describes a coding agent is learned from it: how to start with a prompt, resume, and set permissions. |
| Configuration | config.json: agent order, accounts, permission ceiling, cooldowns, failover and auto-detect switches. Installed agents are found even when not listed, and a missing ceiling defaults to ask_for_risky, unrestricted, allowed. |
| Choosing the order | /agent inside a session: pick the order, write it to config.json, and move the work to the agent you chose. |
| Sessions | Append-only journal, crash-tolerant resume, and the text of an agent’s screen kept when its run ends. |
| Failover | One general usage-limit reader for every native terminal agent, graceful stop, cooldowns, and a visible-only handoff. It moves the work only when an allowance is gone, never on a warning such as 85% used. |
| Release material | Packaging scripts, checksums, a workflow that builds archives, and a workflow that publishes the Windows x64 package to npm. |
Tried against real programs
On the test machine, four coding agents are installed. uuldana-cli found all four by itself, with no configuration, and learned how to start, resume, and set permissions for each from its own --help. For each of the four:
- it opened through uuldana-cli and was left with Ctrl+C, and the run ended cleanly;
- it was stopped the way a failover stops it, and shut down gracefully (three runs in a row);
--bypass-permissionsreached the real process as the agent’s own flags, and for the one agent that lists a mode that asks about everything and writes nothing, a strict ceiling selected that mode and not the bypass flags.
On 2026-10-31, in a real Windows Terminal window, a limit line printed in front of a real Claude Code session moved the work to Codex, and one printed in front of Codex moved it back to Claude Code. A warning of 85% used did not move anything. In the same windows the wheel, the arrow keys, and Shift+Enter worked before and after each move, and the wheel scrolled Codex’s own transcript. The limit lines were printed text, not an exhausted account.
None of the four was sent a prompt. One of them, earlier in development and before the per-agent wording was removed, moved a session to another agent when it printed a real usage-limit message. That exact message is now a test input of the general reader, not a new live exhaustion.
Three other agents that uuldana-cli was written for earlier are not installed on the test machine, and have not been tried at all.
Not run yet
- A failover at a genuinely exhausted quota since the per-agent wording was removed. The general reader is covered by real usage-limit messages as test inputs and by real child processes standing in for agents.
- The limit message of agents other than the one seen from a real account. The general reader has only seen example sentences for them.
- Scrolling an agent’s own transcript with the wheel, for agents that ask for the mouse, beyond the one that was tried (Codex).
- A real agent run through uuldana-cli on Linux and macOS, and anything on ARM64 Windows. The test suite does run in hosted CI on Ubuntu, macOS, and Windows and passes there. The search of the path for agents is skipped on those runners, because a build server has no agents.
Tests
On 2026-10-31, one run of the workspace tests on Windows passed 437 tests with the GNU toolchain and none failed. With the MSVC toolchain 436 passed and 1 failed: the test that opens each installed agent and leaves it with Ctrl+C. The Codex version installed at that time (0.166) exits with code 1 after two Ctrl+C when it is started on its own, outside uuldana-cli, so that test fails on the agent’s own behavior and is not changed. See Testing.
Usage-limit wording was taken from public reports and from one real message, not from provider documentation, so a provider can change it. See Known limitations.