uxon 3.4.0

Multi-user wrapper for managing terminal AI coding agent sessions (claude, codex, cursor)

uxon

Session manager for development teams using terminal AI coding agents (Claude Code, Codex, Cursor CLI) on one or more Linux servers. Team visibility via OS accounts, cross-host visibility via SSH, supervision via sudoers.

When to use uxon

Use uxon when terminal AI coding agents are a runtime someone else may need to see, attach to, or stop. Four shapes of deployment, one tool:

• One developer, one host. Persistent TUI over tmux; agents optionally sandboxed in a low-priv <user>_agent account so a yolo run can't trash your $HOME.
• One developer, several hosts. Aggregate everything into one TUI with a HOST column; locals first, then peers grouped by host.
• A team sharing one host. Each developer runs as their paired <user>_agent. The lead's TUI sees everyone via sudo. Cross-user supervision without impersonation — the lead never becomes the developer.
• A team across several hosts. Same supervision property per host; per-peer authority (each host's sudoers is the authority on that host); cross-host audit correlation via UUID correlation_id joining caller-side and peer-side events.

Aggregation is client-side: the lead's TUI fans out over SSH. No daemon, no database, no central server to deploy. Each host stays independently configured and independently authorised.

Install

Requires Python 3.11+, tmux, and Linux.

# Team / shared host (recommended): one root-owned binary in
# /usr/local/bin/uxon. Operator owns the version and the install
# path; launch users can append audit events but cannot edit
# the binary or the trail.
sudo pipx install --global uxon

# Solo / single-owner: each OS user manages their own copy.
uv tool install uxon              # or:  pipx install uxon

uxon                              # launch the TUI; it self-diagnoses

For the bundled installer, PEP 668 caveat, and unreleased-from- main builds, see docs/start/install.md.

Documentation

The site at docs/ is organised two ways. Pick the entry that matches what you have in mind.

By scenario:

• Solo on a single host
• Solo on multiple hosts
• Team on a single host
• Team on multiple hosts

By task (Diátaxis layout):

• docs/start/ — tutorials (install, bootstrap a host, add a peer).
• docs/guides/ — how-to recipes (operate, harden, customise, debug).
• docs/reference/ — every command, every flag, every config key, every audit event.
• docs/explain/ — the model (isolation, supervision, multi-host, audit channel).

Top-level pointers:

• docs/index.md — full table of contents.
• docs/clients.md — laptop side (Eternal Terminal, SSH config, hardware keys).
• docs/privacy.md — what uxon records about each developer; for sharing with your team.
• docs/migrations.md — version-bump operator notes.
• SECURITY.md — disclosure policy + threat model summary.
• CHANGELOG.md — version history.
• CONTRIBUTING.md — local checks, branch policy, release process.

Quick TUI tour

uxon (no args, on a TTY) opens a full-screen picker:

• New session in current folder — start the default agent in $PWD.
• Create new project — prompt for a name, create <new_project_root>/<name>, optionally create a GitHub repo, launch the agent.
• Open existing project — pick a directory under new_project_root and launch.

Below that: a unified session dashboard mounting your own sessions, other-user sessions visible via sudo (when the superuser block is active), and one row per session on each configured [[remote_hosts]] peer. Two view modes — flat (default; single ranked list) and by_host (per-host tabs and a status bar); toggle with v. ←/→ on the dashboard cycles between hosts (host tabs in by_host, (host, own/other) transitions in flat). A search bar at the top filters across all rows; / refocuses it. Per-row data: agent, working dir, live CPU / RAM, attached glyph (●/○), creation time, last activity time. Enter attaches; d kills with confirmation.

Every launch asks whether to start in normal mode or with --dangerously-skip-permissions ("yolo") — the TUI does not start yolo without that explicit choice.

Full keybinding list: docs/reference/keybindings.md.

Supported agents

Agent id	Binary	--auto mode	--dsp (yolo)	Install
claude	claude	--permission-mode auto	--dangerously-skip-permissions	Anthropic docs
codex	codex	--full-auto	--dangerously-bypass-approvals-and-sandbox	npm i -g @openai/codex
cursor	cursor-agent	(not supported)	--yolo	curl https://cursor.com/install -fsSL | bash

Enable agents in config/config.toml:

[agents]
enabled = ["claude", "codex"]
default = "claude"

-w <branch> (worktree) is currently claude-only. --auto is unavailable for cursor.

uxon doctor probes each enabled agent and prints its path, version, and status. The TUI auto-detects newly-installed agents and offers a one-keypress enable.

Versioning

uxon follows SemVer. uxon --version prints the version and short git commit (with -dirty when the checkout has uncommitted changes).

In a team·N fleet, all peers must run the same major version — see docs/guides/operate/roll-fleet-upgrade.md.

License

MIT © 2026 Vasily Zakharov.