turix-cua
TuriX Computer Use Agent for macOS desktop automation. Use when you need to perform visual UI tasks that lack CLI or API access, such as opening apps, clicking buttons, navigating GUIs, or multi-step visual workflows.
How do I install this agent skill?
npx skills add https://github.com/shiehxj/turix-cua-skill --skill turix-cuaIs this agent skill safe to install?
- Gen Agent Trust Hubwarn
This skill enables AI-driven macOS desktop automation via the TuriX Computer Use Agent. It requires extensive system permissions, including Accessibility and Screen Recording, to control the user interface. Security concerns include a potential code injection vulnerability in the execution script due to unsafe string interpolation and an attack surface for indirect prompt injection through the processing of untrusted web and GitHub content.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · No issues
- Runlayerwarn
4/9 files flagged
- ZeroLeakspass
1 finding · Score: 82/100
What does this agent skill do?
TuriX-CUA Skill
This skill enables OpenClaw to control macOS desktop visually using the TuriX Computer Use Agent (CUA). TuriX uses a multi-model architecture (Brain, Actor, Planner, Memory) to understand tasks, plan steps, and execute precise UI actions.
📋 When to Use
Use TuriX-CUA when:
- Desktop GUI automation: "Open Spotify and play my liked songs"
- Apps without CLI/API: Navigate applications that lack command-line interfaces
- Multi-step visual workflows: "Find the latest invoice in my email and upload it to the company portal"
- Complex UI interactions: Tasks requiring visual understanding and planning
- Cross-app workflows: "Search iPhone price, create Pages document, and send to contact"
Do NOT use for:
- Tasks that can be done via CLI (use
execinstead) - Simple file operations (use file tools)
- Web scraping (use
web_fetchorbrowsertools) - Tasks requiring system-level permissions without warning
🚀 Quick Start
Prerequisites
-
Install TuriX-CUA:
git clone https://github.com/TurixAI/TuriX-CUA.git cd TuriX-CUA conda create -n turix_env python=3.12 conda activate turix_env pip install -r requirements.txt -
Grant macOS Permissions:
- Accessibility: System Settings → Privacy & Security → Accessibility → Add Terminal/VSCode
- Safari Automation: Safari → Settings → Advanced → Show features for web developers
- Develop menu → Allow Remote Automation
- Develop menu → Allow JavaScript from Apple Events
-
Configure API in
examples/config.json:{ "brain_llm": { "provider": "turix", "model_name": "turix-brain-model", "api_key": "YOUR_API_KEY", "base_url": "https://llm.turixapi.io/v1" }, "actor_llm": { "provider": "turix", "model_name": "turix-actor-model", "api_key": "YOUR_API_KEY", "base_url": "https://llm.turixapi.io/v1" }, "memory_llm": { "provider": "turix", "model_name": "turix-memory-model", "api_key": "YOUR_API_KEY", "base_url": "https://llm.turixapi.io/v1" }, "planner_llm": { "provider": "turix", "model_name": "turix-planner-model", "api_key": "YOUR_API_KEY", "base_url": "https://llm.turixapi.io/v1" } }Or use Ollama (local models):
{ "brain_llm": { "provider": "ollama", "model_name": "llama3.2-vision", "base_url": "http://localhost:11434" } // ... same for actor, memory, planner }
Basic Usage
# Run a simple task
skills/turix-cua/scripts/run_turix.sh "Open Chrome and go to github.com"
# Run with planning enabled (for complex tasks)
skills/turix-cua/scripts/run_turix.sh "Search AI news and create summary" --use-plan
# Resume an interrupted task
skills/turix-cua/scripts/run_turix.sh --resume my-task-001
📁 File Structure
skills/turix-cua/
├── SKILL.md # This file
├── README.md # Detailed documentation
├── scripts/
│ └── run_turix.sh # Main execution script
└── examples/
└── config.json # TuriX configuration (managed by script)
⚙️ Configuration Options
| Option | Description | Default |
|---|---|---|
use_plan | Enable planning for complex tasks | false |
use_skills | Enable skill selection | false |
resume | Resume from previous interruption | false |
agent_id | Stable ID for task resumption | auto-generated |
max_steps | Limit total steps | 100 |
max_actions_per_step | Actions per step | 5 |
📋 Task Examples
✅ Good Tasks
Simple:
- "Open Safari, go to google.com, search for 'TuriX AI', click first result"
- "Open System Settings, click on Dark Mode, return to System Settings"
- "Open Finder, navigate to Documents, create folder 'Project X'"
Complex (use --use-plan):
- "Search iPhone 17 price on Apple store, create Pages document with findings, send to contact John"
- "Open Discord, find message with Excel file from boss, download it, create chart in Numbers, insert to PowerPoint"
- "Search AI news on 36kr and Huxiu, summarize top 5 stories, save to Word document"
❌ Avoid
- Vague: "Help me" or "Fix this"
- Impossible: "Delete all files"
- Without context: "Do it" (unclear what "it" is)
- System-level: "Install software" (requires permissions)
🔧 Script Usage
run_turix.sh
# Basic usage
./run_turix.sh "Your task description"
# With options
./run_turix.sh "Task" --use-plan --use-skills --background
# Resume task
./run_turix.sh --resume my-task-001
# Set custom agent ID
./run_turix.sh "Task" --agent-id custom-id-123
Options:
--use-plan: Enable planning (for complex multi-step tasks)--use-skills: Enable skill selection--background: Run in background (non-blocking)--agent-id <id>: Set custom agent ID for resumption--resume: Resume interrupted task
How It Works
The script:
- Updates
examples/config.jsonwith task and options - Sets PATH correctly (includes
/usr/sbinforscreencapture) - Activates conda environment
- Runs TuriX agent
- Handles UTF-8/Chinese text correctly via Python
📊 Monitoring & Debugging
Check Status
# Check if TuriX is running
ps aux | grep "python.*main.py" | grep -v grep
# View logs
tail -f TuriX-CUA/.turix_tmp/logging.log
# List step files
ls -lt TuriX-CUA/examples/.turix_tmp/brain_llm_interactions.log_brain_*.txt
Log Files
| File | Description |
|---|---|
.turix_tmp/logging.log | Main execution log |
brain_llm_interactions.log_brain_N.txt | Brain reasoning for step N |
actor_llm_interactions.log_actor_N.txt | Actor actions for step N |
Key Log Markers
📍 Step N- New step started✅ Eval: Success/Failed- Step evaluation🎯 Goal to achieve this step- Current goal🛠️ Action- Executed action✅ Task completed successfully- Task done
Force Stop
Hotkey: Cmd+Shift+2 (in the running terminal)
Command:
pkill -f "python examples/main.py"
🧩 Skills System
TuriX supports Skills: markdown playbooks for specific domains.
Built-in Skills
github-web-actions: GitHub navigation, repo search, starringbrowser-tasks: General web browser operations
Create Custom Skill
Create .md file in TuriX-CUA/skills/:
---
name: my-skill-name
description: When to use this skill (Planner matches on this)
---
# Skill Instructions
## Guidelines
- Step 1: Do this first
- Step 2: Then do that
- Step 3: Verify result
## Safety
- Confirm before important actions
Enable Skills
In examples/config.json:
{
"agent": {
"use_plan": true,
"use_skills": true,
"skills_dir": "skills",
"skills_max_chars": 4000
}
}
📝 Best Practices
1. Workflow Design
Recommended pattern:
- Use
web_fetchto gather information - Use Python to create documents (faster, more reliable)
- Use TuriX only for GUI tasks it excels at (sending files, app navigation)
Example:
# 1. Fetch news (OpenClaw)
news = web_fetch("https://36kr.com")
# 2. Create Word doc (OpenClaw)
doc = Document()
doc.add_heading('AI News')
doc.save('news.docx')
# 3. Send via Messages (TuriX)
run_turix.sh "Open Messages, send news.docx to contact John"
2. Task Instructions
Be specific:
- ✅ "Open Safari, go to google.com, search 'AI news'"
- ❌ "Search the web"
Break down complex tasks:
- ✅ "Open Finder, go to Documents, create folder 'Projects'"
- ❌ "Organize my files"
Don't mention coordinates:
- ✅ "Click the Settings button"
- ❌ "Click at x=100, y=200"
3. Performance Tips
- First run: 2-5 minutes to load AI models
- Subsequent runs: Much faster (models cached)
- Complex tasks: Use
--use-planfor better success rate - Long tasks: Use
--backgroundand monitor logs
4. Chinese Text Support
The script handles UTF-8 correctly:
- Uses Python for config updates (not shell interpolation)
- Reads/writes with
encoding='utf-8' - Uses
ensure_ascii=Falsein JSON
⚠️ Troubleshooting
| Error | Solution |
|---|---|
NoneType has no attribute 'save' | Grant Screen Recording permission |
Screen recording access denied | Run Safari trigger command, click Allow |
Conda environment not found | conda create -n turix_env python=3.12 |
| Module import errors | conda activate turix_env && pip install -r requirements.txt |
| Keyboard listener errors | Add Terminal to Accessibility permissions |
| Task stuck on step 1 | Check .turix_tmp/ directory exists |
| No log output | Check config.json logging_level |
🔐 Security Notes
- TuriX runs locally - no data sent externally (unless using cloud APIs)
- Grant minimal permissions needed
- Review tasks before execution
- Use
--backgroundfor long-running tasks with monitoring
📚 Resources
- GitHub: https://github.com/TurixAI/TuriX-CUA
- ClawHub: https://clawhub.ai/Tongyu-Yan/turix-cua
- Discord: https://discord.gg/yaYrNAckb5
- Website: https://turix.ai
- API Platform: https://turixapi.io
🎯 Example OpenClaw Integration
# In OpenClaw skill or workflow:
# 1. Simple task
exec('skills/turix-cua/scripts/run_turix.sh "Open Safari"')
# 2. Complex task with planning
exec('skills/turix-cua/scripts/run_turix.sh "Search AI news and summarize" --use-plan')
# 3. Monitor progress
exec('tail -f TuriX-CUA/.turix_tmp/logging.log')
# 4. Check completion
exec('ps aux | grep "python.*main.py" | grep -v grep')
Version: 1.0.0
Last Updated: 2026-02-23
Compatibility: OpenClaw + TuriX-CUA v0.3+
Platform: macOS 15+
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/shiehxj/turix-cua-skill/turix-cua">View turix-cua on skillZs</a>