Sidekick

An isolated macOS desktop runtime for AI agents, with a native control panel.

Your agent gets its own Mac user session — a real, hidden macOS desktop running alongside yours. It can see, click, type, and use any macOS application without touching your screen, your files, or your session.

Stack

Component	Role	Source
Sidekick	Runtime + native UI + session management	This project
OpenClaw	Agent brain (LLM, skills, memory, heartbeat)	Installed (open source)
Peekaboo	Eyes & hands (screenshot, click, type, scroll)	Installed (open source)

Sidekick.app (control panel)  ←→  SidekickDaemon (agent session)
                                    ├── OpenClaw Gateway (agent brain)
                                    ├── Peekaboo (GUI automation)
                                    └── Any macOS app

Why a Separate Session

Most "computer use" setups run the AI on the same desktop you're using — the agent shares your screen, your Dock, your files. Sidekick takes a different approach.

The sidekick user is a real, hidden macOS account (UID 550). When you start a session, Sidekick bootstraps a full GUI login for that user:

launchctl bootstrap gui/550

This gives the agent its own window server connection, its own Dock, its own running apps — completely invisible and isolated from your session. The agent's desktop is rendered to a virtual display created via CGVirtualDisplay (macOS 14+), a software-backed display that the window server renders to without any physical output.

Your session                    Agent session (sidekick, UID 550)
────────────────────            ──────────────────────────────────
Your apps, your files           Agent's apps, agent's files
Your screen                     Virtual display (CGVirtualDisplay)
                                  └── Captured by ScreenCaptureKit
                                  └── Streamed to Live View in app

ScreenCaptureKit targets the virtual display directly, feeding a real-time stream to the Live View panel in Sidekick.app via IOSurface + XPC. The agent sees a full graphical desktop. You see exactly what it sees. It never touches yours.

Status: The daemon, app, CLI, OpenClaw bridge, and streaming pipeline are all built. The virtual display bootstrapping (CGVirtualDisplay + launchctl bootstrap gui/550) is the next major milestone — the piece that makes everything come alive. See ROADMAP.md.

Quick Start

# Install (creates hidden macOS user, installs OpenClaw + Peekaboo)
sudo ./Scripts/install.sh

# Build
swift build

# Set your API key
sidekick config set api-key sk-ant-...

# Start
sidekick start

# See what it's doing
sidekick screenshot

# Share files
sidekick push ./report.xlsx          # Send to agent
sidekick pull ~/Desktop/output.pdf   # Get from agent

# Mount your project directory
sidekick mount ~/Projects --readonly

CLI

# Session
sidekick start / stop / reset / status

# Screen & input
sidekick screenshot
sidekick click 500 300
sidekick click --element "Sign In"
sidekick type "hello world"
sidekick hotkey "cmd+s"
sidekick scroll 0 100

# Apps
sidekick open Safari
sidekick close Safari
sidekick apps
sidekick windows

# Files & workspace
sidekick push ./file.txt             # Send file to agent
sidekick pull ~/Desktop/output.pdf   # Get file from agent
sidekick mount ~/Projects --readonly
sidekick unmount projects
sidekick mounts

# Shell (runs in agent session)
sidekick exec "ls ~/Desktop"

# Config
sidekick config set api-key sk-ant-...
sidekick config set model anthropic:claude-sonnet-4

# Integration
sidekick mcp-server                  # MCP server (in progress)

Workspace Modes

Mode	Description	Use Case
Isolated (default)	Clean home. Files via ~/Shared/.	Safe browsing, downloads
Selective	Mount specific dirs read-only or read-write.	Dev work, editing files
Mirror	Agent sees your home directory. ⚠️	Power user, max capability

Security Model

Actions are tiered by sensitivity. The control panel surfaces approval requests in real time; the agent blocks until you respond.

Tier	Examples	Default
Always allowed	Screenshot, read files, send you a message	—
Allowed by default	Click/type, open apps, write files, shell	Configurable off
Requires approval	Install packages, access mounted RW dirs, delete files	Prompt
Never allowed	Access your session, escalate privileges, modify its own permissions	Blocked

Connect External Agents

Sidekick will expose an MCP server so any MCP-compatible tool can drive the agent session directly — Claude Code, Claude Desktop, Cursor, Windsurf, and others.

{
  "mcpServers": {
    "sidekick": {
      "command": "sidekick",
      "args": ["mcp-server"]
    }
  }
}

MCP server implementation is in progress. See ROADMAP.md.

Requirements

• macOS 14+ (Sonoma or later)
• Apple Silicon (M1+) recommended
• Xcode 15+ (for building)
• Admin access (for creating the agent user)

Docs

• SPEC.md — Full architecture, design decisions, and component details
• SETUP.md — Detailed setup and configuration guide
• Docs/ROADMAP.md — What's built, what's next, priority order