McClaw Documentation

McClaw is a native macOS AI assistant that brings Claude, ChatGPT, Gemini, Ollama, DashScope (Qwen), Copilot, Codex, and BitNet together in a single app. Instead of using API keys, McClaw wraps the official CLI tools you already have installed, adding a beautiful native interface with voice, canvas, git integration, native channels, connectors, and automation on top.

System Requirements

• macOS 15 (Sequoia) or later
• Apple Silicon or Intel Mac (Universal Binary)
• At least one AI CLI installed (Claude, ChatGPT, Gemini, Ollama, DashScope, Copilot, Codex, or BitNet)

Architecture Overview

McClaw uses a CLI Bridge architecture. Rather than calling AI provider APIs directly, it communicates with the official command-line tools each provider offers. This means:

• McClaw never handles your API keys or credentials
• Authentication is managed by each CLI with its own provider
• You get the same capabilities as the official CLI, plus a native UI
• Streaming responses are parsed in real time from CLI output

Installation

There are two ways to install McClaw:

Option 1: Download the App

Option 2: Build from Source

If you prefer to build McClaw yourself, you need Xcode 16+ with Swift 6.0:

# Source code will be available when the project goes public
# git clone https://github.com/joseconti/mc-claw
# cd mc-claw
# ./scripts/build-app.sh

This generates build/McClaw.app with the complete bundle, including Info.plist, app icon, Sparkle framework for auto-updates, and code signing.

Auto Updates

McClaw uses the Sparkle framework for automatic updates. Once installed, you can check for updates from the menu bar. Updates are downloaded and applied in the background.

CLI Setup

McClaw requires at least one AI CLI tool to be installed on your system. It auto-detects installed CLIs by checking standard installation paths and your shell environment.

Supported Providers

npm install -g @anthropic-ai/claude-code

claude auth login

brew install openai/chatgpt/chatgpt

npm install -g @anthropic-ai/gemini-cli

brew install ollama
ollama pull llama3

# Install via pip
pip install dashscope

export DASHSCOPE_API_KEY=sk-xxxxxxxx

gh extension install github/gh-copilot

gh auth login

npm install -g @openai/codex

# Use with OpenAI
export OPENAI_API_KEY=sk-xxxxxxxx

# Or use with Anthropic
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxx

CLI Detection

McClaw detects installed CLIs automatically by:

1. Checking hardcoded standard paths (e.g. /usr/local/bin, /opt/homebrew/bin)
2. Falling back to your login shell's PATH

If a CLI is installed in a non-standard location, McClaw will still find it as long as it is on your shell's PATH.

First Launch

When you open McClaw for the first time, the Onboarding Wizard guides you through initial setup in 6 steps:

Configuration

McClaw stores its configuration in ~/.mcclaw/mcclaw.json. This file is created automatically on first launch and includes your preferences, provider settings, and feature configuration. You typically do not need to edit this file directly — everything is configurable from the Settings window.

Chat

The chat interface is the core of McClaw. It provides a full-featured conversation experience powered by your chosen AI provider.

Key Features

• Streaming Responses — Responses appear in real time as the AI generates them, parsed from the CLI's streaming output.
• Markdown Rendering — Full Markdown support with headings, lists, tables, bold, italic, links, and more.
• Code Highlighting — Code blocks are syntax-highlighted with language detection. Copy any code block with one click.
• File Attachments — Drag and drop files into the chat to include them as context for the AI.
• Conversation History — All conversations are saved and searchable in the sidebar.
• Projects — Organize conversations into projects for better management.

Switching Providers

You can switch AI providers at any time, even mid-conversation. The provider selector is accessible from the chat input bar. When you switch, McClaw routes your next message through the new provider's CLI.

Slash Commands

McClaw supports built-in slash commands for quick actions:

@fetch Inline Data

Type @fetch followed by a connector name in your message to pull live data from connected services directly into the conversation. For example:

@fetch gmail Show me my unread emails from today

McClaw enriches the prompt with the fetched data before sending it to the AI, so the response includes up-to-date information from your services.

Voice Mode

McClaw includes a full voice interaction system built on native macOS frameworks. No cloud speech services are required.

Modes

• Push-to-Talk — Hold a configurable hotkey to speak. Release to send your message to the AI.
• Wake Word — Say a custom wake word (default: "Hey McClaw") to activate listening. McClaw listens for the wake word in the background using minimal resources.
• Always-On — Continuous listening mode. McClaw processes everything you say and sends it as chat input.

Speech Recognition

Voice input uses SFSpeechRecognizer, Apple's native on-device speech recognition framework. This means:

• Speech processing happens locally on your Mac
• No audio is sent to third-party servers
• Works offline (with on-device models)
• Supports all languages that macOS speech recognition supports

Speech Synthesis

AI responses can be read aloud using NSSpeechSynthesizer. You can choose from any macOS system voice in the Voice Settings.

Voice Overlay

When voice mode is active, a floating overlay shows the current state (listening, processing, speaking) with a visual waveform. The overlay is non-intrusive and can be positioned anywhere on screen.

Permissions

Voice mode requires microphone access. macOS will show a standard permission prompt the first time you activate voice mode. You can manage this in System Settings > Privacy & Security > Microphone.

Canvas

Canvas lets the AI generate interactive HTML content that renders in a floating panel alongside your chat.

How It Works

1. Ask the AI to create something visual (a chart, a form, a mini app, a diagram).
2. The AI generates HTML/CSS/JavaScript code.
3. McClaw renders it in a floating NSPanel with an embedded WKWebView.
4. The canvas updates in real time as the AI streams its response.

Features

• Hot Reload — A file watcher monitors canvas content and reloads the preview instantly when changes are detected.
• JavaScript Bridge — Canvas content can communicate with McClaw through a JS bridge, enabling system integration (file access, clipboard, notifications).
• Custom Scheme Handler — Canvas uses a custom URL scheme (mcclaw://) for loading local resources securely.
• Floating Panel — The canvas window floats above other windows and can be resized, moved, or pinned.

MCP Servers

The Model Context Protocol (MCP) allows AI providers to connect to external tools and data sources. McClaw provides a visual interface for managing MCP server configurations.

Provider Support

Managing MCP Servers

Open Settings > MCP Servers to add, edit, or remove MCP server configurations. McClaw provides a form-based editor so you do not need to edit JSON files manually.

For each MCP server, you configure:

• Name — A human-readable identifier
• Command — The executable to run (for stdio transport)
• Arguments — Command-line arguments
• Environment Variables — Environment variables to pass to the server process
• Transport — stdio, SSE, or streamable-http (Claude only)
• Scope — User-level or project-level (Claude only)

Claude MCP Commands

For the Claude provider, McClaw uses the official CLI commands under the hood:

# Add a server
claude mcp add server-name -- command arg1 arg2

# List configured servers
claude mcp list

# Remove a server
claude mcp remove server-name

Schedules & Automation

McClaw lets you schedule recurring or one-time AI tasks. All schedules are managed locally by the app and persist across restarts.

Schedule Types

• Preset Intervals — Quick presets: every 15 min, 30 min, 1 hour, 6 hours, 12 hours, daily, weekly, monthly.
• Flexible Intervals — "Every X [minutes|hours|days|weeks|months|years] at HH:MM". For example: "Every 2 days at 09:00" or "Every 3 weeks at 14:30". McClaw generates the correct cron expression automatically.
• Cron Expressions — Standard cron syntax for precise scheduling (e.g. 0 9 * * 1-5 for weekdays at 9 AM).
• One-Time Schedules — Run a task once at a specific date and time. Optionally auto-delete the job after successful execution.

Creating a Schedule

Open Settings > Cron and click New Job. The editor is organized in 4 steps:

Connector Enrichment

Scheduled tasks can include @fetch bindings. When the task runs, McClaw automatically fetches the latest data from connected services before sending the prompt to the AI.

Run History

Each job keeps a log of past executions with status (ok, error, skipped), timestamp, duration, and result summary. View history by selecting a job in Settings > Cron.

Connectors

Connectors let McClaw pull live data from external services and include it in your AI conversations. All connectors use OAuth 2.0 with PKCE for authentication, and tokens are stored securely in the macOS Keychain.

Available Connectors

Setting Up OAuth Credentials

Google and Microsoft connectors require you to provide your own OAuth Client ID and Client Secret. You only need to create these once per provider — the same credentials are shared across all connectors of the same provider (e.g., one set of Google credentials works for Gmail, Calendar, Drive, Contacts, and Tasks).

Google Workspace Setup

Microsoft 365 Setup

Connecting Other Services

Development, Communication, Productivity, and Utility connectors use API keys, Personal Access Tokens, or Bot Tokens. Below are direct links to create the credentials for each service:

Development Connectors

Communication Connectors

Productivity & Utility Connectors

Native Channels (Self-Hosted Platforms)

These connectors require a server URL plus a token or API key:

Using Connectors in Chat

Once connected, use connectors in your conversations:

• @fetch gmail — Include your latest emails in the conversation
• @fetch calendar — Include today's events
• @fetch github — Include recent notifications or PRs

You can also use the Connector Action Picker in the chat input bar to browse available actions visually.

Token Management

Connector tokens are stored in the macOS Keychain and refreshed automatically when they expire. You can revoke access to any connector from Settings > Connectors at any time.

Git Integration

McClaw includes a dedicated Git section in the sidebar that lets you browse your GitHub and GitLab repositories, inspect branches, pull requests, issues, and commits — all within the app. Combined with AI chat, you can ask questions about your repos and execute Git operations through natural language.

Enabling Git

The Git section is disabled by default. To enable it:

Repository Browser

The Git panel shows your repositories with search and sort controls. Each repo displays:

• Repository name, visibility (public/private), and fork status
• Primary language with color indicator
• Star count and open PR count
• Last updated time
• Local clone indicator (if McClaw detects a local clone on your machine)

Repository Detail

Double-click a repository to open the detail view with four tabs:

• Branches — All branches with default/protected indicators, ahead/behind counts. Click a branch to set it as the active context.
• Pull Requests — Open, merged, and closed PRs with author, source/target branches, and review state badges.
• Issues — Open and closed issues with labels, assignees, and relative timestamps.
• Commits — Recent commit history with SHA, message, author, and date.

Git Context in Chat

When you select a repository, McClaw creates a Git context that appears as a chip in the chat input bar (e.g., owner/repo / main). This context is automatically injected into your AI prompts, so the AI knows which repository and branch you are working with.

You can:

• Ask questions about the repo: "What are the open PRs for this repo?"
• Request Git operations: "Show me the diff for the last commit"
• Run local Git commands on cloned repos via the @git() intercept

@git() Commands

When a repository has a local clone, the AI can execute Git commands through the @git() intercept — similar to how @fetch() works for connectors. The AI includes @git(status), @git(log --oneline -10), or @git(diff) in its response, and McClaw executes them locally and feeds the output back to the AI.

Supported Operations

Platform Selector

If you have both GitHub and GitLab connected, a capsule pill selector at the top of the Git panel lets you switch between platforms. The selector follows the same design as the CLI provider selector in the chat.

Required Token Scopes

For the Git section to work, your Personal Access Token needs the following scopes:

Git AI Features

Beyond basic repository browsing, McClaw provides AI-powered Git workflows with a confirmation pipeline for safety, contextual actions, and automated repository monitoring.

Execution Pipeline

McClaw uses a confirmation-based pipeline for Git operations:

• @git-confirm — AI requests a Git operation, McClaw shows a confirmation card with the command details before executing.
• Destructive action warnings — Commands like --force, reset, and rebase show highlighted warnings.
• Chain depth tracking — Multi-step chains are limited to 10 operations to prevent infinite loops.
• Sensitive content filtering — Commands are validated before execution to prevent credential exposure.

Contextual Actions (Right-Click Menus)

Right-click on any item in the Git panel to access AI-powered actions specific to the item type:

Quick Actions Bar

When a repository is selected, a floating quick actions panel provides one-click access to common AI operations:

• Explain Repo — Get an AI summary of the repository's purpose and structure
• What Broke? — Analyze recent commits for potential regressions
• Changelog — Generate a changelog from recent commits
• Health Check — Comprehensive repo health analysis
• Security Audit — Scan for potential security issues
• Find TODOs — Locate all TODO/FIXME/HACK comments
• This Week — Summary of activity from the last 7 days

Merge Conflict Resolution

When the AI detects merge conflicts, it can suggest resolutions using the confirmation pipeline. Each conflict shows both sides with the AI's proposed resolution, and you approve or reject before applying.

Cross-Repo Intelligence

Hold Cmd+click to select multiple repositories in the sidebar. McClaw adds all selected repos as context for the AI, enabling cross-repository analysis like "Compare the auth implementation between repo A and repo B".

Repository Monitoring

Combine Git Integration with Schedules to automate repository monitoring:

• PR Review Bot — Automatically review new PRs on a schedule
• Stale Branch Cleanup — Identify and alert on branches older than N days
• Security Scans — Periodic dependency and code security audits
• Health Reports — Weekly summaries delivered to Slack, Telegram, or other channels

Prompt Templates

McClaw includes 30+ built-in prompt templates optimized for Git scenarios. These templates provide structured context to the AI, including repository metadata, branch information, PR diffs, and commit history. Templates are used automatically by contextual actions and quick actions.

Node Mode

Node Mode gives the AI access to macOS hardware capabilities and system operations. All actions require proper TCC (Transparency, Consent, and Control) permissions and go through the execution approval flow.

Available Commands

System

• system.run — Execute shell commands with the approval flow (deny/allowlist/ask modes)
• system.which — Resolve executables via PATH
• system.notify — Send macOS notifications via UNUserNotificationCenter

Camera

• camera.list — List available cameras (built-in, external)
• camera.snap — Capture a photo with JPEG encoding and optional resize
• camera.clip — Record video (max 30s, optional audio)

Requires Camera permission in System Settings > Privacy & Security.

Screen Recording

• screen.record — Record screen via ScreenCaptureKit (H.264 + AAC)

Configurable: screen index, duration (max 60s), FPS (max 30), optional audio. Requires Screen Recording permission.

Location

• location.get — Get current location via CLLocationManager

Requires Location permission (when in use).

Canvas Integration

• canvas.present — Show the canvas panel with content
• canvas.hide — Hide the canvas panel
• canvas.navigate — Load a URL in the canvas
• canvas.eval — Execute JavaScript in the canvas
• canvas.snapshot — Take a screenshot of the canvas

Permissions

Node Mode features require macOS permissions that are requested through standard TCC prompts on first use. You can manage all permissions from Settings > Permissions, which shows the current status of each permission with options to request or open System Settings.

DashScope (Qwen)

DashScope is Alibaba Cloud's AI platform, providing access to the Qwen family of models. Qwen models offer strong multilingual capabilities (especially Chinese and English), vision understanding, and code generation.

Setup

Available Models

Configuration

DashScope settings are accessible from Settings → CLIs → DashScope:

• API Key — Your DashScope API key (stored in Keychain)
• Default Model — Select from Qwen-Max, Qwen-Plus, Qwen-Turbo
• Temperature — Controls response randomness
• Max Tokens — Maximum response length

Copilot CLI

GitHub Copilot CLI provides AI-powered code assistance through the GitHub CLI ecosystem. It excels at code explanation, shell command suggestions, and developer-focused workflows.

Setup

brew install gh

gh extension install github/gh-copilot

gh auth login

Requirements

• Active GitHub Copilot subscription (Individual, Business, or Enterprise)
• GitHub CLI (gh) installed and authenticated

Codex

Codex is OpenAI's autonomous coding agent that runs in the terminal. It can write, refactor, and debug code using OpenAI models.

Setup

npm install -g @openai/codex

# OpenAI
export OPENAI_API_KEY=sk-xxxxxxxx

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxx

# Or use Ollama for local models (no API key needed)
codex --model ollama/llama3

How McClaw Uses Codex

McClaw integrates Codex as a CLI provider, routing messages through the Codex CLI. This means you get Codex's multi-file editing capabilities with McClaw's native UI, voice mode, connectors, and automation on top.

Configuration

Codex settings are accessible from Settings → CLIs → Codex:

• LLM Backend — Select OpenAI, Anthropic, or Ollama
• Model — Choose the specific model (e.g., gpt-4, claude-3, llama3)
• Working Directory — Default directory for code editing sessions

BitNet Experimental

BitNet is an open-source inference framework by Microsoft for 1-bit Large Language Models (1.58-bit LLMs). Unlike traditional models that use 16/32-bit weights, BitNet models restrict all weights to ternary values {-1, 0, +1}, enabling dramatically more efficient inference on CPUs.

How BitNet Differs from Ollama

Both BitNet and Ollama run models locally, but they serve different purposes:

• Ollama runs standard quantized models (4-bit, 8-bit). Large ecosystem of models, higher quality output, more resource-intensive.
• BitNet runs natively ternary models (1.58-bit). Dramatically lower memory and energy consumption, fewer models available, faster on CPU.

System Requirements

BitNet has heavier installation requirements than other providers:

Works on both Apple Silicon (ARM) and Intel (x86) Macs. McClaw detects your architecture and uses the optimal quantization kernels automatically.

Installation

McClaw handles the full BitNet installation through a guided, multi-phase process accessible from Settings → CLIs → BitNet:

Available Models

McClaw includes a built-in registry of BitNet-compatible models. You can download and manage them from Settings → CLIs → BitNet → Manage Models:

Configuration

BitNet settings are accessible from Settings → CLIs → BitNet:

• Default Model — Select which model to use for new conversations
• Threads — Number of CPU threads for inference (auto-detected)
• Context Size — Maximum context window in tokens (default: 2048)
• Temperature — Controls response randomness (default: 0.7)

Limitations

• No streaming support (responses appear when complete)
• No tool use or function calling
• No vision or multimodal capabilities
• No MCP server support
• Limited model ecosystem compared to Ollama
• Each new model requires a kernel rebuild (~5 minutes)

Uninstallation

To remove BitNet, go to Settings → CLIs → BitNet → Uninstall BitNet. This removes the Conda environment and the ~/.mcclaw/bitnet directory.

Security

McClaw is designed with a security-first approach. It never handles your AI provider credentials and includes multiple layers of protection for system access.

Execution Approvals

When an AI provider wants to execute a shell command, McClaw shows an approval dialog before running it. You can:

• Approve once — Allow the specific command this time only
• Always allow — Add a glob pattern to your allow list so matching commands run without prompts
• Deny — Block the command

Glob-Based Allow Lists

Configure trusted command patterns to reduce approval friction. For example:

# Allow all git commands
git *

# Allow listing files in home directory
ls ~/Documents/*

# Allow Python scripts in a specific project
python /path/to/project/*.py

Environment Sanitization

Before passing commands to CLI processes, McClaw automatically strips sensitive environment variables (API keys, tokens, secrets) to prevent accidental exposure. The sanitization is configured via HostEnvSanitizer and covers common patterns like *_KEY, *_SECRET, *_TOKEN, and provider-specific variables.

Keychain Storage

All connector tokens, OAuth credentials, and other secrets are stored in the macOS Keychain using the Security framework. Secrets are never written to plain text files on disk.

TCC Compliance

McClaw follows Apple's Transparency, Consent, and Control framework. Access to sensitive resources requires explicit user permission through standard macOS prompts:

• Microphone — Required for voice mode
• Camera — Required for Node Mode camera capture
• Screen Recording — Required for Node Mode screen capture
• Location — Required for Node Mode location services

Secure IPC

Remote connections between McClaw instances use Unix sockets with HMAC authentication and length-prefixed binary frames. The HMAC key is derived from a shared secret and includes a UID for session binding.

Remote Access

McClaw can be accessed remotely, allowing you to use it from another machine or network.

Connection Modes

• SSH Tunnel — McClaw creates an SSH tunnel (ssh -N -L) to forward a local port to the remote McClaw instance. This is the recommended mode for secure remote access over untrusted networks.
• Direct Connection — Connect directly to a McClaw instance on your local network. Suitable for trusted environments (e.g. home network).

SSH Tunnel Setup

Connection Mode Coordinator

The ConnectionModeCoordinator manages switching between local and remote modes. When remote mode is active, CLI operations are routed through the SSH tunnel, while local features continue to work normally.

Native Channels

Native Channels allow McClaw to receive messages and respond directly on external messaging platforms. Unlike Connectors (which pull data), Native Channels establish a persistent real-time connection to each platform, enabling two-way communication and automated delivery of scheduled task results.

Supported Platforms

Setting Up a Native Channel

Channels & Scheduled Tasks

Native Channels integrate with the Schedules system. When creating a scheduled task, you can select one or more connected channels as delivery targets in Step 4 (Results & Delivery). Each channel destination can have its own recipient (chat ID, channel name, thread, etc.).

How It Works

Each Native Channel maintains a real-time connection using the platform's preferred protocol (WebSocket, long-poll, or event queue). When a message arrives:

1. The channel service receives and parses the incoming message
2. McClaw routes it to the configured AI provider
3. The AI response is sent back through the same channel

All connections auto-reconnect on failure with exponential backoff. Channel credentials are stored securely in the macOS Keychain.

Troubleshooting

CLI Not Detected

Streaming Not Working

McClaw uses --print --output-format stream-json for Claude CLI streaming. If responses appear all at once instead of streaming:

• Make sure your CLI is up to date
• Check that no shell aliases are interfering with the CLI command
• Try running the CLI directly in Terminal to verify streaming works

Voice Mode Not Working

• Check that microphone permission is granted in System Settings > Privacy & Security > Microphone
• Make sure no other app is exclusively using the microphone
• Try selecting a different input device in the Voice Settings

Connector Authentication Failed

• Google 400 error — Make sure you have entered a valid OAuth Client ID and Client Secret from the Google Cloud Console. See Connectors > Google Workspace Setup for step-by-step instructions.
• Microsoft error — Verify your Azure App Registration has the correct API permissions and a valid client secret.
• Revoke the connector in Settings and re-authenticate
• Check that your browser allows popups from McClaw (needed for OAuth flow)
• If token refresh fails, the connector will prompt you to re-authenticate automatically

Remote Connection Issues

• Verify your SSH credentials are correct and the remote host is reachable
• Check firewall rules if connecting to a remote machine
• Use Settings > Remote to test the connection before enabling remote mode
• Ensure the remote machine has the AI CLIs installed and accessible

Build Issues

• Ensure Xcode 16+ is installed with Swift 6.0
• Always use ./scripts/build-app.sh, not swift build alone
• Run cd McClaw && swift test to verify the codebase compiles and tests pass
• If you see Sparkle-related errors, make sure the framework is available in the build path

Config Reset

If McClaw is behaving unexpectedly, you can reset its configuration:

# Back up your config first
cp ~/.mcclaw/mcclaw.json ~/.mcclaw/mcclaw.json.bak

# Remove config to trigger fresh onboarding
rm ~/.mcclaw/mcclaw.json

McClaw will run the Onboarding Wizard again on next launch.

Getting Help

If you encounter issues not covered here:

• Search existing issues (GitHub Issues will be available when the project goes public)
• Open a new issue with your macOS version, McClaw version, and steps to reproduce
• Include relevant logs from ~/.mcclaw/ if available