Universal CLI Agent System is a tool for managing and launching AI agents and teams with a modular, configuration-driven approach.

• Sandwich Merge: Multi-layer configuration (System → User → Project → Agent → Mods → Overrides).
• Modular Skills: Add capabilities via mods (e.g., +git, +docker).
• Run Wrappers: Execute agents in different environments (tmux, bash, xterm).
• Dynamic Context: Environment variables and paths injected into every agent session.
• DIR Variable: Automatically resolve paths relative to the mod's directory in ucas.yaml.

# Recommended: symlink the binary
ln -s $(pwd)/ucas-bin ~/bin/ucas

Run ucas install to set up UCAS for your user account:

ucas install

This creates:

• ~/.ucas/ - Main UCAS directory structure
• ~/.ucas/mods/ - User-specific mods
• ~/.ucas/mails/USER/ - User mail storage (inbox/sent/read/archive)
• ~/.ucas/ucas.yaml - User configuration file
• ~/.local/share/applications/ucas-mail.desktop - Desktop entry for clickable notifications

To reinstall:

ucas install --force

Check your installation with ucas doctor:

ucas doctor

This verifies:

• Python version compatibility
• System hostname (for unique Message-IDs)
• Installation directories
• User configuration
• Mail notification setup
• Desktop entry status

UCAS can show desktop notifications when you receive new mail. After running ucas install, edit ~/.ucas/ucas.yaml:

mail:
  notifications:
    on_new_mail: "notify-send 'UCAS Mail' '{subject} from {from}' -u normal"

Available placeholders:

• {subject} - Email subject
• {from} - Sender address
• {id} - Message ID
• {date} - Date string

Desktop entry requirement: Clicking notifications requires libnotify-bin on Linux:

sudo apt install libnotify-bin  # Debian/Ubuntu
sudo dnf install libnotify      # Fedora

Message-ID format: All outgoing emails use hostname in Message-ID: <20260208-133023-5bb6@ucas-hostname>

ucas ls-mods         # Detailed list with descriptions
ucas -q ls-mods      # Names only, grouped by layer
ucas -v ls-mods      # Show paths to mod directories

ucas run generic                   # Default run (tmux + claude)
ucas run generic +skill +acli-pi   # Run using Pi CLI with skills
ucas run generic +run-bash         # Run directly in current terminal

ucas team run my-dev-team   # Start a team
ucas team status            # Check status of running teams
ucas team stop my-dev-team  # Stop a team

Team Autostart: Teams can be configured to start automatically when a mail arrives if no team is running. Add team_autostart: true to your ucas.yaml.

Communicate with agents using the built-in EML-based mail system. Requires mails: true in your project configuration to enable agent mailboxes.

• Address Book: Use ucas mail addressbook to find contacts. Descriptions for local agents are fetched from their ucas.yaml.
• Cross-Project Communication: Send mail to agents in other folders using agent-name@/path/to/project.
• Auto-Reply: Replying to a message (--reply <ID>) automatically resolves the recipient.

# List available contacts
ucas mail addressbook

# Send a message (recipient optional if replying)
echo "Hello Agent" | ucas mail send agent-name "Subject"

# Check inbox (notifies if new mail is waiting)
ucas mail list

# Read a message (moves to read folder)
ucas mail read <ID>

# Archive a message
ucas mail archive <ID>

• -q, --quiet: Minimize output (useful for scripting).
• -v, --verbose: Show which configuration files are being loaded.
• --debug: Show detailed merge tracing and internal commands.
• --dry-run: Show the final command without executing it.

UCAS is highly configurable using ucas.yaml files. You can find the full list of available keys, merge strategies, and variable expansions in the official Configuration Reference.

name: my-mod
description: A useful capability
acli!: # Force-overwrite ACLI block
  executable: my-cli
  prompt_arg: --prompt
  skills_dir: --tools

1. Project: ./.ucas/mods/
2. User: ~/.ucas/mods/
3. System: <install-dir>/mods/ or $UCAS_HOME/mods/

Run tests with:

./run_tests.sh

Always use ./ucas-bin for local execution during development.