💡 Idea 3: Deploy Clawpilot — AI Desktop Assistant¶
| Field | Detail |
|---|---|
| Priority | 📌 Important |
| Status | 🔄 In Progress |
| Category | 🎓 Learning Project / 💼 Official |
| Date added | 2026-03-29 |
| Started | 2026-03-29 |
| Source | Enterprise GitHub repo: gim-home/m |
| Version (repo) | 0.20.50 |
| To-Do link | I3 on To-Do List |
What Is Clawpilot? (The Simple Version)¶
☕ Cloud Café analogy: Imagine your café has two ways to manage it:
- Copilot CLI = A walkie-talkie to your sous chef. You speak (type), they do things. Fast, efficient, but text-only.
- Clawpilot = A touchscreen tablet for your restaurant manager. Same kitchen (AI engine), but now you can SEE things — plus the manager can also go online to order supplies (browser control) and print beautiful menus (Office docs).
Both talk to the same chef (Copilot SDK). One uses voice (terminal), the other uses a screen (GUI).
Clawpilot is an internal AI-powered desktop app built on the same GitHub Copilot SDK that powers Copilot CLI. It wraps that AI engine in a visual desktop window with extra capabilities.
Architecture Overview¶
The Big Picture¶
┌─────────────────────────────────────────────────────────────────────┐
│ YOUR COMPUTER │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ CLAWPILOT (Electron App) │ │
│ │ │ │
│ │ ┌─────────────────────┐ ┌──────────────────────────────┐ │ │
│ │ │ RENDERER PROCESS │ │ MAIN PROCESS │ │ │
│ │ │ (What you see) │ │ (The engine room) │ │ │
│ │ │ │ │ │ │ │
│ │ │ ┌───────────────┐ │ │ ┌────────────────────────┐ │ │ │
│ │ │ │ Chat Window │ │◄──►│ │ Copilot SDK Client │ │ │ │
│ │ │ │ (React UI) │ │IPC │ │ (AI Brain) │ │ │ │
│ │ │ ├───────────────┤ │ │ ├────────────────────────┤ │ │ │
│ │ │ │ Model Picker │ │ │ │ Session Manager │ │ │ │
│ │ │ ├───────────────┤ │ │ │ (Conversations) │ │ │ │
│ │ │ │ Skills Panel │ │ │ ├────────────────────────┤ │ │ │
│ │ │ ├───────────────┤ │ │ │ Permission System │ │ │ │
│ │ │ │ Settings │ │ │ │ (Safety checks) │ │ │ │
│ │ │ └───────────────┘ │ │ └────────────────────────┘ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ Built with: │ │ Built with: │ │ │ │
│ │ │ React + TypeScript │ │ Node.js │ │ │ │
│ │ │ + Tailwind CSS │ │ + Electron │ │ │ │
│ │ └─────────────────────┘ └──────────────┼───────────────┘ │ │
│ │ │ │ │
│ └────────────────────────────────────────────┼──────────────────┘ │
│ │ │
│ ┌────────────────────────────────────────────┼──────────────────┐ │
│ │ MCP SERVERS (Connected Tools) │ │ │
│ │ ▼ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ 📁 Filesystem │ │ 🌐 Playwright │ │ 🐚 Shell │ │ │
│ │ │ Read/Write │ │ Browser │ │ Commands │ │ │
│ │ │ Files │ │ Automation │ │ (PowerShell) │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ 🧠 WorkIQ │ │ 🔍 Web Search│ │ │
│ │ │ M365 Data │ │ Internet │ │ │
│ │ │ (via CLI) │ │ Search │ │ │
│ │ └──────────────┘ └──────────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ EXTERNAL SERVICES (Cloud) │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ GitHub │ │ GitHub │ │ Microsoft│ │ Azure │ │ │
│ │ │ Auth │ │ Copilot │ │ 365 │ │ Table │ │ │
│ │ │ (OAuth) │ │ (AI) │ │ (WorkIQ) │ │ (Skills) │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
How the Two Processes Talk (IPC Bridge)¶
☕ Analogy: Think of it like a restaurant with a kitchen (Main Process) and a dining room (Renderer). The waiter (IPC Bridge) carries orders from diners to the kitchen and brings food back. Diners never walk into the kitchen directly — that's a security rule!
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ RENDERER │ │ IPC BRIDGE │ │ MAIN PROCESS │
│ (Dining Room) │ │ (The Waiter) │ │ (Kitchen) │
│ │ │ │ │ │
│ "I want to send │────────►│ Carries the │────────►│ SessionManager │
│ a message" │ │ request across │ │ processes it │
│ │ │ the bridge │ │ │
│ Gets the reply │◄────────│ Brings back │◄────────│ Returns result │
│ and shows it │ │ the response │ │ {success: true} │
│ │ │ │ │ │
│ window. │ │ ipcRenderer │ │ ipcMain │
│ copilotAPI. │ │ .invoke() │ │ .handle() │
│ send() │ │ │ │ │
└──────────────────┘ └──────────────────┘ └──────────────────┘
Session Lifecycle (How a Conversation Works)¶
User opens Clawpilot
│
▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Auth Screen │────►│ GitHub │────►│ Copilot SDK │
│ "Sign In" │ │ Device Flow │ │ Initialized │
└──────────────┘ └──────────────┘ └──────┬───────┘
│
┌───────────────────────────────────────────┘
▼
┌──────────────┐
│ New Chat │ ◄── User clicks "New Chat"
└──────┬───────┘
│
▼
┌──────────────────────────────────────────────────────────┐
│ Session Created │
│ • UUID generated │
│ • MCP servers configured (filesystem, playwright) │
│ • System prompt built (AI instructions + skills) │
│ • Personality applied (default, JARVIS, TARS, etc.) │
│ • Saved to ~/.copilot/m-sessions/{id}.json │
└──────────────────────────┬───────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────┐
│ Chat Loop │
│ │
│ User types message ──► SDK processes ──► AI responds │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌──────────────┐ │ │
│ │ │ Tool calls? │ │ │
│ │ │ (file, shell, │ │ │
│ │ │ browser...) │ │ │
│ │ └──────┬───────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌──────────────────┐ │ │
│ │ │ Permission Check │ │ │
│ │ │ Tier 1: Auto? │──Yes──► │ │
│ │ │ Tier 2: Per-server│──Yes──► │ │
│ │ │ Tier 3: Session? │──Yes──► │ │
│ │ │ Tier 4: Ask User │ │ │
│ │ └──────────────────┘ │ │
│ │ │ │
│ ▼ ▼ │
│ Messages auto-saved to disk Streaming │
│ after every exchange response shown │
└────────────────────────────────────────────────────────────┘
Permission System (3-Tier Safety)¶
☕ Analogy: Like a café kitchen with safety rules:
- Tier 1 (Auto-approve): Reading the recipe book (safe, always allowed) =
ls,cat,git status- Tier 2 (Ask manager): Using the deep fryer (needs a trained person to approve) = file writes, npm install
- Tier 3 (Block): Playing with fire near the gas line (too dangerous) = piped commands, redirects
Tool permission request arrives
│
▼
┌─────────────────────────────────────┐
│ Tier 1: Global Auto-Approve? │
│ (User turned on "allow everything")│
│ │
│ settings.autoApprove.global = true │
└────────┬──────────────┬─────────────┘
│ YES │ NO
▼ ▼
✅ Approved ┌─────────────────────────────────┐
│ Tier 2: Per-Server Auto-Approve? │
│ (e.g., auto-approve shell reads) │
└────────┬──────────────┬──────────┘
│ YES │ NO
▼ ▼
✅ Approved ┌──────────────────────────┐
│ Tier 3: Read-Only Check │
│ Is it a safe command? │
│ (ls, cat, git status...) │
└────────┬──────────┬──────┘
│ YES │ NO
▼ ▼
✅ Approved ┌────────────────┐
│ Tier 4: Dialog │
│ ┌────────────┐│
│ │ Allow ││
│ │ Auto-allow││
│ │ Deny ││
│ └────────────┘│
└────────────────┘
Deep Dive: What Are All These Packages? (1,716 of Them!)¶
When you run pnpm install, Clawpilot downloads 1,716 packages. That sounds like a lot, but most are sub-dependencies (packages that other packages need). The project directly uses about 35 key packages, organised into 6 groups.
🧠 Group 1: The AI Brain¶
┌──────────────────────────────────────────────────────────────────┐
│ THE AI BRAIN GROUP │
│ │
│ ┌──────────────────────┐ │
│ │ @github/copilot-sdk │ ◄── THE most important package │
│ │ v0.1.32 │ Everything else serves this │
│ │ │ │
│ │ What it does: │ │
│ │ • Creates AI sessions│ │
│ │ • Sends messages │ │
│ │ • Manages tool calls │ │
│ │ • Streams responses │ │
│ │ • Handles auth │ │
│ └──────────┬───────────┘ │
│ │ talks to │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ GitHub Copilot │ │
│ │ Cloud Service │ │
│ │ (runs the AI models) │ │
│ └──────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
☕ Analogy: The Copilot SDK is like hiring a head chef. You don't need to know how to cook (run AI models yourself) — you just tell the chef what you want ("make a pasta dish"), and the chef figures out the recipe (AI reasoning), gathers ingredients (calls tools), and delivers the dish (response). The chef works remotely in a cloud kitchen (GitHub's servers), and the SDK is the phone line connecting your restaurant to that kitchen.
What @github/copilot-sdk does step by step:
| Function | What It Does | In Simple English |
|---|---|---|
new CopilotClient() |
Creates a connection to the AI service | "Hire the chef and give them a phone" |
client.start() |
Spawns a local Copilot CLI process | "Chef clocks in for the shift" |
client.createSession() |
Opens a new conversation with system prompt, model, MCP servers | "Start a new table's order — here's the menu and tools available" |
session.sendMessage() |
Sends user text to the AI and gets streaming response | "Customer orders pasta" → chef starts cooking and sends updates |
session.destroy() |
Closes a conversation, frees resources | "Table is done, clear the dishes" |
onPreToolUse hook |
Fires before the AI uses a tool | "Chef wants to use the deep fryer — check if it's safe first" |
onPermissionRequest |
Asks user for permission | "Chef asks: 'Can I open the back door for a delivery?'" |
The critical flow when you send a message:
Your message: "Create a PowerPoint about our Q4 results"
│
▼
┌────────────────────────────────────────────────────────┐
│ Copilot SDK receives your message │
│ │
│ Step 1: Sends to GitHub's AI service (cloud) │
│ "Here's the user's request + system prompt │
│ + available tools" │
│ │
│ Step 2: AI decides: "I need to use the pptx skill" │
│ → SDK fires onPreToolUse event │
│ → Permission check happens │
│ │
│ Step 3: AI calls the tool (creates .pptx file) │
│ → SDK fires onPostToolUse event │
│ │
│ Step 4: AI writes response: "I've created your PPT" │
│ → SDK streams message_delta events │
│ → UI shows text appearing word by word │
│ │
│ Step 5: Done │
│ → SDK fires session.idle event │
│ → UI re-enables the input box │
└────────────────────────────────────────────────────────┘
🔌 Group 2: The Connectors (MCP Packages)¶
These give the AI its "hands" — the ability to DO things in the real world.
┌────────────────────────────────────────────────────────────────────┐
│ MCP TOOL PACKAGES │
│ │
│ ┌────────────────────────────────────┐ │
│ │ @modelcontextprotocol/ │ │
│ │ server-filesystem │ │
│ │ │ │
│ │ 📁 Read files, write files, │ │
│ │ search directories, │ │
│ │ create folders │ │
│ │ │ │
│ │ Works in: workspace/ folder │ │
│ │ Transport: stdio (pipe) │ │
│ └────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────┐ │
│ │ @playwright/mcp │ │
│ │ │ │
│ │ 🌐 Open websites, click buttons, │ │
│ │ fill forms, take screenshots, │ │
│ │ read page content │ │
│ │ │ │
│ │ Uses: Microsoft Edge browser │ │
│ │ Transport: stdio (pipe) │ │
│ └────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────┐ │
│ │ @microsoft/workiq │ │
│ │ │ │
│ │ 🧠 Query Outlook, Teams, Calendar, │ │
│ │ SharePoint, OneDrive │ │
│ │ │ │
│ │ Runs as: CLI tool (shell command) │ │
│ │ Auth: MSAL (Microsoft login) │ │
│ └────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────┘
☕ Analogy — Chef's Tools:
- filesystem = The chef's knife — can chop (read/write) ingredients (files)
- playwright = A delivery driver — goes out to other restaurants (websites) and brings things back
- workiq = A phone to the office — calls company HQ to ask "what meetings do I have tomorrow?"
How this connects to your MCP learning: You already learned about MCP servers! Clawpilot uses the exact same concept — but pre-configures them for you instead of you setting up mcp-config.json manually.
| Concept | In Your MCP Learning | In Clawpilot |
|---|---|---|
| MCP Server | A server that gives AI access to tools | Same! filesystem and playwright are MCP servers |
| Transport | How messages travel (stdio, SSE, HTTP) | Uses stdio — pipes messages through the process |
| Tools | Functions the AI can call | read_file, write_file, navigate, click, etc. |
| Who starts them? | You configure in mcp-config.json |
Clawpilot auto-starts them in SessionManager |
🔐 Group 3: The Security (Auth Packages)¶
┌────────────────────────────────────────────────────────────────────┐
│ AUTHENTICATION GROUP │
│ │
│ ┌─────────────────────────────┐ ┌─────────────────────────────┐ │
│ │ @azure/msal-node │ │ @azure/msal-node-extensions │ │
│ │ │ │ │ │
│ │ Microsoft Authentication │ │ Extra features: │ │
│ │ Library │ │ • Token caching │ │
│ │ │ │ • Windows credential │ │
│ │ Used for: M365 login │ │ manager integration │ │
│ │ (WorkIQ needs this to │ │ • Persistent login │ │
│ │ access your Outlook, │ │ (don't re-auth every │ │
│ │ Teams, Calendar data) │ │ time you open the app) │ │
│ └─────────────────────────────┘ └─────────────────────────────┘ │
│ │
│ Two separate auth flows: │
│ │
│ GitHub Auth (for AI): │
│ Copilot SDK → GitHub Device Flow → ~/.copilot/config.json │
│ │
│ M365 Auth (for WorkIQ): │
│ MSAL → Browser OAuth2 → ~/.copilot/m-auth/msal-cache.json │
│ (Windows: tries WAM first = silent, no browser needed) │
└────────────────────────────────────────────────────────────────────┘
☕ Analogy — Two ID Badges:
- GitHub auth (via SDK) = Your "kitchen access" badge — lets you talk to the AI chef
- MSAL auth (for M365) = Your "office building" badge — lets you access company data
- WAM (Windows Account Manager) = The automatic door — if your laptop is already signed in to your corp account, it opens silently without tapping your badge
🎨 Group 4: The Look & Feel (UI Packages)¶
| Package | What It Is | Café Analogy |
|---|---|---|
| react v19.2 | Architecture blueprint — defines WHERE everything goes | The restaurant floor plan |
| react-dom v19.2 | Construction crew — actually builds the rooms | The builders who follow the plan |
| radix-ui v1.4 | Invisible mechanisms — dropdown menus, dialogs, tooltips | Door hinges and drawer slides |
| shadcn v4.1 | Pre-built beautiful components (buttons, cards) | Interior designer's furniture catalogue |
| tailwind-merge | Smart CSS combiner (resolves conflicts) | Paint colour mixer |
| lucide-react | Icons for every button and menu item | The decorations (🔍 ⚙️ 💬 etc.) |
| class-variance-authority | Makes button styles consistent ("primary"=blue, "danger"=red) | The brand guidelines document |
| @fluentui/react-brand-icons | Microsoft brand icons | The company logo stickers |
📊 Group 5: The Telemetry (@1js packages)¶
These are Microsoft's internal logging packages — they send anonymous usage data back to the Clawpilot team.
| Package | Purpose | Café Analogy |
|---|---|---|
| @1js/diagnostics | Error/crash reporting | Security camera footage |
| @1js/hugin-* | Event logging (which features you used) | Receipt logs |
| @1js/px-telemetry | Performance measurement (how fast) | Kitchen timer records |
| @1js/functional | Utility functions | Swiss army knife |
| @1js/guid | Generates unique IDs | Order numbers |
| @1js/midgard-error | Error formatting | Makes crash reports readable |
⚠️ These are from the private 1JS feed — that's why we needed
auth:1jsin Step 3!
📝 Group 6: Content & Utilities¶
| Package | What It Does | Simple Analogy |
|---|---|---|
| streamdown | Renders streaming Markdown as it arrives | Live subtitles — shows text as the AI "speaks" |
| @streamdown/mermaid | Renders Mermaid diagrams in chat | Turns code into visual flowcharts |
| @shikijs/* | Syntax highlighting for code blocks | Colour-coding a recipe: ingredients in green, steps in blue |
| dompurify | Sanitises HTML to prevent attacks | Food safety inspector — removes anything harmful |
| cmdk | Command palette (search bar) | The café's ordering kiosk |
| ws | WebSocket client | Real-time phone line (for Teams integration) |
| @tanstack/react-query | Smart data fetching with caching | Remembering menu prices instead of re-checking every time |
The Full Package Map¶
CLAWPILOT PACKAGES (1,716 total)
│
┌─────────────────┼─────────────────┐
│ │ │
🧠 AI Core 🔌 Connectors 🎨 UI Layer
│ │ │
┌────────┴──────┐ ┌─────┴────────┐ ┌────┴──────────┐
│ copilot-sdk │ │ filesystem │ │ react │
│ (the brain) │ │ playwright │ │ radix-ui │
│ │ │ workiq │ │ shadcn │
│ │ │ msal-node │ │ tailwind │
└────────────────┘ └──────────────┘ │ lucide │
│ shikijs │
┌─────────────────┐ │ streamdown │
│ │ └───────────────┘
📊 Telemetry 🔧 Utilities
│ │
┌────────┴──────┐ ┌─────┴────────┐
│ @1js/hugin-* │ │ clsx │
│ @1js/px-* │ │ cmdk │
│ diagnostics │ │ dompurify │
└───────────────┘ │ ws │
└──────────────┘
Direct dependencies: 35
With sub-dependencies: 1,716
Technology Stack Explained (Simple English)¶
Each technology is explained with a real-world analogy so you don't need coding background to understand.
| Technology | What It Is | Simple Analogy | Why Clawpilot Uses It |
|---|---|---|---|
| Electron | A framework that turns web pages into desktop apps | Like putting a website inside a picture frame so it looks like a real painting (app) | Makes Clawpilot work as a desktop app (like VS Code, Slack, Teams) |
| React | A JavaScript library for building user interfaces | Like LEGO blocks — you build the screen from reusable pieces (components) | Builds the chat window, buttons, settings panels |
| TypeScript | JavaScript but with type-checking | Like a spell-checker for code — catches mistakes before they break things | Prevents bugs, makes code reliable |
| Vite | A build tool that bundles code | Like a food processor — takes raw ingredients (code files) and blends them into a finished dish (the app) | Compiles and bundles all the code for the app |
| Tailwind CSS | A styling system using utility classes | Like a paint-by-numbers kit — pick colours and spacing using preset codes instead of mixing paint yourself | Makes the app look beautiful with consistent design |
| Node.js | JavaScript running on your computer (not browser) | Like a chef who can cook anywhere — not just in the restaurant (browser) | Powers the "engine room" (main process) of the app |
| pnpm | A package manager (installs libraries) | Like a warehouse manager who efficiently stores and retrieves ingredients (code packages) | Installs all the 3rd-party code libraries Clawpilot needs |
| Copilot SDK | The AI engine from GitHub | Like the brain of your sous chef — understands requests and decides what to do | THE core AI that powers all chat + tool usage |
| MCP | Model Context Protocol — how AI connects to tools | Like a universal adapter plug — lets the AI brain talk to different tools (files, browser, M365) using the same "language" | Connects AI to filesystem, browser, and M365 |
| Playwright | Browser automation library | Like a robot arm that can click, type, and navigate websites for you | Enables browser control (fill forms, take screenshots) |
| MSAL | Microsoft Authentication Library | Like a digital ID badge that proves you're allowed to access Microsoft 365 data | Authenticates you with Microsoft 365 for WorkIQ |
How They All Fit Together¶
┌─────────────────────────────────────────────────────┐
│ WHAT YOU SEE (Frontend) │
│ React + TypeScript + Tailwind CSS │
│ "The dining room with beautiful furniture" │
├─────────────────────────────────────────────────────┤
│ DESKTOP WRAPPER │
│ Electron │
│ "The building that holds the restaurant" │
├─────────────────────────────────────────────────────┤
│ AI ENGINE │
│ Copilot SDK + Node.js │
│ "The chef in the kitchen" │
├─────────────────────────────────────────────────────┤
│ CONNECTIONS TO TOOLS │
│ MCP (filesystem, Playwright, WorkIQ) │
│ "The delivery drivers bringing ingredients" │
├─────────────────────────────────────────────────────┤
│ BUILD TOOLS │
│ Vite (bundler) + pnpm (packages) │
│ "The construction crew that built the restaurant" │
└─────────────────────────────────────────────────────┘
Clawpilot vs GitHub Copilot CLI — Complete Comparison¶
Feature Comparison¶
| Feature | GitHub Copilot CLI | Clawpilot | Winner |
|---|---|---|---|
| Interface | Terminal (text-only) | Desktop GUI (visual) | 🏆 Clawpilot |
| Chat | Text input/output | Rich markdown + images + streaming | 🏆 Clawpilot |
| File access | ✅ Built-in | ✅ Via MCP filesystem | 🤝 Tie |
| Shell commands | ✅ Built-in | ✅ Built-in with visual permission cards | 🏆 Clawpilot |
| Browser automation | ❌ Not available | ✅ Playwright MCP (navigate, click, screenshot) | 🏆 Clawpilot |
| Office docs (Word/PPT/Excel) | ❌ Not available | ✅ Built-in skills (docx, pptx, xlsx) | 🏆 Clawpilot |
| WorkIQ (M365) | ✅ Via MCP server | ✅ Built-in (via CLI shim) | 🤝 Tie |
| Web search | ✅ Built-in | ✅ Built-in | 🤝 Tie |
| Custom instructions | ✅ copilot-instructions.md | ✅ Skills system (SKILL.md) | 🤝 Tie |
| Agents (custom) | ✅ AGENTS.md | ❌ Uses skills instead | 🏆 CLI |
| Multiple sessions | ❌ Single session | ✅ Up to 10 concurrent (with pausing) | 🏆 Clawpilot |
| Personality presets | ❌ Not available | ✅ 7 presets (JARVIS, TARS, etc.) | 🏆 Clawpilot |
| Model switching | ✅ /model command |
✅ Dropdown picker with badges | 🤝 Tie |
| Background tasks | ❌ Not available | ✅ Heartbeat system (scheduled tasks) | 🏆 Clawpilot |
| Skill marketplace | ❌ Not available | ✅ Browse, install, vote, publish | 🏆 Clawpilot |
| Image support | ❌ Not available | ✅ Attach/view images in chat | 🏆 Clawpilot |
| Setup difficulty | Easy (npm install -g) | Complex (clone, pnpm, 1JS feed, build) | 🏆 CLI |
| Resource usage | Low (~50-100 MB) | High (~300-500 MB, Electron + Chromium) | 🏆 CLI |
| Update method | npm update -g |
git pull && pnpm install && rebuild |
🏆 CLI |
| Stability | GA (production) | Pre-release (v0.20.x, internal) | 🏆 CLI |
| Keyboard speed | ⚡ Fastest (pure typing) | Slower (mouse + keyboard) | 🏆 CLI |
| Azure MCP tools | ✅ Full Azure MCP suite | ❌ Not configured | 🏆 CLI |
| M365 admin tools | ✅ Graph MCP server | ❌ Not configured | 🏆 CLI |
When to Use Which?¶
| Scenario | Best Tool | Why |
|---|---|---|
| Quick file edits, git operations | Copilot CLI | Faster to type commands |
| Creating Word docs or PowerPoint decks | Clawpilot | Built-in Office skills |
| Browser automation (fill forms, navigate) | Clawpilot | Playwright MCP built-in |
| Azure resource management | Copilot CLI | Full Azure MCP suite available |
| M365 tenant admin tasks | Copilot CLI | Graph MCP server configured |
| Customer demos (visual) | Clawpilot | GUI is more impressive to show |
| Daily coding/DevOps work | Copilot CLI | Terminal workflow, faster |
| Querying M365 data (emails, meetings) | Either | Both have WorkIQ |
| Running while working in terminal | Copilot CLI | Already in terminal |
| Building and testing websites | Clawpilot | Can preview in browser automation |
| Scheduled background tasks | Clawpilot | Heartbeat system |
| Learning/experimenting | Both | Different skills to learn |
The Bottom Line¶
┌───────────────────────────────────────────────────────────────────────┐
│ │
│ 🤔 "Should I use Clawpilot OR Copilot CLI?" │
│ │
│ Answer: USE BOTH! They complement each other. │
│ │
│ ┌─────────────────────┐ ┌──────────────────────┐ │
│ │ COPILOT CLI │ │ CLAWPILOT │ │
│ │ │ │ │ │
│ │ Your daily driver │ │ Your power tool │ │
│ │ for terminal work │ │ for visual tasks │ │
│ │ and Azure/M365 │ │ and demos │ │
│ │ admin tasks │ │ │ │
│ │ │ │ Browser automation │ │
│ │ ⚡ Fast │ │ Office doc creation │ │
│ │ 🎯 Focused │ │ Multiple sessions │ │
│ │ 💻 Terminal-native │ │ 🎨 Visual │ │
│ └─────────┬───────────┘ └──────────┬────────────┘ │
│ │ │ │
│ └──────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Same AI Engine │ │
│ │ (Copilot SDK) │ │
│ │ Same GitHub Auth │ │
│ │ Same Quality │ │
│ └──────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────┘
Can I Install This on My Corp Laptop?¶
Compatibility Check¶
| Requirement | Your Setup | Status | Notes |
|---|---|---|---|
| Node.js 20+ | ✅ Installed | ✅ Ready | Already have it |
| Git | ✅ Installed | ✅ Ready | Already have it |
| pnpm | ❌ Not installed | 🟡 Easy fix | npm install -g pnpm or corepack enable |
| Enterprise GitHub access | ✅ ssutheesh_microsoft |
✅ Ready | Can access gim-home/m repo |
| 1JS npm feed | ❓ Need to test | 🟡 Unknown | Internal Microsoft npm feed — needs one-time browser auth |
| Copilot license | ✅ Active | ✅ Ready | Same license works with SDK |
| Windows Terminal | ✅ Your primary | ✅ Ready | All commands run here |
| Microsoft Edge | ✅ Pre-installed | ✅ Ready | Required for Playwright browser automation |
| Disk space | Need ~2 GB | ❓ Check | For node_modules + build output |
| RAM | Need ~500 MB free | ❓ Check | Electron apps use more memory |
| Admin rights | Needed for install | ❓ Check | pnpm global install may need it |
| Intune/Corp policies | ❓ Unknown | ⚠️ Risk | Corp policies might block unsigned Electron apps |
Potential Corp Laptop Blockers¶
| Risk | Severity | What Could Happen | Mitigation |
|---|---|---|---|
| Intune app control | ⚠️ Medium | Corp policy might block unsigned .exe | Run in dev mode (electron:dev) instead of installing |
| Firewall/proxy | ⚠️ Medium | npm/pnpm might not reach 1JS feed | Use VPN or configure proxy in .npmrc |
| Disk encryption overhead | 🟡 Low | BitLocker can slow build process | Just takes longer, still works |
| Antivirus scanning | 🟡 Low | Windows Defender might scan node_modules | Add exclusion for project folder |
| Port 5173 blocked | 🟡 Low | Vite dev server port might be in use | Can change port in config |
💡 Tip: The safest approach is to run Clawpilot in dev mode (
pnpm run electron:dev) rather than building a full installer. Dev mode doesn't install anything system-wide — it just runs from the project folder.
⚠️ Things to Watch Out For¶
Before You Start¶
| Watch Out | Why | What To Do |
|---|---|---|
| It's pre-release (v0.20.x) | Features may change or break between updates | Expect rough edges — this isn't a finished product |
| Internal only | Not publicly available — don't share outside Microsoft | Keep it on corp devices, don't demo to external audiences without checking |
| 1JS feed dependency | Some packages come from Microsoft's private npm feed | If feed is down or auth expires, pnpm install will fail |
| Copilot SDK changes | The SDK is also pre-release and evolving | Updates to the repo might require SDK version bumps |
| No auto-update | Unlike Copilot CLI, there's no npm update |
You must manually git pull and rebuild |
During Use¶
| Watch Out | Why | What To Do |
|---|---|---|
| Memory usage | Electron + Chromium + Node.js = ~400-500 MB | Close when not using; don't leave running all day |
| Browser automation risks | Playwright can interact with real websites | Be careful with auto-approve; watch what URLs it visits |
| Permission fatigue | If you auto-approve everything, safety is reduced | Keep Tier 2/3 prompts ON for writes and shell commands |
| Session data on disk | Chat history saved to ~/.copilot/m-sessions/ |
Contains your conversations — treat as sensitive data |
| M365 auth tokens | MSAL cache at ~/.copilot/m-auth/ |
Contains your M365 tokens — don't share this folder |
| Shared config folder | Both CLI and Clawpilot use ~/.copilot/ |
Changes to config.json affect both tools |
After Updates¶
| Watch Out | Why | What To Do |
|---|---|---|
| Breaking changes | Pre-release software can change APIs between versions | Read the commit log before pulling (git log --oneline -20) |
| Dependency changes | New packages might be added or removed | Always run pnpm install after git pull |
| Skill format changes | SKILL.md format might evolve | Check if your custom skills still work after updating |
| Settings reset | Rare, but possible during major updates | Back up ~/.copilot/m-settings.json before updating |
Data Locations (Where Everything Lives)¶
| What | Path | Shared with CLI? |
|---|---|---|
| Sessions (chat history) | ~/.copilot/m-sessions/ |
❌ Clawpilot only |
| Settings | ~/.copilot/m-settings.json |
❌ Clawpilot only |
| GitHub auth | ~/.copilot/config.json |
✅ Shared |
| M365 auth (MSAL) | ~/.copilot/m-auth/msal-cache.json |
❌ Clawpilot only |
| CLI logs | ~/.copilot/logs/ |
✅ Shared |
| Heartbeat settings | <userData>/heartbeat/settings.json |
❌ Clawpilot only |
| Local skills | workspace/.github/skills/ |
❌ Clawpilot only |
| Global skills | ~/.copilot/skills/ |
❌ Clawpilot only |
| Custom instructions | ~/.copilot/copilot-instructions.md |
✅ Shared |
Available Personalities 🎭¶
One of Clawpilot's fun features — you can change your AI's personality!
| Personality | Emoji | Style | Best For |
|---|---|---|---|
| Default | 🤖 | Helpful, professional | Everyday tasks |
| TARS | 🛸 | Dry wit from Interstellar | Fun conversations |
| Sarcastic Teenager | 🙄 | Eye-rolling, reluctantly helpful | Entertainment |
| Enthusiastic Intern | 🤩 | SO excited about EVERYTHING | When you need energy |
| David Attenborough | 🎬 | Nature documentary narrator | Creative writing |
| JARVIS | ⚡ | Tony Stark's AI — polished, formal | Professional demos |
| Marvin | 😮💨 | Depressed genius from Hitchhiker's Guide | Comedy |
Pros & Cons (Updated)¶
✅ Why Do This¶
- Beautiful GUI — Visual chat interface, no terminal needed
- Browser automation — Navigate websites, fill forms, take screenshots automatically
- Office document creation — Create Word docs, PowerPoint decks, Excel sheets from natural language
- Same AI engine — Uses the same Copilot SDK, identical AI quality
- WorkIQ built-in — Same M365 integration you already have
- Skills system + Marketplace — Extensible with custom/shared automation skills
- Tiered permissions — Safer than CLI's permission model (visual dialogs, read-only auto-approve)
- Multiple sessions — Up to 10 concurrent conversations (CLI has 1)
- Personality presets — Fun and practical AI personality customisation
- Background tasks — Heartbeat system for scheduled automation
- Image support — Attach and view images in chat
- Learning value — Great way to learn Electron, React, TypeScript, modern web dev
- Demo value — Visual demos are more impactful than terminal demos for customers
❌ Challenges¶
- Not publicly released — Internal pre-release (v0.20.x), build from source
- Internal 1JS feed — Requires enterprise npm feed authentication
- Heavier on resources — Electron app uses ~400-500 MB RAM (CLI uses ~50-100 MB)
- Setup complexity — More steps than
npm install -g @anthropic-ai/copilot-cli - Manual updates — Need to
git pulland rebuild (no auto-update) - Two systems to manage — Runs alongside Copilot CLI, not a replacement
- No Azure MCP tools — Unlike CLI, no built-in Azure resource management
- No M365 admin tools — Unlike CLI, no Graph MCP server for tenant admin
- Corp policy risk — Unsigned Electron app might be blocked by Intune
- Shared config — Both tools share
~/.copilot/folder — potential conflicts
Setup Steps (Detailed)¶
Prerequisites Check¶
# Check Node.js version (need 20+)
node --version
# Check git
git --version
# Check if pnpm is installed
pnpm --version
Installation¶
Phase 1: Clone & Setup
─────────────────────────────────────────────────────────
Step 1: Install pnpm (if not already installed)
corepack enable
— OR —
npm install -g pnpm
Step 2: Clone the repository
cd C:\ssClawy
git clone https://github.com/gim-home/m.git clawpilot
cd clawpilot
Step 3: Authenticate with 1JS feed (one-time, opens browser)
pnpm run auth:1js
→ Sign in with your Microsoft account when the browser opens
→ This writes tokens to ~/.npmrc
Phase 2: Install & Build
─────────────────────────────────────────────────────────
Step 4: Install dependencies
pnpm install
→ This also fetches platform-specific Copilot CLI binaries
→ And patches WorkIQ for Windows (no console popups)
Step 5: Build the bundled skills
pnpm run prebuild:skills
Phase 3: First Launch
─────────────────────────────────────────────────────────
Step 6: Run in Electron dev mode
pnpm run electron:dev
→ Builds with Vite, then launches the Electron app
→ First time: you'll see the Auth Screen
Step 7: Sign in with GitHub
→ Click "Sign in with GitHub"
→ Copy the device code shown
→ Enter it at https://github.com/login/device
→ App will auto-detect authentication
Phase 4 (Optional): Build Windows Installer
─────────────────────────────────────────────────────────
Step 8: Build installer
pnpm run build
→ Creates: release/<version>/Clawpilot-Windows-<version>-Setup.exe
How to Update Clawpilot¶
Update Script (Quick Method)¶
# Navigate to the clawpilot folder
cd C:\ssClawy\clawpilot
# Pull latest changes, reinstall, rebuild, launch
git pull && pnpm install && pnpm run prebuild:skills && pnpm run electron:dev
Before Updating (Safety Check)¶
# See what changed since your last pull
cd C:\ssClawy\clawpilot
git log --oneline -20
# Check the current version
node -e "console.log(require('./package.json').version)"
Changelog¶
This section tracks every time we update Clawpilot. After each
git pull, record what changed.
| Date | From Version | To Version | Notable Changes | Issues? |
|---|---|---|---|---|
| 2026-03-29 | — | 0.20.50 | Initial clone and setup | — |
How to Check What Changed¶
# After git pull, see what's new
cd C:\ssClawy\clawpilot
git log --oneline --since="2026-03-29"
# See which files changed
git diff HEAD~10 --stat
# Check version bump
node -e "console.log(require('./package.json').version)"
Key Files Reference¶
| File | Purpose | Importance |
|---|---|---|
electron/main.ts |
All IPC handlers, window creation, permissions | 🔴 Core |
electron/sessions.ts |
SessionManager — SDK lifecycle, MCP config, persistence | 🔴 Core |
electron/preload.cjs |
Bridge: 8 API namespaces exposed to renderer | 🔴 Core |
shared/ipc-contract.ts |
Single source of truth for all IPC types | 🔴 Core |
src/App.tsx |
Root: auth flow, session init, panel state | 🟡 Important |
src/components/ChatPanel.tsx |
Main chat UI (largest component) | 🟡 Important |
electron-builder.json5 |
Electron packager config (NSIS/DMG/AppImage) | 🟡 Important |
package.json |
Dependencies, scripts, version | 🟡 Important |
workspace/ |
Default workspace for MCP file access | 🟢 Reference |
Repository Structure¶
clawpilot/
├── electron/ # Main process (Node.js) — "the kitchen"
│ ├── main.ts # Window creation, IPC handlers, app lifecycle
│ ├── sessions.ts # SessionManager — AI lifecycle, MCP config
│ ├── preload.cjs # Bridge between UI and engine
│ ├── skills.ts # Custom skill loading, SKILL.md parsing
│ ├── heartbeat.ts # Background task scheduler
│ ├── permissions-dialog.ts # Permission UI formatting
│ ├── permission-policy.ts # Safety rules (read-only detection)
│ └── auth/ # Authentication (MSAL, WAM)
│
├── src/ # Renderer process (React) — "the dining room"
│ ├── App.tsx # Root component
│ ├── components/ # UI components (ChatPanel, Header, etc.)
│ ├── services/ # SDK wrapper, marketplace utilities
│ └── types/ # TypeScript type definitions
│
├── shared/ # Shared between main & renderer
│ └── ipc-contract.ts # All IPC type definitions
│
├── sidecar/ # Windows-only helpers
│ └── node-runner.exe # Windowless Node.js spawner for MCP
│
├── first-party-skills/ # Built-in skills (docx, pptx, xlsx)
├── workspace/ # Default workspace for file access
├── docs/architecture/ # Detailed architecture documentation
└── package.json # Dependencies, scripts, version
Benefits¶
- 🎥 YouTube content — "AI Desktop Assistant that controls your browser and creates Office docs" would be a great video
- 🎓 Learning — Hands-on with Electron, React, TypeScript, modern web dev stack
- 💼 Demo value — Visual demos are more impactful than terminal demos for customers
- 🔧 Productivity — Browser automation + Office doc creation could save real time
- 🧪 Experimentation — Test bleeding-edge Copilot SDK features before they're mainstream
Started: 2026-03-29 · Status: 🔄 In Progress