TuriX macOS Desktop Agent

TuriX-Mac Skill

This skill allows Clawdbot to control the macOS desktop visually using the TuriX Computer Use Agent.

When to Use

• When asked to perform actions on the Mac desktop (e.g., "Open Spotify and play my liked songs").
• When navigating applications that lack command-line interfaces.
• For multi-step visual workflows (e.g., "Find the latest invoice in my email and upload it to the company portal").
• When you need the agent to plan, reason, and execute complex tasks autonomously.

Key Features

🤖 Multi-Model Architecture

TuriX uses a sophisticated multi-model system:

• Brain: Understands the task and generates step-by-step plans
• Actor: Executes precise UI actions based on visual understanding
• Planner: Coordinates high-level task decomposition (when use_plan: true)
• Memory: Maintains context across task steps

📋 Skills System

Skills are markdown playbooks that guide the agent for specific domains:

• github-web-actions: GitHub navigation, repo search, starring
• browser-tasks: General web browser operations
• Custom skills can be added to the skills/ directory

🔄 Resume Capability

The agent can resume interrupted tasks by setting a stable agent_id.

Running TuriX

Basic Task

skills/local/turix-mac/scripts/run_turix.sh "Open Chrome and go to github.com"

Resume Interrupted Task

skills/local/turix-mac/scripts/run_turix.sh --resume my-task-001

✅ Note: run_turix.sh updates examples/config.json for you (task, resume, use_plan, use_skills). If you want to keep a hand-edited config, skip passing a task and edit examples/config.json directly.

Tips for Effective Tasks

✅ Good Examples:

• "Open Safari, go to google.com, search for 'TuriX AI', and click the first result"
• "Open System Settings, click on Dark Mode, then return to System Settings"
• "Open Finder, navigate to Documents, and create a new folder named 'Project X'"

❌ Avoid:

• Vague instructions: "Help me" or "Fix this"
• Impossible actions: "Delete all files"
• Tasks requiring system-level permissions without warning

💡 Best Practices:

1. Be specific about the target application
2. Break complex tasks into clear steps, but do not mention the precise coordinates on the screen.

Hotkeys

• Force Stop: Cmd+Shift+2 - Immediately stops the agent

Monitoring & Logs

Logs are saved to .turix_tmp/logging.log in the project directory. Check this for:

• Step-by-step execution details
• LLM interactions and reasoning
• Errors and recovery attempts

Important Notes

How TuriX Runs

• TuriX can be started via clawdbot exec with pty:true mode
• The first launch takes 2-5 minutes to load all AI models (Brain, Actor, Planner, Memory)
• Background output is buffered - you won't see live progress until task completes or stops

Before Running

Always set PATH first:

export PATH="/usr/sbin:$PATH"
cd your_dir/TuriX-CUA
/opt/anaconda3/envs/turix_env/bin/python examples/main.py

Why? The screencapture tool is located at /usr/sbin/screencapture, which is not in the default PATH.

Checking if TuriX is Running

# Check process
ps aux | grep "python.*main" | grep -v grep

# Should show something like:
# user  57425  0.0  2.4 412396704 600496 s143  Ss+  5:56PM   0:04.76 /opt/anaconda3/envs/turix_env/bin/python examples/main.py

Note: The .turix_tmp directory may not be created until TuriX starts executing steps.

Troubleshooting

Common Issues

Debug Mode

Logs include DEBUG level by default. Check:

tail -f your_dir/TuriX-CUA/.turix_tmp/logging.log

Architecture

User Request
     ↓
[Clawdbot] → [TuriX Skill] → [run_turix.sh] → [TuriX Agent]
                                              ↓
                    ┌─────────────────────────┼─────────────────────────┐
                    ↓                         ↓                         ↓
               [Planner]                 [Brain]                  [Memory]
                    ↓                         ↓                         ↓
                                         [Actor] ───→ [Controller] ───→ [macOS UI]

Skill System Details

Skills are markdown files with YAML frontmatter in the skills/ directory:

---
name: skill-name
description: When to use this skill
---
# Skill Instructions
High-level workflow like: Open Safari,then go to Google.

The Planner selects relevant skills based on name/description; the Brain uses full content for step guidance.

Advanced Options

TuriX Skills System

TuriX supports Skills: markdown playbooks that help the agent behave more reliably in specific domains.

1. Built-in Skills

2. Create a Custom Skill

Create a .md file in the TuriX project's skills/ directory:

---
name: my-custom-skill
description: When performing X specific task
---
# Custom Skill

## Guidelines
- Step 1: Do this first
- Step 2: Then do that
- Step 3: Verify the result

Field definitions:

• name: Skill identifier (used by the Planner to select)
• description: When to use this skill (Planner matches on this)
• The body below: Full execution guide (used by the Brain)

3. Enable Skills

In examples/config.json:

{
  "agent": {
    "use_plan": true,
    "use_skills": true,
    "skills_dir": "skills",
    "skills_max_chars": 4000
  }
}

4. Run a Task with Skills

skills/local/turix-mac/scripts/run_turix.sh "Search for turix-cua on GitHub and star it"

The agent will automatically:

1. Planner reads the skill name and description
2. Selects relevant skills
3. Brain uses the full skill content to guide execution