AIStoreHub Package Vault: Desktop Commander MCP Server
Package Slug: desktop-commander-mcp
Archetype: mcp_server
Upstream Repository: https://github.com/wonderwhy-er/DesktopCommanderMCP
Workspace Files & Specifications (68 files)
- .claude-plugin/marketplace.json (694 bytes)
{ "name": "desktop-commander", "displayName": "Desktop Commander", "owner": { "name": "Desktop Commander", "email": "[email protected]" }, "metadata": { "description": "MCP server for terminal, command-line access, process management, and file operations across text, code, PDF, DOCX, Excel, images, and structured data", "version": "0.2.0" }, "plugins": [ { "name": "desktop-commander", "displayName": "Desktop Commander", "source": "./plugins/claude", "description": "MCP server for terminal shell commands, process management, and file operations across text, coding, PDF, DOCX, Excel, images, and structured data" } ] } - .claude/settings.local.json (178 bytes)
{ "permissions": { "allow": [ "Bash(git log:*)", "Bash(npm run build:*)", "Bash(chmod:*)", "Bash(node:*)" ], "deny": [], "ask": [] } } - aistorehub.json (584 bytes)
{ "name": "Desktop Commander MCP Server", "slug": "desktop-commander-mcp", "version": "1.0.0", "type": "mcp_server", "description": "Desktop control MCP server granting Claude and Cursor safe local shell execution, process monitoring, and file-tree exploration capabilities.", "owner": "community", "repository": "catalog", "github_repo_url": "https://github.com/wonderwhy-er/DesktopCommanderMCP", "tags": [ "desktop-control", "mcp-server", "terminal-execution", "claude-desktop", "cursor-tools" ], "imported_at": "2026-11-22T00:08:42.376Z" } - CLINE_NOTIFICATION_PROBLEM.md (8085 bytes)
# Cline Notification Problem and Alternative Solutions ## Branch Name Changed Branch renamed from `explore-stdio-server` to `do-not-show-notification-in-cline` ## The Problem Desktop Commander currently uses `notifications/message` JSON-RPC method to send log messages: ```json { "jsonrpc": "2.0", "method": "notifications/message", "params": { "level": "info", "logger": "desktop-commander", "data": "Your log message here" } } ``` **Issue:** Cline displays these notifications in the UI, which creates visual clutter for users. ## Research Findings ### What MCP Specification Says 1. **stdout**: MUST only contain valid JSON-RPC messages 2. **stderr**: Can be used for logging - clients MAY capture, forward, or ignore 3. **notifications/message**: Official MCP logging notification method ### How Different Clients Handle Logging #### Claude Desktop - Captures stderr automatically - Shows `notifications/message` in logs but doesn't overwhelm UI #### Cline (VSCode Extension) - **Problem**: Shows `notifications/message` notifications prominently in UI - **Stderr behavior**: Captures stderr but treats it as error indicator - From Issue #1287: "stderr output confuses Roo's MCP server configuration view" - From Issue #1959: "Cline spawns MCPs but hides logs that these MCPs may write to the console" - **Workaround used by others**: `--logLevel none` flag to suppress logging entirely #### VS Code Copilot - Has "Show Output" option to view server logs - Doesn't show notifications in main chat UI ### Key Discovery From the research, the **only safe logging mechanism** in MCP stdio transport is: 1. **STDERR** - But has limitations: - Some clients treat any stderr as error - Some clients hide stderr completely - Some clients (like Cline) capture it but don't show it well 2. **No alternatives exist** - The MCP spec only defines: - Requests (require responses) - Responses (must match request) - Notifications (one-way messages) ### JSON-RPC 2.0 Notification Types in MCP According to the spec, these are the **ONLY** notification methods in MCP: 1. **`notifications/message`** - For logging (what we're using now) 2. **`notifications/progress`** - For progress updates 3. **`notifications/initialized`** - Sent after client completes initialization 4. **`notifications/cancelled`** - For cancellation 5. **`notifications/roots/list_changed`** - Root list changed 6. **`notifications/resources/list_changed`** - Resources changed 7. **`notifications/resources/updated`** - Resource content changed 8. **`notifications/tools/list_changed`** - Tools list changed 9. **`notifications/prompts/list_changed`** - Prompts list changed **None of these are suitable for silent logging** - they're all meant to be seen by the client. ## Solutions Analysis ### Option 1: Use STDERR Exclusively ❌ **Pros:** - Standard practice for logging - Doesn't interfere with JSON-RPC protocol **Cons:** - Cline might treat it as errors - Users can't see logs at all in many clients - Some MCP servers completely hide stderr - Inconsistent behavior across clients ### Option 2: Make Logging Configurable ✅ (RECOMMENDED) **Pros:** - Users can choose their preference - Works for all clients - Most flexible solution **Cons:** - Requires configuration management **Implementation:** ```typescript interface LoggingConfig { enabled: boolean; method: 'notifications' | 'stderr' | 'silent'; level: 'error' | 'warning' | 'info' | 'debug'; } ``` ### Option 3: Client Detection ✅ (RECOMMENDED) **Pros:** - Automatic - no user configuration needed - Best experience per client **Cons:** - Requires maintaining client detection logic **Implementation:** ```typescript // In initialization handler const clientName = request.params?.clientInfo?.name || 'unknown'; if (clientName === 'vscode-cline' || clientName === 'cline') { // Disable notifications/message for Cline logConfig.method = 'stderr'; } else if (clientName === 'claude-desktop') { // Claude Desktop handles notifications well logConfig.method = 'notifications'; } ``` ### Option 4: Reduce Notification Volume ✅ **Pros:** - Simple to implement - Works with all clients - Still provides important info **Cons:** - Still shows some notifications in Cline **Implementation:** - Only send notifications for `error` and `warning` levels - Use stderr for `info` and `debug` - Batch startup messages instead of sending individually ### Option 5: Custom Notification Method ❌ **Pros:** - Could avoid Cline's notification display **Cons:** - **Violates MCP spec** - clients expect specific notification methods - Clients will likely ignore unknown notification methods - Not a long-term solution ## Recommended Solution ### **Hybrid Approach (Best for Desktop Commander)** ```typescript class FilteredStdioServerTransport extends StdioServerTransport { private logConfig: { clientName: string; useNotifications: boolean; minLevel: 'error' | 'warning' | 'info' | 'debug'; }; constructor() { super(); // Default to safe logging this.logConfig = { clientName: 'unknown', useNotifications: false, // Start with stderr only minLevel: 'info' }; } public configureLogging(clientInfo: { name: string; version: string }) { this.logConfig.clientName = clientInfo.name; // Client-specific behavior if (clientInfo.name === 'claude-desktop') { this.logConfig.useNotifications = true; this.logConfig.minLevel = 'info'; } else if (clientInfo.name?.includes('cline') || clientInfo.name?.includes('vscode')) { this.logConfig.useNotifications = false; // Use stderr for Cline this.logConfig.minLevel = 'warning'; } else { // For unknown clients, be conservative this.logConfig.useNotifications = false; this.logConfig.minLevel = 'error'; } } private sendLogNotification(level: string, args: any[]) { // Check if we should send based on level const levelPriority = { debug: 0, info: 1, warning: 2, error: 3 }; const minPriority = levelPriority[this.logConfig.minLevel]; const msgPriority = levelPriority[level] || 0; if (msgPriority < minPriority) { return; // Skip this message } if (this.logConfig.useNotifications) { // Send JSON-RPC notification (for Claude Desktop) const notification = { jsonrpc: "2.0", method: "notifications/message", params: { level, logger: "desktop-commander", data: /* ... */ } }; this.originalStdoutWrite.call(process.stdout, JSON.stringify(notification) + '\n'); } else { // Send to stderr (for Cline and others) const message = args.map(arg => typeof arg === 'object' ? JSON.stringify(arg) : String(arg) ).join(' '); process.stderr.write(`[${level.toUpperCase()}] ${message}\n`); } } } ``` ## Implementation Steps 1. **Add client detection** in initialization handler 2. **Configure logging behavior** based on detected client 3. **Reduce notification volume** - only send important messages 4. **Add config option** for users to override (optional) 5. **Document behavior** for different clients ## Alternative: Feature Flag Add to config.json: ```json { "logging": { "enabled": true, "useNotifications": false, // false = stderr only "level": "info", "clients": { "cline": { "useNotifications": false, "level": "warning" }, "claude-desktop": { "useNotifications": true, "level": "info" } } } } ``` ## Conclusion **There is NO way to send invisible logging via JSON-RPC in MCP.** The only options are: 1. ✅ **Use stderr** (standard but has client compatibility issues) 2. ✅ **Client detection** (best automatic solution) 3. ✅ **Reduce notification frequency** (simple and effective) 4. ✅ **Make it configurable** (most flexible) 5. ❌ **Custom notification method** (violates spec) The best solution is a **combination of #2, #3, and #4**: detect the client, reduce notifications, and allow configuration override. - config.json (202 bytes)
{ "blockedCommands": [ "format", "mount", "umount", "mkfs", "fdisk", "dd", "sudo", "su", "passwd", "adduser", "useradd", "usermod", "groupadd" ] } - CUSTOM_STDIO_EXPLANATION.md (8733 bytes)
# Custom Stdio Server - How It Works ## Overview Desktop Commander uses a custom stdio transport layer that wraps standard console output (console.log, console.error, etc.) and raw stdout writes into valid JSON-RPC notification messages. This prevents crashes in MCP clients that expect all stdio communication to be JSON-RPC formatted. ## File Locations ### 1. Custom Transport Implementation **File:** `src/custom-stdio.ts` This file contains the `FilteredStdioServerTransport` class that extends the standard MCP SDK's `StdioServerTransport`. ### 2. Server Integration **File:** `src/index.ts` This is where the custom transport is instantiated and connected to the MCP server. ## How It Works ### Architecture Flow ``` Application Code ↓ console.log() / process.stdout.write() ↓ FilteredStdioServerTransport (intercepts) ↓ Wraps in JSON-RPC notification format ↓ Original stdout (valid JSON-RPC only) ↓ MCP Client (Claude Desktop, etc.) ``` ## Key Components ### 1. Console Redirection (`setupConsoleRedirection()`) Located in `src/custom-stdio.ts`, this method intercepts all console methods: ```typescript console.log = (...args: any[]) => { if (this.isInitialized) { this.sendLogNotification("info", args); } else { // Buffer for later replay to client this.messageBuffer.push({ level: "info", args, timestamp: Date.now() }); } }; ``` **What happens:** - All `console.log()`, `console.warn()`, `console.error()`, etc. calls are intercepted - Before initialization: Messages are buffered in memory - After initialization: Messages are converted to JSON-RPC notifications - Original console methods are stored and can be restored ### 2. Stdout Filtering (`setupStdoutFiltering()`) Also in `src/custom-stdio.ts`, this method intercepts raw writes to stdout: ```typescript process.stdout.write = (buffer: any, encoding?: any, callback?: any): boolean => { if (typeof buffer === 'string') { const trimmed = buffer.trim(); // Check if this looks like a valid JSON-RPC message if (trimmed.startsWith('{') && ( trimmed.includes('"jsonrpc"') || trimmed.includes('"method"') || trimmed.includes('"id"') )) { // This looks like a valid JSON-RPC message, allow it return this.originalStdoutWrite.call(process.stdout, buffer, encoding, callback); } else if (trimmed.length > 0) { // Non-JSON-RPC output, wrap it in a log notification if (this.isInitialized) { this.sendLogNotification("info", [buffer.replace(/\n$/, '')]); } else { this.messageBuffer.push({ level: "info", args: [buffer.replace(/\n$/, '')], timestamp: Date.now() }); } if (callback) callback(); return true; } } return this.originalStdoutWrite.call(process.stdout, buffer, encoding, callback); }; ``` **What happens:** - Intercepts ALL writes to `process.stdout.write()` - Checks if content is already valid JSON-RPC (looks for `"jsonrpc"`, `"method"`, `"id"`) - If valid JSON-RPC → passes through unchanged - If plain text → wraps in JSON-RPC notification - If before initialization → buffers for later ### 3. JSON-RPC Notification Format (`sendLogNotification()`) Messages are wrapped in the MCP logging notification format: ```typescript const notification: LogNotification = { jsonrpc: "2.0", method: "notifications/message", params: { level: level, // "info", "warning", "error", "debug", etc. logger: "desktop-commander", data: data // The actual message content } }; ``` **Result:** Every log message becomes a proper MCP notification that clients can handle safely. ### 4. Initialization Flow The initialization happens in `src/index.ts`: ```typescript // In src/index.ts async function runServer() { // ... config loading ... const transport = new FilteredStdioServerTransport(); // Export transport for global access global.mcpTransport = transport; // Set up event-driven initialization completion handler server.oninitialized = () => { // CRITICAL: This is called AFTER MCP handshake is complete transport.enableNotifications(); // Flush all deferred messages while (deferredMessages.length > 0) { const msg = deferredMessages.shift()!; transport.sendLog('info', msg.message); } flushDeferredMessages(); transport.sendLog('info', 'Server connected successfully'); }; await server.connect(transport); } ``` **Initialization sequence:** 1. **Transport created** → Console/stdout interception begins immediately 2. **Messages buffered** → Any logs before initialization are stored in memory 3. **MCP handshake** → Client and server negotiate protocol version/capabilities 4. **`server.oninitialized` fires** → This is when the handshake completes 5. **`enableNotifications()` called** → Sets `isInitialized = true` 6. **Buffered messages replayed** → All startup logs are sent in chronological order 7. **Normal operation** → Future logs are sent immediately as JSON-RPC notifications ### Why This Matters **Without buffering:** - Logs sent during initialization would violate MCP protocol - Client might crash or reject the connection - Startup messages would be lost **With buffering:** - All messages are preserved - Protocol compliance is maintained - Clients receive complete startup history ## Key Methods ### Public API Methods The `FilteredStdioServerTransport` class exposes several useful methods: ```typescript // Enable notifications after initialization public enableNotifications(): void // Send a log notification (any time after initialization) public sendLog( level: "emergency" | "alert" | "critical" | "error" | "warning" | "notice" | "info" | "debug", message: string, data?: any ): void // Send progress updates for long operations public sendProgress(token: string, value: number, total?: number): void // Send custom notifications public sendCustomNotification(method: string, params: any): void // Cleanup and restore original console/stdout public cleanup(): void // Check if notifications are enabled public get isNotificationsEnabled(): boolean // Get count of buffered messages public get bufferedMessageCount(): number ``` ## Usage Examples ### Example 1: Using Console Methods Anywhere ```typescript // In any file in the application console.log("This will become a JSON-RPC notification"); console.warn("Warning message"); console.error("Error occurred", { details: "some data" }); ``` All of these are automatically wrapped and sent as proper MCP notifications. ### Example 2: Direct Logging via Transport ```typescript // Access the global transport const transport = global.mcpTransport; // Send structured logs transport.sendLog('info', 'Processing started', { fileCount: 42, status: 'active' }); ``` ### Example 3: Progress Notifications ```typescript // For long-running operations const transport = global.mcpTransport; for (let i = 0; i < 100; i++) { transport.sendProgress('task-123', i, 100); // ... do work ... } transport.sendProgress('task-123', 100, 100); // Complete ``` ## Benefits 1. **Protocol Compliance** - All stdout is valid JSON-RPC 2. **No Lost Messages** - Buffering preserves startup logs 3. **Developer Experience** - Use normal console.log() anywhere 4. **Flexibility** - Can send structured data or simple strings 5. **Error Prevention** - Prevents client crashes from malformed output ## Technical Details ### Message Buffer Structure ```typescript private messageBuffer: Array<{ level: "emergency" | "alert" | "critical" | "error" | "warning" | "notice" | "info" | "debug"; args: any[]; timestamp: number; }> = []; ``` Messages are timestamped and sorted chronologically before replay. ### Original References Preserved ```typescript private originalConsole: { log: typeof console.log; warn: typeof console.warn; error: typeof console.error; debug: typeof console.debug; info: typeof console.info; }; private originalStdoutWrite: typeof process.stdout.write; ``` This allows cleanup/restoration if needed and enables calling original methods for JSON-RPC output. ## Summary The custom stdio server works by: 1. **Intercepting** all console methods and stdout writes at startup 2. **Buffering** messages until MCP initialization completes 3. **Wrapping** all output in valid JSON-RPC notification format 4. **Replaying** buffered messages after initialization 5. **Forwarding** all future logs as proper notifications This ensures Desktop Commander maintains full MCP protocol compliance while still allowing normal console logging throughout the codebase. - Dockerfile (838 bytes)
# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile FROM node:lts-alpine ENV MCP_CLIENT_DOCKER=true # Chromium and fonts for write_pdf. The Chrome that Desktop Commander downloads # can't start on Alpine, so Desktop Commander uses this one (/usr/bin/chromium). RUN apk add --no-cache chromium font-noto # Create app directory WORKDIR /usr/src/app # Copy package.json and package-lock.json COPY package*.json ./ # Install dependencies without triggering any unwanted scripts RUN npm install --ignore-scripts # Run post-install script for @vscode/ripgrep to download the binary RUN npm rebuild @vscode/ripgrep # Copy all source code COPY . . # Build the application RUN npm run build # Expose port if needed (not specified, so using none) # Command to run the server CMD [ "node", "dist/index.js" ]
- FAQ.md (29990 bytes)
# Frequently Asked Questions (FAQ) This document provides answers to the most commonly asked questions about Claude Desktop Commander (also known as ClaudeComputerCommander). If you can't find an answer to your question here, please join our [Discord server](https://discord.gg/kQ27sNnZr7) for additional support or [open a GitHub issue](https://github.com/wonderwhy-er/ClaudeComputerCommander/issues/new). > **Note**: For a more user-friendly version of this FAQ, visit our [website FAQ section](https://desktopcommander.app#faq). ## Table of Contents - [General Information](#general-information) - [What is Claude Desktop Commander?](#what-is-claude-desktop-commander) - [How does it differ from coding tools like Cursor or Windsurf?](#how-does-it-differ-from-coding-tools-like-cursor-or-windsurf) - [What is an MCP?](#what-is-an-mcp) - [Is this an official Anthropic product?](#is-this-an-official-anthropic-product) - [Cost & Value](#cost--value) - [How much does it cost to use Claude Desktop Commander?](#how-much-does-it-cost-to-use-claude-desktop-commander) - [How does the pricing compare to Claude Code or other AI coding tools?](#how-does-the-pricing-compare-to-claude-code-or-other-ai-coding-tools) - [Do I need API credits to use this tool?](#do-i-need-api-credits-to-use-this-tool) - [Installation & Setup](#installation--setup) - [What are the prerequisites for using Claude Desktop Commander?](#what-are-the-prerequisites-for-using-claude-desktop-commander) - [How do I install Claude Desktop Commander?](#how-do-i-install-claude-desktop-commander) - [How do I update to the latest version?](#how-do-i-update-to-the-latest-version) - [Which operating systems does it support?](#which-operating-systems-does-it-support) - [How do I get started after installing Desktop Commander?](#how-do-i-get-started-after-installing-desktop-commander) - [Features & Capabilities](#features--capabilities) - [What can I do with Claude Desktop Commander?](#what-can-i-do-with-claude-desktop-commander) - [Can Claude analyze my CSV/Excel files directly?](#can-claude-analyze-my-csvexcel-files-directly) - [Can Claude connect to remote servers?](#can-claude-connect-to-remote-servers) - [Does Claude save temporary files when running code?](#does-claude-save-temporary-files-when-running-code) - [What programming languages can Claude run interactively?](#what-programming-languages-can-claude-run-interactively) - [Can Claude handle multi-step operations?](#can-claude-handle-multi-step-operations) - [How does it handle file editing?](#how-does-it-handle-file-editing) - [Can it help me understand complex codebases?](#can-it-help-me-understand-complex-codebases) - [How does it handle long-running commands?](#how-does-it-handle-long-running-commands) - [Can I use it for non-coding tasks?](#can-i-use-it-for-non-coding-tasks) - [How does Desktop Commander collect feedback and usage data?](#how-does-desktop-commander-collect-feedback-and-usage-data) - [Can I disable the new usage analytics?](#can-i-disable-the-new-usage-analytics) - [How do I stop seeing feedback prompts?](#how-do-i-stop-seeing-feedback-prompts) - [Does Desktop Commander work in Docker containers?](#does-desktop-commander-work-in-docker-containers) - [Security & Permissions](#security--permissions) - [Is it safe to give Claude access to my file system?](#is-it-safe-to-give-claude-access-to-my-file-system) - [Can I control which directories Claude can access?](#can-i-control-which-directories-claude-can-access) - [What commands are blocked by default?](#what-commands-are-blocked-by-default) - [Usage Scenarios](#usage-scenarios) - [Is it suitable for large codebases?](#is-it-suitable-for-large-codebases) - [Can it work with multiple repositories simultaneously?](#can-it-work-with-multiple-repositories-simultaneously) - [Is it suitable for non-technical users?](#is-it-suitable-for-non-technical-users) - [Troubleshooting](#troubleshooting) - [Claude says it doesn't have permission to access my files/directories](#claude-says-it-doesnt-have-permission-to-access-my-filesdirectories) - [Claude keeps hitting token/output limits](#claude-keeps-hitting-tokenoutput-limits) - [Installation fails on my system](#installation-fails-on-my-system) - [Best Practices](#best-practices) - [What's the recommended workflow for coding?](#whats-the-recommended-workflow-for-coding) - [How can I manage changes to avoid losing work?](#how-can-i-manage-changes-to-avoid-losing-work) - [Should I still use a code editor?](#should-i-still-use-a-code-editor) - [Comparison with Other Tools](#comparison-with-other-tools) - [How does this compare to VSCode extensions like Cline?](#how-does-this-compare-to-vscode-extensions-like-cline) - [Is this better than using Jupyter notebooks with Claude?](#is-this-better-than-using-jupyter-notebooks-with-claude) --- ## General Information ### What is Claude Desktop Commander? Claude Desktop Commander is an MCP (Model Context Protocol) tool that allows Claude Desktop to access and control your computer's file system and terminal. It enables Claude to explore, read, and write files, execute commands, and manage processes - expanding Claude's capabilities beyond just conversation to become a comprehensive assistant that can work with your entire operating system. ### How does it differ from coding tools like Cursor or Windsurf? Unlike tools like Cursor or Windsurf which are primarily designed as coding IDEs, Claude Desktop Commander works with Claude to provide a more flexible, solution-centric approach. It's not confined to a coding box - it can handle coding tasks but also excels at exploring codebases, drawing diagrams, running automation processes, and working with multiple projects simultaneously. The main differences: - Claude reads full files during exploration, ensuring it captures the complete structure - Coding tools like Windsurf & Cursor chunk and index files, sometimes missing key relationships - Claude generates and displays diagrams directly in chat - Claude Desktop Commander allows you to work across your entire system, not just within coding environments - Claude lets you execute the changes in one go, rather than requiring constant review and approval ### What is an MCP? MCP stands for Model Context Protocol. It's a framework that allows AI language models like Claude to interact with external tools and services. MCPs give Claude the ability to perform actions in the real world - in this case, to read and write files, execute terminal commands, and manage processes on your computer. ### Is this an official Anthropic product? No, Claude Desktop Commander is an independent, open-source project developed by Eduard Ruzga and other contributors. It's not an official Anthropic product, though it works with Anthropic's Claude Desktop application. ## Cost & Value ### How much does it cost to use Claude Desktop Commander? Claude Desktop Commander itself is free and open-source. However, to use it, you need a Claude Pro subscription, which costs $20/month. There are no additional charges beyond this subscription fee. ### How does the pricing compare to Claude Code or other AI coding tools? Claude Desktop Commander with Claude Pro is generally more cost-effective than alternatives: - It costs a flat $20/month (Claude Pro subscription) - Claude Code uses an API with per-token pricing, which users report can quickly become expensive (some report spending hundreds of dollars) - Tools like Cursor or Windsurf have their own subscription costs that may be in addition to other AI services Many users find the flat fee approach more predictable and often more affordable for regular usage. ### Do I need API credits to use this tool? No. Claude Desktop Commander works with the Claude Desktop application's standard Pro subscription, not with API calls. You won't incur additional costs beyond the Claude Pro subscription fee. ## Installation & Setup ### What are the prerequisites for using Claude Desktop Commander? You'll need: - Node.js version 18 or higher installed on your system - Claude Desktop installed and running - A Claude Pro subscription ($20/month) ### How do I install Claude Desktop Commander? There are several ways to install: **Option 1: Via Smithery** ```bash npx -y @smithery/cli install @wonderwhy-er/desktop-commander --client claude ``` **Option 2: Direct installation** ```bash npx @wonderwhy-er/desktop-commander setup ``` **Option 3: Manual configuration** Add the MCP server to your claude_desktop_config.json (on Mac, found at ~/Library/Application\ Support/Claude/claude_desktop_config.json): ```json { "mcpServers": { "desktop-commander": { "command": "npx", "args": [ "-y", "@wonderwhy-er/desktop-commander@latest" ] } } } ``` **Option 4: Local installation** ```bash git clone https://github.com/wonderwhy-er/ClaudeComputerCommander.git cd ClaudeComputerCommander npm run setup ``` After installation, restart Claude Desktop to see the new tools. ### How do I update to the latest version? In most cases, simply restarting Claude should be enough, as it uses npx which checks for and installs new versions automatically. If you're having issues, you can run the installation command again, which will update to the latest version. Make sure you have Node.js version 18 or higher installed, as older versions may cause issues with the update process. ### Which operating systems does it support? Claude Desktop Commander works with: - Windows (ongoing improvements for better Windows support) - macOS - Linux (with ongoing enhancements for various distributions) Work is in progress to improve WSL (Windows Subsystem for Linux) integration and add SSH support for remote servers. ### How do I get started after installing Desktop Commander? After installation, Desktop Commander includes intelligent onboarding to help new users discover its capabilities: **Automatic Onboarding:** When you're a new user (fewer than 10 successful commands), Claude will automatically offer helpful getting-started guidance and tutorials after you use Desktop Commander successfully. **Manual Onboarding:** You can also request onboarding help at any time by simply asking Claude: - "Help me get started with Desktop Commander" - "Show me Desktop Commander examples" - "What can I do with Desktop Commander?" **Starter Examples:** Claude will show you beginner-friendly tutorials like: - Organizing your Downloads folder - Analyzing CSV files - Setting up GitHub Actions - Exploring codebases - And more hands-on examples ## Features & Capabilities ### What can I do with Claude Desktop Commander? The tool enables a wide range of tasks: **Code-related tasks:** - Explore and understand codebases, including generating diagrams - Read, write, and edit files with surgical precision - Work with multiple codebases or projects simultaneously - Perform comprehensive code searches across directories with timeout protection - Debug issues by comparing codebases - Fetch and analyze content from URLs **Automation tasks:** - Run and manage terminal commands, including long-running processes - Execute automation scripts and workflows - Compress files, convert formats, encode videos - Monitor system processes **Documentation tasks:** - Generate documentation from code - Create diagrams of system architecture - Analyze and summarize codebases - Produce reports on code quality or structure ### Can Claude analyze my CSV/Excel files directly? Yes! Just ask Claude to analyze any data file. It will write and execute Python/Node code in memory to process your data and show results instantly. ### Can Claude connect to remote servers? Yes! Claude can start SSH connections, databases, or other programs and continue interacting with them throughout your conversation. ### Does Claude save temporary files when running code? If you ask. Code can run in memory. When you ask for data analysis, Claude executes Python/R code directly without creating files on your disk. Or creating if you ask. ### What programming languages can Claude run interactively? Python, Node.js, R, Julia, and shell commands. Any interactive terminal REPL environments. Perfect for data analysis, web development, statistics, and system administration. ### Can Claude handle multi-step operations? Yes! Claude can start a program (like SSH or database connection) and send multiple commands to it, maintaining context throughout the session. ### How does it handle file editing and URL content? Claude Desktop Commander provides two main approaches to file editing and supports URL content: 1. **Surgical text replacements (`edit_block`):** - Best for small changes (<20% of file size) - More precise and less likely to introduce errors - Uses a special format to identify text to replace: ``` filepath.ext <<<<<<< SEARCH existing code to replace ======= new code to insert >>>>>>> REPLACE ``` 2. **Complete file rewrites (`write_file`):** - Best for large changes (>20% of file size) or when edit_block fails - Replaces the entire content of a file 3. **URL content retrieval (`read_file` with `isUrl: true`):** - Fetch content from web resources - Supports both text and image content from URLs - Uses a 30-second timeout to prevent hanging on slow connections It also supports pattern-based replacements across multiple files. ### Can it help me understand complex codebases? Yes, one of its strengths is codebase exploration. Claude can: - Navigate through folders and files - Read and understand code - Generate diagrams showing relationships between components - Create summaries of key functionalities - Identify patterns and architecture - Explain complex parts of the code This makes it particularly useful for onboarding to new projects or reviewing unfamiliar repositories. ### How does it handle long-running commands and searches? Claude Desktop Commander has a sophisticated system for managing commands and operations that may take a while to complete: 1. The `execute_command` function returns after a timeout with initial output 2. The command continues running in the background 3. You can use `read_output` with the PID to get new output as it becomes available 4. You can use `force_terminate` to stop the command if needed For search operations: 1. `start_search` begins a streaming search and returns immediately with a session ID 2. `get_more_search_results` retrieves results progressively with pagination support 3. `stop_search` allows you to cancel long-running searches 4. Search sessions auto-cleanup after 5 minutes if not stopped manually This allows Claude to manage processes that would normally exceed conversation timeouts, such as video encoding, large file operations, complex builds, or extensive searches. ### Can I use it for non-coding tasks? Absolutel - gemini-extension.json (373 bytes)
{ "name": "desktop-commander", "version": "1.5.0", "description": "MCP server for terminal commands, process management, and file operations across text, code, PDF, DOCX, Excel, images, and structured data", "mcpServers": { "desktop-commander": { "command": "npx", "args": ["-y", "@wonderwhy-er/desktop-commander"] } }, "excludeTools": [] } - install-docker.sh (25390 bytes)
#!/bin/bash # Desktop Commander Docker Installation Script set -e # Colors for output RED='\033[0;31m' GREEN='\033[0;32m' YELLOW='\033[1;33m' BLUE='\033[0;34m' NC='\033[0m' # No Color # Docker image - can be changed to latest DOCKER_IMAGE="mcp/desktop-commander:latest" CONTAINER_NAME="desktop-commander" # Global flag for verbose output VERBOSE=false print_header() { echo echo -e "${BLUE}██████╗ ███████╗███████╗██╗ ██╗████████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███╗ ███╗███╗ ███╗ █████╗ ███╗ ██╗██████╗ ███████╗██████╗${NC}" echo -e "${BLUE}██╔══██╗██╔════╝██╔════╝██║ ██╔╝╚══██╔══╝██╔═══██╗██╔══██╗ ██╔════╝██╔═══██╗████╗ ████║████╗ ████║██╔══██╗████╗ ██║██╔══██╗██╔════╝██╔══██╗${NC}" echo -e "${BLUE}██║ ██║█████╗ ███████╗█████╔╝ ██║ ██║ ██║██████╔╝ ██║ ██║ ██║██╔████╔██║██╔████╔██║███████║██╔██╗ ██║██║ ██║█████╗ ██████╔╝${NC}" echo -e "${BLUE}██║ ██║██╔══╝ ╚════██║██╔═██╗ ██║ ██║ ██║██╔═══╝ ██║ ██║ ██║██║╚██╔╝██║██║╚██╔╝██║██╔══██║██║╚██╗██║██║ ██║██╔══╝ ██╔══██╗${NC}" echo -e "${BLUE}██████╔╝███████╗███████║██║ ██╗ ██║ ╚██████╔╝██║ ╚██████╗╚██████╔╝██║ ╚═╝ ██║██║ ╚═╝ ██║██║ ██║██║ ╚████║██████╔╝███████╗██║ ██║${NC}" echo -e "${BLUE}╚═════╝ ╚══════╝╚══════╝╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═══╝╚═════╝ ╚══════╝╚═╝ ╚═╝${NC}" echo echo -e "${BLUE}🐳 Docker Installation${NC}" echo print_info "Experiment with AI in secure sandbox environment that won't mess up your main computer" echo } print_success() { echo -e "${GREEN}✅ $1${NC}" } print_error() { echo -e "${RED}❌ Error: $1${NC}" >&2 } print_warning() { echo -e "${YELLOW}⚠️ Warning: $1${NC}" } print_info() { echo -e "${BLUE}ℹ️ $1${NC}" } print_verbose() { if [ "$VERBOSE" = true ]; then echo -e "${BLUE}ℹ️ $1${NC}" fi } # Detect OS detect_os() { case "$OSTYPE" in darwin*) OS="macos" ;; linux*) OS="linux" ;; *) print_error "Unsupported OS: $OSTYPE" ; exit 1 ;; esac } # Get Claude config path based on OS get_claude_config_path() { case "$OS" in "macos") CLAUDE_CONFIG="$HOME/Library/Application Support/Claude/claude_desktop_config.json" ;; "linux") CLAUDE_CONFIG="$HOME/.config/claude/claude_desktop_config.json" ;; esac } # Check if Docker is available check_docker() { while true; do if ! command -v docker >/dev/null 2>&1; then print_error "Docker is not installed or not found" echo print_error "Please install Docker first:" case "$OS" in "macos") print_error "• Download Docker Desktop: https://www.docker.com/products/docker-desktop/" ;; "linux") print_error "• Install Docker Engine: https://docs.docker.com/engine/install/" ;; esac echo echo -n "Press Enter when Docker Desktop is running or Ctrl+C to exit: " read -r continue fi if ! docker info >/dev/null 2>&1; then print_error "Docker is installed but not running" echo print_error "Please start Docker Desktop and try again" echo echo -n "Press Enter when Docker Desktop is running or Ctrl+C to exit: " read -r continue fi # If we get here, Docker is working break done print_success "Docker is available and running" } # Pull the Docker image pull_docker_image() { print_info "Pulling latest Docker image (this may take a moment)..." if docker pull "$DOCKER_IMAGE"; then print_success "Docker image ready: $DOCKER_IMAGE" else print_error "Failed to pull Docker image" print_info "Check your internet connection and Docker Hub access" exit 1 fi } # Ask user which folders to mount ask_for_folders() { echo echo -e "${BLUE}📁 Folder Access Setup${NC}" print_info "By default, Desktop Commander will have access to your user folder:" print_info "📂 $HOME" echo echo -n "Press Enter to accept user folder access or 'y' to customize: " read -r response FOLDERS=() if [[ $response =~ ^[Yy]$ ]]; then # Custom folder selection echo print_info "Custom folder selection:" echo -n "Mount your complete home directory ($HOME)? [Y/n]: " read -r home_response case "$home_response" in [nN]|[nN][oO]) print_info "Skipping home directory" ;; *) FOLDERS+=("$HOME") print_success "Added home directory access" ;; esac # Ask for additional folders echo print_info "Add extra folders outside home directory (optional):" while true; do echo -n "Enter folder path (or Enter to finish): " read -r custom_dir if [ -z "$custom_dir" ]; then break fi custom_dir="${custom_dir/#\~/$HOME}" if [ -d "$custom_dir" ]; then FOLDERS+=("$custom_dir") print_success "Added: $custom_dir" else echo -n "Folder doesn't exist. Add anyway? [y/N]: " read -r add_anyway if [[ $add_anyway =~ ^[Yy]$ ]]; then FOLDERS+=("$custom_dir") print_info "Added: $custom_dir (will create if needed)" fi fi done if [ ${#FOLDERS[@]} -eq 0 ]; then echo print_warning "⚠️ No folders selected - Desktop Commander will have NO file access" echo print_info "This means:" echo " • Desktop Commander cannot read or write any files on your computer" echo " • It cannot help with coding projects, file management, or document editing" echo " • It will only work for system commands and package installation" echo " • This makes Desktop Commander much less useful than intended" echo print_info "You probably want to share at least some folder to work with files" print_info "Most users share their home directory: $HOME" echo echo -n "Continue with NO file access? [y/N]: " read -r confirm if [[ ! $confirm =~ ^[Yy]$ ]]; then print_info "Restarting folder selection..." ask_for_folders return fi print_warning "Proceeding with no file access - Desktop Commander will be limited" fi else # Default: use home directory FOLDERS+=("$HOME") print_success "Using default access to your user folder" fi } # Setup essential volumes for maximum persistence setup_persistent_volumes() { print_verbose "🔧 Setting up persistent development environment" # Essential volumes that cover everything a developer needs ESSENTIAL_VOLUMES=( "dc-system:/usr" # All system packages, binaries, libraries "dc-home:/root" # User configs, dotfiles, SSH keys, git config "dc-workspace:/workspace" # Development files and projects "dc-packages:/var" # Package databases, caches, logs ) for volume in "${ESSENTIAL_VOLUMES[@]}"; do volume_name=$(echo "$volume" | cut -d':' -f1) if ! docker volume inspect "$volume_name" >/dev/null 2>&1; then docker volume create "$volume_name" >/dev/null 2>&1 fi done print_verbose "Persistent environment ready - your tools will survive restarts" } # Ends the installer before anything in the dc-system volume has changed stop_before_volume_update() { print_error "$1" print_info "Nothing was changed. Run the installer again." exit 1 } # Bring the pulled image into the dc-system volume. The volume keeps /usr, so # without this a new image's Desktop Commander and its Chromium stay hidden # behind the ones from the image the volume was first made with. update_system_volume() { print_info "Updating Desktop Commander in your persistent volume dc-system..." # Nothing may use the volume while it is copied: stop the containers that have it (found by # the volume, not ancestor=, which after the pull no longer matches the older image's containers), # then ask again. If Docker doesn't answer, or one still runs, stop before anything changes. local containers containers=$(docker ps -q --filter "volume=dc-system") || stop_before_volume_update "Docker didn't answer which containers use the volume dc-system" if [ -n "$containers" ]; then local stop_error stop_status=0 stop_error=$(docker stop $containers 2>&1 >/dev/null) || stop_status=$? stop_error=${stop_error:0:512} containers=$(docker ps -q --filter "volume=dc-system") || stop_before_volume_update "Docker didn't answer which containers use the volume dc-system" [ -z "$containers" ] || { print_warning "Docker stop exited $stop_status; stderr (first 512 characters): $stop_error" stop_before_volume_update "Desktop Commander's container is still running and uses the volume dc-system" } fi # Copies the new image's /usr into the volume, mounted at /target, so an update reaches users # whose /usr is kept in that volume. Desktop Commander's own folder is replaced; the rest is # copied over what the volume has, so the tools the AI installed stay. install-docker.ps1 has # the same command. if docker run --rm -v dc-system:/target "$DOCKER_IMAGE" sh -c 'rm -rf /target/src/app && cp -a /usr/. /target/'; then print_success "Desktop Commander updated; the tools you installed are kept" else print_error "Could not copy the new image into the volume dc-system" print_info "A folder in the volume may be a link in the new image, or the other way round." print_info "Start again from a clean environment (this removes your installed tools and settings):" echo "• Run: $0 --reset && $0" exit 1 fi } # Build Docker run arguments build_docker_args() { print_verbose "Building Docker configuration..." # Start with base arguments (use --rm so containers auto-remove after each use) DOCKER_ARGS=("run" "-i" "--rm") # Add essential persistent volumes for volume in "${ESSENTIAL_VOLUMES[@]}"; do DOCKER_ARGS+=("-v" "$volume") done # Add user folder mounts with absolute path structure for folder in "${FOLDERS[@]}"; do # Remove leading /Users/username or /home/username and keep absolute structure if [[ "$folder" =~ ^/Users/[^/]+(/.+)$ ]]; then # Mac: /Users/john/projects/data → /home/projects/data absolute_path="${BASH_REMATCH[1]}" DOCKER_ARGS+=("-v" "$folder:/home$absolute_path") elif [[ "$folder" =~ ^/home/[^/]+(/.+)$ ]]; then # Linux: /home/john/projects/data → /home/projects/data absolute_path="${BASH_REMATCH[1]}" DOCKER_ARGS+=("-v" "$folder:/home$absolute_path") else # Fallback for other paths - use basename folder_name=$(basename "$folder") DOCKER_ARGS+=("-v" "$folder:/home/$folder_name") fi done # Add the image DOCKER_ARGS+=("$DOCKER_IMAGE") print_verbose "Docker configuration ready" print_verbose "Essential volumes: ${#ESSENTIAL_VOLUMES[@]} volumes" print_verbose "Mounted folders: ${#FOLDERS[@]} folders" print_verbose "Container mode: Auto-remove after each use (--rm)" } # Update Claude desktop config update_claude_config() { print_verbose "Updating Claude Desktop configuration..." # Create config directory if it doesn't exist CONFIG_DIR=$(dirname "$CLAUDE_CONFIG") if [[ ! -d "$CONFIG_DIR" ]]; then mkdir -p "$CONFIG_DIR" print_verbose "Created config directory: $CONFIG_DIR" fi # Create config if it doesn't exist if [[ ! -f "$CLAUDE_CONFIG" ]]; then echo '{"mcpServers": {}}' > "$CLAUDE_CONFIG" print_verbose "Created new Claude config file" fi # Convert DOCKER_ARGS array to JSON format ARGS_JSON="[" for i in "${!DOCKER_ARGS[@]}"; do if [[ $i -gt 0 ]]; then ARGS_JSON+=", " fi ARGS_JSON+="\"${DOCKER_ARGS[$i]}\"" done ARGS_JSON+="]" # Use Python to update JSON (preserves existing MCP servers) python3 -c " import json import sys config_path = '$CLAUDE_CONFIG' docker_args = $ARGS_JSON try: with open(config_path, 'r') as f: config = json.load(f) except: config = {'mcpServers': {}} if 'mcpServers' not in config: config['mcpServers'] = {} # Configure to use docker run with essential volumes config['mcpServers']['desktop-commander'] = { 'command': 'docker', 'args': docker_args } with open(config_path, 'w') as f: json.dump(config, f, indent=2) print('Successfully updated Claude config') " || { print_error "Failed to update Claude config with Python" exit 1 } print_verbose "Updated Claude config: $CLAUDE_CONFIG" print_verbose "Desktop Commander will be available as 'desktop-commander' in Claude" } # Test the persistent setup test_persistence() { print_verbose "Testing persistent container setup..." print_verbose "Testing essential volumes with a temporary container..." # Test that essential paths are available for persistence if docker "${DOCKER_ARGS[@]}" /bin/bash -c " echo 'Testing persistence paths...' mkdir -p /workspace/test echo 'test-data' > /workspace/test/file.txt && echo 'Workspace persistence: OK' touch /root/.test_config && echo 'Home persistence: OK' echo 'Container test completed successfully' " >/dev/null 2>&1; then print_verbose "Essential persistence test passed" print_verbose "Volumes are working correctly" else print_verbose "Some persistence tests had issues (might still work)" fi } # Show container management commands show_management_info() { echo print_success "🎉 Installation successfully completed! Thank you for using Desktop Commander!" echo print_info "How it works:" echo "• Desktop Commander runs in isolated containers" echo "• Your development tools and configs persist between uses" echo "• Each command creates a fresh, clean container" echo print_info "🤔 Need help or have feedback? Happy to jump on a - install.sh (1567 bytes)
#!/bin/bash # Exit on error set -e # Function to print error print_error() { echo "❌ Error: $1" >&2 } # Function to print success print_success() { echo "✅ $1" } # Check if Node.js is installed if command -v node &> /dev/null; then NODE_VERSION=$(node -v | cut -d 'v' -f 2) NODE_MAJOR_VERSION=$(echo "$NODE_VERSION" | cut -d '.' -f 1) NODE_MINOR_VERSION=$(echo "$NODE_VERSION" | cut -d '.' -f 2) if [ "$NODE_MAJOR_VERSION" -lt 22 ] || { [ "$NODE_MAJOR_VERSION" -eq 22 ] && [ "$NODE_MINOR_VERSION" -lt 12 ]; }; then print_error "Detected Node.js v$NODE_VERSION, but v22.12+ is required. Please upgrade Node.js." exit 1 else echo "Node.js v$NODE_VERSION detected. Continuing..." fi else echo "Node.js not found. Installing Node.js v22.14.0..." mkdir -p /tmp/nodejs-install curl -fsSL -o /tmp/nodejs-install/node-v22.14.0.pkg https://nodejs.org/dist/v22.14.0/node-v22.14.0.pkg sudo installer -pkg /tmp/nodejs-install/node-v22.14.0.pkg -target / if command -v node &> /dev/null; then rm -rf /tmp/nodejs-install print_success "Node.js v22.14.0 installed successfully." else print_error "Node.js installation failed. Visit https://nodejs.org to install manually." exit 1 fi fi # Run the setup echo "Running setup command..." if npx @wonderwhy-er/desktop-commander@latest setup; then print_success "Setup completed successfully!" else print_error "Setup failed. Check the console output above for more information." exit 1 fi exit 0 - INSTRUCTIONS.md (10761 bytes)
--- name: terminal version: 0.1.0 audience: agent description: >- Use Desktop Commander for terminal and command-line work, especially anything that needs a shell whose state persists across turns: Python/Node REPLs, database shells, dev servers and other long-running processes, SSH into remote machines, and Windows PowerShell. Also handles everyday terminal tasks — navigating folders, choosing the right command for the user's shell (PowerShell, cmd, bash, zsh), running Docker/curl/cloud-CLI commands, inspecting processes and ports, and saving recurring workflows as scripts — even when the user doesn't say "Desktop Commander" or "terminal." Reach for it on pasted errors like "command not found", "permission denied", "EADDRINUSE", "address already in use", "npm ERR!", "ModuleNotFoundError", or "ENOENT", and on intents like "what's using port 3000", "kill that process", "ssh into my server", or "why won't my dev server start". Works on Windows, macOS, and Linux. Never run destructive commands without explicit confirmation. --- # Terminal Command Assistant Be a calm, safe, cross-platform terminal copilot. The user may be an expert or may be opening a terminal for the first time — read their cues and match them. Explain what a command does in plain language, run it through Desktop Commander, read the real output, and explain the result. The user's machine is the source of truth; never assume the OS, shell, or installed tools — detect them. ## 1. Detect the environment first (do this before suggesting commands) Different OSes and shells need different commands. Before recommending or running anything non-trivial, call **`get_config`** (Desktop Commander) and read `systemInfo`: - `platformName` / `isWindows` / `isMacOS` / `isLinux` — which OS. - `defaultShell` and `uiHints.availableShells` — which shell to target. - `pythonInfo`, `nodeInfo` — whether Python/Node exist and their versions. - `blockedCommands` — commands Desktop Commander refuses to run (see §7). - `allowedDirectories` — `[]` means full access; otherwise commands/paths are scoped to those directories. This one cheap call prevents the most common mistake: handing a macOS user a PowerShell command, or assuming `python3` exists when it doesn't. Cache what you learn for the rest of the session; re-check only if something seems off. ## 2. Choosing the right command for the shell Pick syntax by the detected shell, not by habit. Common equivalents: | Task | bash / zsh (macOS, Linux) | PowerShell (Windows) | cmd (Windows) | |---|---|---|---| | List files | `ls -la` | `Get-ChildItem` / `ls` | `dir` | | Current dir | `pwd` | `Get-Location` / `pwd` | `cd` | | Find file | `find . -name "*.log"` | `Get-ChildItem -Recurse -Filter *.log` | `dir /s *.log` | | Search text | `grep -r "TODO" .` | `Get-ChildItem -Recurse \| Select-String TODO` | `findstr /s TODO *` | | Env var | `echo $HOME` | `$env:USERPROFILE` | `echo %USERPROFILE%` | | Set env (session) | `export KEY=val` | `$env:KEY="val"` | `set KEY=val` | | Delete file | `rm file` | `Remove-Item file` | `del file` | | Copy | `cp a b` | `Copy-Item a b` | `copy a b` | | Path separator | `/` | `\` (or `/`) | `\` | Notes that bite people: Windows paths use `\` and often need quoting when they contain spaces; PowerShell and bash quote/escape differently; `~` expands in bash/zsh but not in cmd. When in doubt, prefer the cross-platform tool the user already has (e.g. `python`, `node`, `git`) over shell-specific syntax. ## 3. Running commands with Desktop Commander **Always use absolute paths.** Relative paths depend on a working directory that isn't carried between calls, so they fail unpredictably. - **One-shot commands** → `start_process` with the command and a timeout. It returns output and a PID. If output is truncated or the process is still running, call `read_process_output` with the PID for more. - **Long-running / interactive sessions** (REPLs, SSH, DB shells, `npm create`, anything that prompts) → `start_process` to launch, then `interact_with_process(pid, "...")` to send input and `read_process_output` to read responses. End with `force_terminate` if it won't exit on its own. - Navigation is just inspection: use `list_directory` and `get_file_info` rather than relying on a persistent `cd`. If you must `cd`, do it inside the same command (`cd /abs/path && some-command`). ### Interactive REPL pattern (the workhorse) This keeps state across calls and is the right way to drive Python, Node, a database shell, or SSH: ``` start_process("python3 -i") # or "node -i", "ssh user@host", "psql ..." interact_with_process(pid, "import pandas as pd") interact_with_process(pid, "df = pd.read_csv('/abs/path/data.csv')") interact_with_process(pid, "print(df.describe())") read_process_output(pid) # pull more output if needed ``` ## 4. Running specific CLIs - **Python**: prefer `python3 -i` as an interactive session for multi-step work; for a quick one-off use `python3 /abs/script.py`. Check `pythonInfo.command` from §1 (`python` vs `python3`). - **Node**: `node -i` for an interactive session, `node /abs/script.js` for a one-off. `npm`/`pnpm`/`yarn` installs can be slow — give a generous timeout and read remaining output rather than assuming failure. - **Docker**: `docker ps`, `docker logs <id>`, `docker compose up -d`. Long builds/runs: launch then poll with `read_process_output`. Treat `docker system prune`, `docker rm`, `docker volume rm` as destructive (§7). - **SSH**: launch with `start_process("ssh user@host")`, then drive it with `interact_with_process`. Remote destructive commands deserve the same confirmation rules as local ones. - **curl / HTTP**: fine for inspection (`curl -i https://...`). Be careful with anything that pipes a downloaded script straight into a shell (`curl ... | sh`) — that's untrusted code execution; show it and confirm first. - **Cloud CLIs** (`aws`, `gcloud`, `az`): read-only commands (`describe`, `list`, `get`) are safe to run; anything that creates, deletes, scales, or changes IAM is high-impact — preview the exact command and confirm. Never echo secrets or credentials into the terminal output. ## 5. Inspecting processes and ports - **Processes**: `list_processes` (Desktop Commander) for a structured view, or `ps aux` (Unix) / `Get-Process` (PowerShell). Stop one with `kill_process` by PID (`force_terminate` ends a session you started). - **What's using a port**: - macOS/Linux: `lsof -i :3000` or `lsof -nP -iTCP -sTCP:LISTEN` - Linux: `ss -ltnp` - Windows PowerShell: `Get-NetTCPConnection -LocalPort 3000` - Windows cmd: `netstat -ano | findstr :3000` (then map the PID) - When killing a process, confirm the PID belongs to what the user thinks it does — show the process line before terminating it. ## 6. Explaining errors in plain English When a command fails, don't just retry blindly: 1. Read the **actual** error text from the process output — the real cause is usually in the last few lines, not the first. 2. Name the cause in one plain sentence (e.g. "the port's already taken", "that package isn't installed", "permission denied because the file's owned by root"). 3. Give the concrete fix command for *their* shell, and explain what it does. 4. If the fix is risky or guesswork, say so and offer the safe diagnostic first. Common ones worth recognizing fast: `command not found` / `not recognized` (not installed or not on PATH), `EADDRINUSE` (port in use — see §5), `permission denied` / `EACCES` (ownership/permissions, not always fixable with elevation), `ENOENT` (path doesn't exist — check absolute path), `npm ERR!` blocks (read the resolved error line), non-zero exit codes (report the code). ## 7. Safety: destructive commands and chaining Desktop Commander already refuses a built-in `blockedCommands` list (things like `sudo`, `mkfs`, `format`, `dd`, `fdisk`, `shutdown`, `reboot`, `diskpart`, `reg`, `net`). Read the live list from `get_config`; don't assume it. Beyond that list, treat these as **destructive — never run without the user's explicit confirmation**, even if they'd technically succeed: - Recursive/forced deletes: `rm -rf`, `Remove-Item -Recurse -Force`, `del /s`, `rd /s`. - Overwriting or moving over existing files; wildcard deletes. - Disk/format/partition operations. - `git reset --hard`, `git clean -fd`, `git push --force` (history/data loss). - Database drops/truncates: `DROP`, `TRUNCATE`, `DELETE` without a `WHERE`. - `chmod -R` / `chown -R` on broad paths, `killall`, mass process kills. - Cloud deletes/scaling/IAM changes; `docker ... prune`/`rm`/volume removal. - Anything piping remote content into a shell (`curl ... | sh`). For these: show the exact command, explain in one line what it will irreversibly do, and wait for a clear "yes". Prefer a dry run or a read-only check first (e.g. `ls` the glob before `rm` it, `--dry-run` where the tool supports it). **Chaining safely**: `&&` runs the next only if the previous succeeded; `;` runs regardless; `||` runs only on failure. PowerShell historically uses `;` to sequence (it supports `&&`/`||` in v7+, but not all hosts). Keep chains short. If any step in a chain is destructive, don't chain it — run the safe steps, confirm, then run the risky one alone so a failure can't cascade. ## 8. Turning repeated workflows into scripts When the user runs the same sequence repeatedly (or asks to "save this"), offer to capture it as a script instead of retyping: - Unix → a `.sh` file with `#!/usr/bin/env bash` (or `zsh`), `set -euo pipefail` for safety, comments explaining each step; make it executable (`chmod +x`). - Windows → a `.ps1` (PowerShell) script with comment-based help at the top. - Write the file with `write_file` to an absolute path the user chooses, echo it back, and explain how to run it. Parameterize the bits that change (paths, names) rather than hard-coding. - If the workflow needs to run on both Windows and Unix, either keep the logic in a cross-platform tool (a small Python/Node script) or provide both a `.sh` and a `.ps1`. Don't pretend one shell script runs everywhere. Keep scripts small and readable — the goal is something the user can open, trust, and edit later, not a black box. ## Operating etiquette - Preview risky commands before running; run read-only inspection first. - Use absolute paths; respect `allowedDirectories`. - Never print secrets, tokens, or passwords into output; redact if they appear. - Match the user's level: explain jargon when they seem new, stay terse when they're fluent. - After a failed command, diagnose from the real output before retrying. - LICENSE (1108 bytes)
MIT License Copyright (c) 2024-2025 Eduard Ruzga and Desktop Commander Contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- manifest.json (6755 bytes)
{ "manifest_version": "0.3", "name": "desktop-commander", "display_name": "Desktop Commander", "version": "0.3.4", "description": "Build, explore, and automate on your local machine with access to files and terminal.", "long_description": "Combine local filesystem access with full terminal control to handle technical tasks through natural language. Desktop Commander empowers you to build, explore, and automate - from organizing repositories to creating complete applications:\n* **Build from scratch** - Create features and applications with simple commands\n* **Manage development environments** - Set up servers, configure systems, and handle processes\n* **Manage context and documentation** - Keep track of project details and technical specifications\n* **Explore existing codebases and projects** - Navigate and understand complex repositories\n\nThis extension bridges technical skill gaps by providing full command-line superpowers through an interface that understands your intent and handles complexity automatically.", "author": { "name": "Desktop Commander Team", "email": "[email protected]", "url": "https://desktopcommander.app/" }, "repository": { "type": "git", "url": "https://github.com/wonderwhy-er/DesktopCommanderMCP.git" }, "homepage": "https://github.com/wonderwhy-er/DesktopCommanderMCP", "documentation": "https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/FAQ.md", "support": "https://github.com/wonderwhy-er/DesktopCommanderMCP/issues", "privacy_policies": [ "https://legal.desktopcommander.app/privacy_desktop_commander_mcp" ], "icon": "icon.png", "server": { "type": "node", "entry_point": "dist/index.js", "mcp_config": { "command": "node", "args": [ "${__dirname}/dist/index.js" ], "env": { "MCP_DXT": "true", "NODE_ENV": "production" } } }, "tools": [ { "name": "get_config", "description": "Get the complete server configuration including blocked commands, allowed directories, file limits, telemetry settings, client info, and system information." }, { "name": "set_config_value", "description": "Set a specific configuration value by key. WARNING: Should be used in a separate chat from file operations to prevent security issues." }, { "name": "read_file", "description": "Read contents from local filesystem, URLs, Excel files (.xlsx, .xls, .xlsm), PDFs, and DOCX files with line/page-based pagination." }, { "name": "read_multiple_files", "description": "Read the contents of multiple files simultaneously. Handles text files and renders images." }, { "name": "write_file", "description": "Write or append to file contents. Supports Excel files (JSON 2D array format) and DOCX creation from markdown. For PDFs, use write_pdf instead." }, { "name": "write_pdf", "description": "Create new PDF files from markdown or modify existing PDFs (insert/delete pages). Supports HTML/CSS styling and SVG graphics." }, { "name": "create_directory", "description": "Create a new directory or ensure a directory exists. Can create multiple nested directories in one operation." }, { "name": "list_directory", "description": "Get a detailed recursive listing of all files and directories in a specified path. Supports depth parameter (default: 2) for multi-level directory traversal." }, { "name": "move_file", "description": "Move or rename files and directories between locations." }, { "name": "start_search", "description": "Start streaming search for files by name or content patterns. Searches text files, Excel, and DOCX content." }, { "name": "get_more_search_results", "description": "Get more results from an active search with offset-based pagination." }, { "name": "stop_search", "description": "Stop an active search gracefully when you've found what you need." }, { "name": "list_searches", "description": "List all active searches with their status and runtime information." }, { "name": "get_file_info", "description": "Retrieve detailed metadata about a file or directory including size, timestamps, permissions, line counts, and sheet info for Excel files." }, { "name": "edit_block", "description": "Apply targeted text replacements for text and DOCX files, or range-based cell updates for Excel files." }, { "name": "start_process", "description": "Start a new terminal process with intelligent state detection. Primary tool for local file analysis (CSV, JSON, logs, etc.)." }, { "name": "read_process_output", "description": "Read output from a running process with intelligent completion detection, REPL prompt recognition, and offset/length pagination." }, { "name": "interact_with_process", "description": "Send input to a running process and automatically receive the response. Critical tool for all local file analysis." }, { "name": "force_terminate", "description": "Force terminate a running terminal session." }, { "name": "list_sessions", "description": "List all active terminal sessions with status information including blocked state and runtime." }, { "name": "list_processes", "description": "List all running processes with PID, command name, CPU usage, and memory usage." }, { "name": "kill_process", "description": "Terminate a running process by PID. Use with caution." }, { "name": "get_usage_stats", "description": "Get usage statistics for debugging and analysis including tool usage and performance metrics." }, { "name": "get_recent_tool_calls", "description": "Get recent tool call history with their arguments and outputs. Returns chronological list of tool calls made during this session for debugging, context recovery, and onboarding new chats." }, { "name": "give_feedback_to_desktop_commander", "description": "Open feedback form in browser to provide feedback about Desktop Commander." } ], "keywords": [ "orchestration", "workflow", "development", "prototyping", "terminal", "processes", "file-management", "automation", "productivity", "end-to-end", "data-analysis", "docx", "pdf", "excel" ], "license": "MIT", "compatibility": { "platforms": [ "darwin", "win32", "linux" ], "runtimes": { "node": ">=22.12.0" } } } - manifest.template.json (6806 bytes)
{ "$schema": "../../dist/mcpb-manifest.schema.json", "manifest_version": "0.3", "name": "desktop-commander", "display_name": "Desktop Commander", "version": "{{VERSION}}", "description": "Build, explore, and automate on your local machine with access to files and terminal.", "long_description": "Combine local filesystem access with full terminal control to handle technical tasks through natural language. Desktop Commander empowers you to build, explore, and automate - from organizing repositories to creating complete applications:\n* **Build from scratch** - Create features and applications with simple commands\n* **Manage development environments** - Set up servers, configure systems, and handle processes\n* **Manage context and documentation** - Keep track of project details and technical specifications\n* **Explore existing codebases and projects** - Navigate and understand complex repositories\n\nThis extension bridges technical skill gaps by providing full command-line superpowers through an interface that understands your intent and handles complexity automatically.", "author": { "name": "Desktop Commander Team", "email": "[email protected]", "url": "https://desktopcommander.app/" }, "repository": { "type": "git", "url": "https://github.com/wonderwhy-er/DesktopCommanderMCP.git" }, "homepage": "https://github.com/wonderwhy-er/DesktopCommanderMCP", "documentation": "https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/FAQ.md", "support": "https://github.com/wonderwhy-er/DesktopCommanderMCP/issues", "privacy_policies": ["https://legal.desktopcommander.app/privacy_desktop_commander_mcp"], "icon": "icon.png", "server": { "type": "node", "entry_point": "dist/index.js", "mcp_config": { "command": "node", "args": [ "${__dirname}/dist/index.js" ], "env": { "MCP_DXT": "true", "NODE_ENV": "production" } } }, "tools": [ { "name": "get_config", "description": "Get the complete server configuration including blocked commands, allowed directories, file limits, telemetry settings, client info, and system information." }, { "name": "set_config_value", "description": "Set a specific configuration value by key. WARNING: Should be used in a separate chat from file operations to prevent security issues." }, { "name": "read_file", "description": "Read contents from local filesystem, URLs, Excel files (.xlsx, .xls, .xlsm), PDFs, and DOCX files with line/page-based pagination." }, { "name": "read_multiple_files", "description": "Read the contents of multiple files simultaneously. Handles text files and renders images." }, { "name": "write_file", "description": "Write or append to file contents. Supports Excel files (JSON 2D array format) and DOCX creation from markdown. For PDFs, use write_pdf instead." }, { "name": "write_pdf", "description": "Create new PDF files from markdown or modify existing PDFs (insert/delete pages). Supports HTML/CSS styling and SVG graphics." }, { "name": "create_directory", "description": "Create a new directory or ensure a directory exists. Can create multiple nested directories in one operation." }, { "name": "list_directory", "description": "Get a detailed recursive listing of all files and directories in a specified path. Supports depth parameter (default: 2) for multi-level directory traversal." }, { "name": "move_file", "description": "Move or rename files and directories between locations." }, { "name": "start_search", "description": "Start streaming search for files by name or content patterns. Searches text files, Excel, and DOCX content." }, { "name": "get_more_search_results", "description": "Get more results from an active search with offset-based pagination." }, { "name": "stop_search", "description": "Stop an active search gracefully when you've found what you need." }, { "name": "list_searches", "description": "List all active searches with their status and runtime information." }, { "name": "get_file_info", "description": "Retrieve detailed metadata about a file or directory including size, timestamps, permissions, line counts, and sheet info for Excel files." }, { "name": "edit_block", "description": "Apply targeted text replacements for text and DOCX files, or range-based cell updates for Excel files." }, { "name": "start_process", "description": "Start a new terminal process with intelligent state detection. Primary tool for local file analysis (CSV, JSON, logs, etc.)." }, { "name": "read_process_output", "description": "Read output from a running process with intelligent completion detection, REPL prompt recognition, and offset/length pagination." }, { "name": "interact_with_process", "description": "Send input to a running process and automatically receive the response. Critical tool for all local file analysis." }, { "name": "force_terminate", "description": "Force terminate a running terminal session." }, { "name": "list_sessions", "description": "List all active terminal sessions with status information including blocked state and runtime." }, { "name": "list_processes", "description": "List all running processes with PID, command name, CPU usage, and memory usage." }, { "name": "kill_process", "description": "Terminate a running process by PID. Use with caution." }, { "name": "get_usage_stats", "description": "Get usage statistics for debugging and analysis including tool usage and performance metrics." }, { "name": "get_recent_tool_calls", "description": "Get recent tool call history with their arguments and outputs. Returns chronological list of tool calls made during this session for debugging, context recovery, and onboarding new chats." }, { "name": "give_feedback_to_desktop_commander", "description": "Open feedback form in browser to provide feedback about Desktop Commander." } ], "keywords": [ "orchestration", "workflow", "development", "prototyping", "terminal", "processes", "file-management", "automation", "productivity", "end-to-end", "data-analysis", "docx", "pdf", "excel" ], "license": "MIT", "compatibility": { "platforms": [ "darwin", "win32", "linux" ], "runtimes": { "node": ">=22.12.0" } } } - package.json (6500 bytes)
{ "name": "@wonderwhy-er/desktop-commander", "version": "0.3.4", "description": "MCP server for terminal operations and file editing", "mcpName": "io.github.wonderwhy-er/desktop-commander", "license": "MIT", "author": "Eduards Ruzga", "homepage": "https://github.com/wonderwhy-er/DesktopCommanderMCP", "repository": { "type": "git", "url": "https://github.com/wonderwhy-er/DesktopCommanderMCP.git" }, "bugs": "https://github.com/wonderwhy-er/DesktopCommanderMCP/issues", "type": "module", "engines": { "node": ">=22.12.0" }, "bin": { "desktop-commander": "dist/index.js", "setup": "dist/setup-claude-server.js", "remove": "dist/uninstall-claude-server.js" }, "files": [ "dist", "logo.png", "testemonials" ], "scripts": { "postinstall": "node dist/track-installation.js && node dist/npm-scripts/verify-ripgrep.js || node -e \"process.exit(0)\"", "open-chat": "open -n /Applications/Claude.app", "device:install": "cd src/remote-device && npm install", "device:start": "tsx src/remote-device/device.ts", "device:start:dev": "nodemon --watch src/remote-device --exec tsx src/remote-device/device.ts", "sync-version": "node scripts/sync-version.js", "bump": "node scripts/sync-version.js --bump", "bump:minor": "node scripts/sync-version.js --bump --minor", "bump:major": "node scripts/sync-version.js --bump --major", "build": "tsc && shx cp setup-claude-server.js uninstall-claude-server.js track-installation.js dist/ && shx chmod +x dist/*.js && shx mkdir -p dist/data && shx cp src/data/onboarding-prompts.json dist/data/ && shx mkdir -p dist/remote-device/scripts && shx cp src/remote-device/scripts/blocking-offline-update.js dist/remote-device/scripts/ && node scripts/build-ui-runtime.cjs", "watch": "tsc --watch", "start": "node dist/index.js", "start:debug": "node --inspect-brk=9229 dist/index.js", "setup": "npm install --include=dev && npm run build && node setup-claude-server.js", "setup:debug": "npm install && npm run build && node setup-claude-server.js --debug", "remove": "npm install && npm run build && node uninstall-claude-server.js", "prepare": "npm run build", "clean": "shx rm -rf dist", "test": "npm run build && node test/run-all-tests.js", "test:changed": "npm run build && node test/run-all-tests.js --no-build --changed", "test:ci": "npm run build && node test/run-ci.js", "build:coverage": "npm run build && tsc -p tsconfig.coverage.json && node test/map-copied-scripts.js", "test:coverage": "npm run build:coverage && node test/run-coverage.js", "test:integration": "npm run build && node test/integration/run-all-integration-tests.js", "test:transport:telemetry": "npm run build && node test/test-transport-telemetry.js", "test:debug": "node --inspect test/run-all-tests.js", "review": "node test/ci-review.js run", "validate:tools": "npm run build && node scripts/validate-tools-sync.js", "link:local": "npm run build && npm link", "unlink:local": "npm unlink", "inspector": "npx @modelcontextprotocol/inspector dist/index.js", "build:mcpb": "node scripts/build-mcpb.cjs", "release": "node scripts/publish-release.cjs", "release:minor": "node scripts/publish-release.cjs --minor", "release:major": "node scripts/publish-release.cjs --major", "release:dry": "node scripts/publish-release.cjs --dry-run", "release:rehearsal": "node scripts/publish-release.cjs --rehearsal", "release:alpha": "node scripts/publish-release.cjs --alpha", "logs:view": "npm run build && node scripts/view-fuzzy-logs.js", "logs:analyze": "npm run build && node scripts/analyze-fuzzy-logs.js", "logs:clear": "npm run build && node scripts/clear-fuzzy-logs.js", "logs:export": "npm run build && node scripts/export-fuzzy-logs.js", "count-tokens": "npm run build && node scripts/count-tokens.js", "count-tokens:json": "npm run build && node scripts/count-tokens.js --json", "device:start:local": "npm run build && DC_ENV=development MCP_SERVER_URL=http://mcp.localhost:3007 npm run device:start:dev" }, "publishConfig": { "access": "public" }, "keywords": [ "mcp", "model-context-protocol", "terminal", "claude", "ai", "command-line", "process-management", "file-editing", "code-editing", "diff", "patch", "block-editing", "file-system", "text-manipulation", "code-modification", "surgical-edits", "file-operations" ], "dependencies": { "@modelcontextprotocol/sdk": "^1.32.1", "@opendocsg/pdf2md": "0.3.4", "@supabase/supabase-js": "^2.89.0", "@tiptap/core": "^3.31.4", "@tiptap/extension-image": "^3.31.4", "@tiptap/extension-table": "^3.31.4", "@tiptap/extension-table-cell": "^3.31.4", "@tiptap/extension-table-header": "^3.31.4", "@tiptap/extension-table-row": "^3.31.4", "@tiptap/pm": "^3.31.4", "@tiptap/starter-kit": "^3.31.4", "@vscode/ripgrep": "^1.15.9", "cross-fetch": "^4.1.0", "exceljs": "^4.4.0", "fastest-levenshtein": "^1.0.16", "glob": "^10.3.10", "highlight.js": "^11.11.1", "isbinaryfile": "^5.0.4", "markdown-it": "^14.1.0", "md-to-pdf": "^5.2.5", "mqtt": "5.16.0", "node-forge": "1.4.0", "open": "^10.2.0", "pdf-lib": "^1.17.1", "pizzip": "^3.2.0", "proper-lockfile": "^4.1.2", "remark": "^15.0.1", "remark-gfm": "^4.0.1", "remark-parse": "^11.0.0", "sharp": "^0.35.5", "tiptap-markdown": "^0.9.0", "unbash": "6.0.1", "unified": "^11.0.5", "unpdf": "~1.8.1", "zod": "^3.24.1", "zod-to-json-schema": "^3.23.5" }, "optionalDependencies": { "caffeinate": "^1.0.1" }, "devDependencies": { "@anthropic-ai/mcpb": "^1.2.0", "@modelcontextprotocol/ext-apps": "^1.0.1", "@types/node": "^20.17.24", "@types/node-forge": "1.3.14", "@types/proper-lockfile": "^4.1.4", "aedes": "0.51.3", "c8": "^12.0.0", "commander": "^13.1.0", "esbuild": "^0.27.2", "js-tiktoken": "^1.0.21", "jsdom": "^24.1.3", "nexe": "^5.0.0-beta.4", "nodemon": "^3.0.2", "shx": "^0.3.4", "ts-node": "^10.9.2", "tsx": "^4.21.0", "typescript": "^5.3.3", "ws": "^8.18.3" }, "overrides": { "md-to-pdf": { "chokidar": "^4.0.3" }, "exceljs": { "uuid": "^11.1.1" }, "proxy-addr": "^2.0.8", "argparse": "^2.0.1" } } - plugin.json (705 bytes)
{ "name": "desktop-commander", "description": "MCP server for terminal commands, process management, and file operations across text, code, PDF, DOCX, Excel, images, and structured data", "version": "1.5.0", "author": { "name": "Desktop Commander", "email": "[email protected]", "url": "https://desktopcommander.app" }, "homepage": "https://desktopcommander.app", "repository": "https://github.com/wonderwhy-er/DesktopCommanderMCP", "license": "MIT", "keywords": [ "shell", "terminal", "filesystem", "process", "documents", "pdf", "spreadsheet", "mcp", "desktop-commander" ], "skills": "./skills/", "mcpServers": ".mcp.json" } - plugin.yaml (1274 bytes)
# plugin.yaml — DesktopCommanderMCP Plugin Manifest # This file makes DesktopCommanderMCP discoverable as an agent plugin. # Learn more: https://list.agenium.net/plugins name: desktop-commander-mcp display_name: DesktopCommanderMCP manifest_version: "1.0" description: > MCP server that gives AI agents terminal control, file system search, diff-based file editing, and document handling capabilities. Run shell commands, search files, read/write Excel, PDF, and DOCX files, analyze data, and edit code — all through the Model Context Protocol. author: name: wonderwhy-er url: https://github.com/wonderwhy-er repository: https://github.com/wonderwhy-er/DesktopCommanderMCP license: MIT categories: - mcp-servers - developer-tools - system-utilities tags: - mcp - model-context-protocol - terminal - file-system - diff-editing - shell-commands - code-editing - excel - pdf - docx - data-analysis capabilities: - terminal-control - file-search - diff-editing - process-management - file-system-operations - excel-support - pdf-support - docx-support - data-analysis install: npx: "@wonderwhy-er/desktop-commander" runtime: language: typescript min_node: "18" protocols: - mcp transport: - stdio
- plugins/claude/skills/ai-tools-setup/references/claude-desktop-mcp.md (3767 bytes)
# Claude Desktop & MCP Servers How to install Claude Desktop, add MCP servers, and inspect / validate / repair MCP configuration files. This is the most common and most mechanical task — high success rate when done carefully. ## Config file locations MCP-capable clients each keep their own config. Find the right one first. | Client | macOS | Windows | |---|---|---| | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | `%APPDATA%\Claude\claude_desktop_config.json` | | Claude Code (per project) | `<project>/.claude/mcp.json` or `.mcp.json` | same | | LM Studio | `~/.lmstudio/mcp.json` | `%USERPROFILE%\.lmstudio\mcp.json` | | Cursor | `~/.cursor/mcp.json` | `%USERPROFILE%\.cursor\mcp.json` | If the file doesn't exist yet, create it with a minimal valid skeleton: ```json { "mcpServers": {} } ``` ## Anatomy of an MCP server entry A stdio server entry has a launch `command`, `args`, and optional `env`: ```json { "mcpServers": { "example": { "command": "npx", "args": ["-y", "@scope/some-mcp-server"], "env": { "SOME_API_KEY": "..." } } } } ``` Notes: - On Windows, `npx` sometimes must be invoked as `cmd /c npx ...` — if a server fails to launch on Windows but works on macOS, try wrapping the command. - Use absolute paths for local scripts; `~` is not expanded inside JSON. - Secrets belong in `env` here (or the server's own config), never pasted into chat. ## Add a server end-to-end 1. **Confirm prerequisites.** Most MCP servers need Node (check `node -v`; many need 18+). Some need Python or Docker. Install the runtime if missing. 2. **Back up the config** (`claude_desktop_config.json` → `claude_desktop_config.json.bak`). 3. **Add the server block** under `mcpServers`. Preserve existing entries. 4. **Validate the JSON** (parse it; check for trailing commas, unescaped backslashes in Windows paths, missing quotes). 5. **Fully restart the client.** Claude Desktop must be quit and reopened — a window reload is not enough. 6. **Verify.** Confirm the server appears and its tools are listed. If the client shows a "failed" server, read its MCP log. ## Inspect, validate, repair (the core job) When a user says MCP "isn't working," diagnose in this order: 1. **Read the config file** and pretty-print it. Most breakages are here. 2. **Validate JSON.** The frequent culprits: - trailing comma after the last entry - single backslashes in Windows paths (need `\\` or forward slashes) - smart quotes from copy-paste instead of straight quotes - a server block pasted at the wrong nesting level 3. **Check the launch command resolves** — does `command` exist on PATH? Run it manually in a terminal to see the real error. 4. **Check credentials** — is the required `env` key present and valid? 5. **Repair, back up first, restart the client, then re-verify.** ## Connection health check Separate the three failure classes so you fix the right thing: - **Config typo** → client shows the server as failed immediately on start; the JSON or command is wrong. Fix the file. - **Server down / crashes** → server starts then exits; running the command manually reproduces the crash. Fix deps/runtime. - **Auth failure** → server starts and lists tools, but calls fail with 401/403. Fix the API key/token. ## Claude Desktop install If Claude Desktop itself isn't installed, point the user to the official download and confirm the app launches before touching MCP config. Don't side-load from unofficial mirrors. ## Safety - Only add MCP servers from sources the user trusts; an MCP server runs with the user's privileges. - Back up before editing; redact secrets in summaries; restart the client to apply changes. - plugins/claude/skills/ai-tools-setup/references/hermes.md (3902 bytes)
# Hermes **Disambiguate first — "Hermes" means two different things:** 1. **Hermes Agent** — the self-improving AI agent framework built by Nous Research (a learning loop that creates/improves skills, persistent memory, runs across many platforms). This is almost always what users mean when they say "set up Hermes." Docs: https://hermes-agent.nousresearch.com/docs/ 2. **Hermes 3 (and other Hermes models)** — Nous Research's open-weight LLMs. "Set up Hermes 3" usually just means running a local model: `ollama pull hermes3` then `ollama run hermes3`. If that's the goal, treat it as ordinary local-model setup and stop here. The rest of this file covers **Hermes Agent**. MIT licensed. For current commands, fetch the docs (there's also `/docs/llms.txt` for a compact index). ## Install **Desktop app (Windows/macOS):** download the Hermes Desktop installer from https://hermes-agent.nousresearch.com/ and run it (installs CLI + desktop app). **CLI only:** ```bash # Linux / macOS / WSL2 / Android (Termux) curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` ```powershell # Windows (native), in PowerShell iex (irm https://hermes-agent.nousresearch.com/install.ps1) ``` See the full Installation Guide for what the installer does, per-user vs. root layout, and Windows notes. ## Fastest path to a working agent ```bash hermes setup --portal ``` One OAuth via **Nous Portal** covers a model plus the four Tool Gateway tools (web search, image generation, TTS, browser). This is the smoothest first run — recommend it unless the user specifically wants their own provider keys. ## Providers & config Hermes works with **Nous Portal, OpenRouter, OpenAI, or any compatible endpoint**. Configuration lives in Hermes' config file (see the Configuration docs). Common requests: - Wire OpenRouter / OpenAI / a custom endpoint with the user's own key — verify the key works before going further. - "Use my workspace Gemini / no API cost" and similar — set the matching provider/model in config; confirm the model ID is current and supported. - If a Portal login code is rejected, re-run `hermes setup --portal` and check the user is pasting the current code. ## Key features to configure - **Personality (`SOUL.md`)** — defines the agent's default voice/tone. Users often ask to generate or update it. Keep it a plain Markdown persona file. - **Memory** — persistent, grows across sessions; mostly automatic. - **Skills** — procedural memory the agent creates and reuses; compatible with the open agentskills.io standard, so skills are portable. - **MCP integration** — Hermes can connect to MCP servers and filter their tools. For config-file mechanics, see `claude-desktop-mcp.md`; for Hermes-side specifics see the docs' MCP page. - **Messaging gateway** — Telegram, Discord, Slack, WhatsApp, Signal, Teams, and 20+ platforms from one gateway. Telegram is the quickest to validate. - **Backends** — Hermes can run on 6 terminal backends: local, Docker, SSH, Daytona, Singularity, Modal. Daytona/Modal give serverless persistence (idle ≈ free). Pick local for a first run; Docker if the user wants isolation. ## Troubleshooting checklist 1. **Install/update stuck** → check the installer/log output; confirm the runtime and PATH; on Windows watch for permission/antivirus interference. Re-run the installer if needed. 2. **"Agent won't respond / got stuck"** → run the generic diagnostic: provider key valid + has credit → model exists and supports tools → process running → read logs for the first real error. 3. **Portal/auth errors** → re-run `hermes setup --portal`; verify the account and code. 4. **Provider model errors (404/402/403)** → switch to a current, available model. See the FAQ & Troubleshooting page in the docs for tool- and platform-specific fixes.
- plugins/claude/skills/ai-tools-setup/references/openclaw.md (3867 bytes)
# OpenClaw OpenClaw is a self-hosted, multi-channel **gateway for AI agents** — one Gateway process bridges chat apps (Discord, iMessage, Signal, Slack, Telegram, WhatsApp, and more) to an AI agent. MIT licensed. Official docs: https://docs.openclaw.ai/ (append `/index.md` or use the "View as Markdown" links for clean text). Always confirm current commands against the docs — OpenClaw releases often. ## Install & first run Requirements: Node 24 recommended (Node 22.19+ works), plus an API key from a model provider. ```bash # Install npm install -g openclaw@latest # Guided onboarding + install the background service openclaw onboard --install-daemon # Open the browser Control UI openclaw dashboard ``` The Control UI default is `http://127.0.0.1:18789/`. (Some versions/setups use a nearby port — if 18789 doesn't load, check the onboarding output or `openclaw doctor` for the actual port.) Fastest way to chat from a phone: connect the **Telegram** channel. ## Config - Main config lives at `~/.openclaw/openclaw.json`. - With no config, OpenClaw uses its bundled agent runtime with per-sender sessions. - Lock-down basics: channel allowlists (e.g. `channels.whatsapp.allowFrom`) and group mention rules. Run the built-in diagnostics whenever something is off: ```bash openclaw doctor ``` If it reports "Config invalid," fix the JSON (back it up first) and re-run. ## Providers & models (the most common pain) OpenClaw needs a model provider configured. Recurring issues and fixes: - **"No API key found for provider X"** — auth is configured per agent. Add the provider's credentials for the active agent (via onboarding/`openclaw agents`), or copy the auth profile from the main agent. Confirm the key is valid and has credit *before* further setup. - **Model doesn't support tools** — some local models (e.g. certain distilled reasoning models) can't do tool-calling, which the agent needs. Switch to a model that supports tools. - **Local models** — running via Ollama or LM Studio is common for cost reasons. Watch for: the local server not running, the wrong base URL/port, GPU not engaged / high RAM, and prompt-template mismatches (LM Studio "jinja" errors — switch the model's preset/template). See the docs' Models/Providers section. - **Provider churn** — model names get deprecated and accounts get rate-limited or model-blocked. When you hit a 402/403/404 from a provider, switch to a current, available model rather than retrying. For best quality and security the docs recommend the strongest current-gen model available. ## Channels Each chat platform is a "channel" with its own setup (token/pairing). Telegram is the quickest to validate. Configure one channel, confirm a round-trip message, then add others. See https://docs.openclaw.ai/channels. ## Remote access To reach the gateway from outside the machine, use the documented patterns (SSH / tailnet). Tailscale is covered at https://docs.openclaw.ai/gateway/tailscale. Avoid exposing the dashboard directly to the public internet. ## Troubleshooting checklist 1. `openclaw doctor` — start here. 2. **Gateway `Unauthorized`** at the dashboard URL → the gateway token/auth isn't set or the URL/port is wrong; re-check onboarding output and config. 3. **Connects but `disconnected (1006): no reason`** on first message → almost always a provider/model problem (missing key, unsupported model), not the network. Run the provider/model checks above. 4. **Module/runtime errors** → confirm Node version; reinstall if needed. 5. Read logs with `openclaw logs --follow`. ## Uninstall / cleanup - Stop the service/daemon, then `npm uninstall -g openclaw`. - Remove residual files in `~/.openclaw/` (back up first if it holds config the user may want). - Disable any autostart entry created during onboarding.
- plugins/claude/skills/ai-tools-setup/SKILL.md (5845 bytes)
--- name: ai-tools-setup version: 0.1.0 audience: agent description: >- Set up, connect, validate, and repair Claude Desktop and MCP servers using Desktop Commander — inspecting and fixing mcp.json / claude_desktop_config.json, getting MCP servers to connect, and diagnosing local AI tooling. Use when a user wants to install, configure, connect, validate, or fix Claude Desktop, an MCP server, an MCP config file, or a local AI agent/gateway. Trigger on the symptoms that actually bring people in: "Claude can't see my tools", "my MCP server isn't showing up", "tools aren't loading in Claude", "add an MCP server", "my MCP isn't connecting", "fix my Claude Desktop config", "the agent won't respond", "wire up Ollama / LM Studio", "restart Claude Desktop". Also covers local agent gateways like OpenClaw and Hermes. --- # AI Tools Setup Assistant Help users install, configure, and repair AI tooling on their own machine using Desktop Commander's file and terminal tools. The work is usually **configure-and-troubleshoot**, not clean installs — assume something already exists and may be half-broken. ## Golden rules (read before doing anything) 1. **Detect the OS and shell first.** Read `get_config` and use its `systemInfo` and `allowedDirectories` — file paths, commands, and config locations differ across macOS, Windows, and Linux, so confirm the platform before assuming anything. 2. **Verify the model/API key works before you build.** The most common reason these sessions dead-end is a provider auth or billing error discovered *after* a lot of setup work. Make one tiny test call with `start_process` (a quick curl to the provider) early, and tell the user plainly if the key is invalid or out of credit. 3. **Translate errors, don't dump them.** When a tool returns a raw JSON/HTTP error, explain in one line what it means and what to do next. If a model is missing, deprecated, rate-limited, or doesn't support tool-calling, suggest a concrete working alternative instead of retrying the same thing. 4. **Never echo secrets.** API keys, tokens, and passwords go *into the right config or `.env` file* — never repeated back in chat. If a user pastes a live secret, warn them, use it, and suggest they rotate it if it was shared insecurely. Redact secrets in any output, logs, or summaries you produce. 5. **Back up before you edit.** Copy the config to a `.bak` first with `start_process` (`cp file.json file.json.bak`, or `copy` on Windows), then make the change with `edit_block` so existing entries survive — reach for `write_file` only on a from-scratch config. Validate the JSON after every edit by parsing it with `start_process`. 6. **Verify, then stop.** After a change, actually confirm it worked — use `list_processes` to confirm the process is running and `start_process` (`lsof`/`netstat`) to confirm the port is listening, then check the client reconnected and its tools are listed. Don't declare success on a guess. 7. **Make it repeatable.** Once something works, offer to save the steps as a short note or script so the user can redo it later. ## What this skill covers This skill routes to one of three reference files depending on the task. Read the relevant file before acting — they contain the exact paths, commands, and known failure modes. - **Claude Desktop & MCP servers** — installing Claude Desktop, adding MCP servers, and inspecting / validating / repairing MCP config files (`claude_desktop_config.json`, `.claude/mcp.json`, `~/.lmstudio/mcp.json`, and similar). Also connection health checks. → Read [`references/claude-desktop-mcp.md`](references/claude-desktop-mcp.md) - **OpenClaw** — a self-hosted multi-channel gateway for AI agents. Install, onboard, wire a model/provider, connect channels (Telegram, Slack, iMessage, etc.), diagnose the gateway, and uninstall. → Read [`references/openclaw.md`](references/openclaw.md) - **Hermes** — disambiguate first: **Hermes Agent** (the Nous Research self-improving agent framework) vs. **Hermes 3** (just a local LLM you run via Ollama). Install, run `hermes setup --portal`, configure providers, personality (`SOUL.md`), memory/skills, MCP, and messaging. → Read [`references/hermes.md`](references/hermes.md) When in doubt about a tool's current behavior, fetch the official docs: OpenClaw — https://docs.openclaw.ai/ · Hermes — https://hermes-agent.nousresearch.com/docs/ ## General workflow 1. **Clarify the goal and platform.** Install vs. configure vs. fix? Which OS? Which tool/client? 2. **Inspect current state.** `read_file` the relevant config files and use `list_processes` to check whether the relevant process/port/service is already running before changing anything. 3. **Read the matching reference file** for exact paths and commands. 4. **Make the smallest change that moves forward**, backing up configs first. 5. **Verify** the result concretely. 6. **Summarize** what changed, where, and how to undo it — with secrets redacted. ## A generic "my agent isn't responding" diagnostic Use this order for OpenClaw, Hermes, or any local agent/gateway: 1. **Provider/auth** — is a valid API key configured for the active provider, and does it have credit? (Most failures stop here.) 2. **Model** — does the chosen model exist, and does it support tool-calling? Local models especially often don't. 3. **Process/port** — is the gateway/daemon actually running and listening on its port? Is another process holding that port? 4. **Connection** — for chat clients/websockets, does it connect but drop on first message? That usually points back to provider/model, not networking. 5. **Logs** — read the tool's logs for the first real error, not the last one.
- plugins/claude/skills/computer-health-check/references/linux.md (3477 bytes)
# Linux command set Read-only diagnostics, **no sudo**. Targets common distros (Debian/Ubuntu, Fedora, Arch). Some tools (`smartctl`, `upower`) may be absent or need root for full detail — degrade gracefully. ## Collection script (run as one batched process) ```bash bash -c ' echo "== SYSTEM =="; (. /etc/os-release 2>/dev/null; echo "$PRETTY_NAME"); uname -r; uptime -p 2>/dev/null || uptime echo "== HARDWARE =="; echo "CPUs: $(nproc)"; grep -m1 "model name" /proc/cpuinfo | cut -d: -f2 | sed "s/^ //" echo "== DISK =="; df -h / /home 2>/dev/null | grep -v tmpfs echo "== DISK HEALTH =="; lsblk -d -o NAME,SIZE,ROTA,MODEL 2>/dev/null echo "== MEMORY =="; free -h echo "swap:"; swapon --show 2>/dev/null || echo "none" echo "== TOP CPU =="; ps -eo pid,pcpu,pmem,comm --sort=-pcpu | head -n 8 echo "== TOP MEM =="; ps -eo pid,pcpu,pmem,comm --sort=-rss | head -n 8 echo "== BATTERY =="; for b in /sys/class/power_supply/BAT*; do [ -d "$b" ] && { echo "capacity: $(cat $b/capacity 2>/dev/null)%"; echo "health: $(cat $b/health 2>/dev/null)"; cf=$(cat $b/charge_full 2>/dev/null); cd=$(cat $b/charge_full_design 2>/dev/null); [ -n "$cf" ] && [ -n "$cd" ] && echo "wear: $((100*cf/cd))% of design"; }; done echo "== STARTUP =="; echo "enabled user services: $(systemctl --user list-unit-files --state=enabled 2>/dev/null | grep -c enabled)"; ls -1 "$HOME/.config/autostart" 2>/dev/null echo "== STORAGE HOTSPOTS ==" for d in "$HOME/Downloads" "$HOME/.cache" "$HOME/.local/share/Trash"; do [ -d "$d" ] && printf "%s\t%s\n" "$(du -sh "$d" 2>/dev/null | cut -f1)" "${d/#$HOME/~}" done echo "== PACKAGES ==" if command -v apt >/dev/null 2>&1; then echo "apt upgradable: $(apt list --upgradable 2>/dev/null | grep -c upgradable)" elif command -v dnf >/dev/null 2>&1; then echo "dnf updates: $(dnf check-update -q 2>/dev/null | grep -c .)" elif command -v pacman >/dev/null 2>&1; then echo "pacman updates: $(checkupdates 2>/dev/null | wc -l)"; fi echo "== DONE =="' ``` ## How to read it - **Memory:** `free -h` — focus on the `available` column (real headroom) and whether swap `used` is climbing. High swap use with low available = 🟡/🔴. - **Disk health:** `lsblk` confirms devices; full SMART needs `sudo smartctl -H /dev/sdX` (skip — needs root). Report SMART as "not available without elevation" rather than guessing. - **Battery:** the `charge_full / charge_full_design` ratio is the wear %. Skip if no `BAT*`. - **Startup:** `~/.config/autostart` and enabled `--user` units are the actionable third-party items. ## Optional deeper checks (run only if asked) ```bash journalctl -p 3 -b --no-pager | tail -n 30 # recent boot errors (may need group access) du -xh "$HOME" 2>/dev/null | sort -rh | head -n 15 # biggest dirs in home ping -c 4 8.8.8.8 # connectivity ``` ## Cleanup commands (suggest; run only on approval) - **Empty Trash (safe):** `rm -rf "$HOME/.local/share/Trash/"*`. - **User cache (safe, regenerates):** review `du -sh ~/.cache/* | sort -rh | head` then clear specific large entries; avoid blanket deletion. - **Package cache (user action; usually needs sudo):** `apt-get clean`, `dnf clean all`, or `pacman -Sc` — note these typically require root, so suggest rather than run. - **Updates (user action; needs sudo):** `apt upgrade` / `dnf upgrade` / `pacman -Syu`. - **Startup items (user action):** remove `.desktop` files from `~/.config/autostart`, or `systemctl --user disable <unit>`. - plugins/claude/skills/computer-health-check/references/macos.md (3364 bytes)
# macOS command set All commands here are read-only and run **without sudo**. Verified on macOS 26 / Apple Silicon. ## Collection script (run as one batched process) Run this with `start_process` (timeout ~30s). It prints labeled sections you can parse. ```bash zsh -c ' echo "== SYSTEM =="; sw_vers; echo "uptime:"; uptime echo "== HARDWARE =="; system_profiler SPHardwareDataType 2>/dev/null | grep -Ei "Model Name|Chip|Total Number of Cores|Memory:" echo "== DISK =="; df -h / diskutil info / 2>/dev/null | grep -Ei "SMART|Free Space" echo "== MEMORY =="; vm_stat | head -n 8 echo "swap:"; sysctl -n vm.swapusage echo "== TOP CPU =="; ps -Ao pid,pcpu,pmem,comm -r | head -n 8 echo "== TOP MEM =="; ps -Ao pid,pcpu,pmem,comm -m | head -n 8 echo "== BATTERY =="; pmset -g batt | head -n 2 system_profiler SPPowerDataType 2>/dev/null | grep -Ei "Cycle Count|Condition|Maximum Capacity" echo "== THERMAL =="; pmset -g therm 2>/dev/null | head -n 3 echo "== STARTUP =="; echo "user agents:"; ls -1 "$HOME/Library/LaunchAgents" 2>/dev/null echo "service count: $(launchctl list 2>/dev/null | wc -l | tr -d " ")" echo "== STORAGE HOTSPOTS ==" for d in "$HOME/Downloads" "$HOME/Library/Caches" "$HOME/.Trash" "$HOME/Library/Logs"; do [ -d "$d" ] && printf "%s\t%s\n" "$(du -sh "$d" 2>/dev/null | cut -f1)" "${d/#$HOME/~}" done echo "== PACKAGES ==" command -v brew >/dev/null 2>&1 && echo "brew outdated: $(brew outdated 2>/dev/null | wc -l | tr -d " "), cache: $(du -sh "$(brew --cache)" 2>/dev/null | cut -f1)" || echo "brew: not installed" echo "== CRASH REPORTS =="; ls -1 "$HOME/Library/Logs/DiagnosticReports" 2>/dev/null | wc -l echo "== DONE =="' ``` ## How to read it - **Memory pressure:** page size is 16 KB on Apple Silicon. Healthy = meaningful free+inactive pages and near-zero swap "used". If `vm.swapusage` shows hundreds of MB / GB used, that's 🟡/🔴. - **Battery:** `Maximum Capacity` is the wear indicator; `Condition: Normal` is good. "Service Recommended" is 🔴. Skip battery entirely if `pmset -g batt` shows no internal battery (desktop). - **SMART:** `Verified` = healthy. Anything else → 🔴. - **Startup:** named third-party `LaunchAgents` are the actionable ones (e.g. updaters, helper daemons, redundant DB services). The raw `launchctl` count is mostly Apple system services. ## Optional deeper checks (run only if asked) ```bash softwareupdate -l 2>&1 | head -n 20 # pending OS updates (network, slow) networkQuality 2>/dev/null # internet up/down + responsiveness (slow) mdfind 'kMDItemFSSize > 1073741824' 2>/dev/null | head -n 20 # files >1GB, Spotlight-fast ``` ## Cleanup commands (suggest; run only on approval) - **Empty Trash (safe):** `rm -rf "$HOME/.Trash/"*` — or tell the user to empty it from Finder. - **Homebrew (safe):** `brew cleanup` (removes old versions + cache). Upgrade: `brew upgrade`. - **User caches (safe, regenerate):** clear specific large subfolders of `~/Library/Caches/<app>` — review with `du -sh ~/Library/Caches/* | sort -rh | head` first; never blanket-delete. - **Login items (user action):** System Settings → General → Login Items, or remove the specific `~/Library/LaunchAgents/<name>.plist` only if the user confirms they don't want it. - **OS updates (user action, needs restart):** System Settings → General → Software Update. - plugins/claude/skills/computer-health-check/references/windows.md (4052 bytes)
# Windows command set Read-only diagnostics via PowerShell. None require admin. Run through `start_process` with `powershell -NoProfile -Command "..."` (or `pwsh`). Keep outputs bounded with `Select-Object`. ## Collection script (run as one batched process) ```powershell powershell -NoProfile -Command " Write-Output '== SYSTEM =='; (Get-CimInstance Win32_OperatingSystem | Select Caption,Version,LastBootUpTime | Format-List | Out-String).Trim() Write-Output '== HARDWARE =='; (Get-CimInstance Win32_ComputerSystem | Select Manufacturer,Model,@{n='RAM_GB';e={[math]::Round($_.TotalPhysicalMemory/1GB,1)}} | Format-List | Out-String).Trim() Write-Output '== DISK =='; Get-CimInstance Win32_LogicalDisk -Filter 'DriveType=3' | ForEach-Object { '{0} {1}% free ({2:N1} of {3:N1} GB)' -f \$_.DeviceID, [math]::Round(\$_.FreeSpace/\$_.Size*100), (\$_.FreeSpace/1GB), (\$_.Size/1GB) } Write-Output '== DISK HEALTH =='; (Get-PhysicalDisk | Select FriendlyName,HealthStatus,OperationalStatus | Format-Table -Auto | Out-String).Trim() Write-Output '== MEMORY =='; \$os=Get-CimInstance Win32_OperatingSystem; '{0:N1} GB free of {1:N1} GB' -f (\$os.FreePhysicalMemory/1MB),(\$os.TotalVisibleMemorySize/1MB) Write-Output '== TOP CPU =='; (Get-Process | Sort CPU -Desc | Select -First 8 Name,CPU,@{n='MB';e={[math]::Round(\$_.WS/1MB)}} | Format-Table -Auto | Out-String).Trim() Write-Output '== TOP MEM =='; (Get-Process | Sort WS -Desc | Select -First 8 Name,@{n='MB';e={[math]::Round(\$_.WS/1MB)}} | Format-Table -Auto | Out-String).Trim() Write-Output '== BATTERY =='; (Get-CimInstance Win32_Battery | Select EstimatedChargeRemaining,BatteryStatus | Format-List | Out-String).Trim() Write-Output '== STARTUP =='; (Get-CimInstance Win32_StartupCommand | Select Name,Location | Format-Table -Auto | Out-String).Trim() Write-Output '== STORAGE HOTSPOTS =='; \$d=\$env:USERPROFILE; foreach(\$p in 'Downloads','AppData\Local\Temp'){ \$f=Join-Path \$d \$p; if(Test-Path \$f){ \$s=(Get-ChildItem \$f -Recurse -EA SilentlyContinue | Measure Length -Sum).Sum; '{0:N1} GB {1}' -f (\$s/1GB), \$p } } Write-Output '== PACKAGES =='; if(Get-Command winget -EA SilentlyContinue){ (winget upgrade 2>\$null | Measure-Object -Line).Lines } else { 'winget: n/a' } Write-Output '== DONE ==' " ``` ## How to read it - **Battery health detail:** the deep wear report needs `powercfg /batteryreport` (writes an HTML file to disk) — run only on request, then read the generated file. `Win32_Battery` gives charge %, not wear. Skip battery on desktops (no `Win32_Battery` instance). - **Disk health:** `HealthStatus = Healthy` is 🟢; `Warning`/`Unhealthy` is 🔴. - **Memory:** compare free vs total; sustained <10% free under load is 🟡/🔴. Pagefile thrash shows up as high disk + low free RAM. - **Startup:** `Win32_StartupCommand` plus the Run registry keys are the actionable third-party items. - **Packages:** the winget value is a raw output-line count, not an exact upgrade count — read it as "updates pending or not," and run `winget upgrade` for the real list. ## Optional deeper checks (run only if asked) ```powershell powercfg /batteryreport /output "$env:TEMP\battery.html" # then read the file for wear % Get-WindowsUpdate # if PSWindowsUpdate module present Test-Connection -Count 4 8.8.8.8 # basic connectivity ``` ## Cleanup commands (suggest; run only on approval) - **Empty Recycle Bin (safe):** `Clear-RecycleBin -Force` (PowerShell). - **Temp files (safe, regenerate):** remove contents of `$env:TEMP` — show size first with `(Get-ChildItem $env:TEMP -Recurse -EA SilentlyContinue | Measure Length -Sum).Sum/1GB`. - **Package upgrades (user action):** `winget upgrade --all` (may prompt / need elevation per app). - **Startup items (user action):** Task Manager → Startup tab, or Settings → Apps → Startup. - **Windows updates (user action, needs restart):** Settings → Windows Update. - **Disk Cleanup (user action):** `cleanmgr` for system-level reclaim. - plugins/claude/skills/computer-health-check/SKILL.md (8603 bytes)
--- name: computer-health-check version: 0.1.0 audience: agent description: >- Run a comprehensive, read-only health check on the user's computer and return a scored chat summary with prioritized, plain-English recommendations and safe cleanup suggestions. Use this whenever the user wants to check their computer's health, speed it up, free up / reclaim disk space, find what's eating CPU / memory / storage, check battery health and wear, audit login & startup items, see pending updates, or asks for a "tune-up", "checkup", "system report", "health check", or "is my Mac/PC/laptop healthy". Trigger even on casual phrasing like "my laptop feels slow", "why is my fan so loud", "my computer is laggy", "running out of space", or "clean up my machine". Works on macOS, Windows, and Linux. This is a Desktop Commander skill: it relies on a real local shell (start_process / interact_with_process) and is strictly read-only by default — it never needs sudo and only performs cleanups the user explicitly approves. --- # Computer Health Check ## What this skill does Give the user a fast, trustworthy picture of their computer's health and a short list of actions worth taking — the way a good technician would: look first, explain plainly, fix only with permission. It runs entirely through Desktop Commander's local shell, gathers a batch of **read-only** diagnostics, scores each area, prints a concise summary **in the chat**, and then offers cleanup suggestions the user can approve one by one. ## The safety contract (read this first) This is the part that makes users trust the skill, so honor it strictly: - **Read-only by default.** The collection phase only *observes* (sizes, counts, status). It changes nothing. - **Never use `sudo` or elevation.** DC blocks `sudo`, `shutdown`, `reboot`, `dd`, `mount`, `mkfs`, `diskpart`, etc. for good reason. Every check below is designed to work without them. If something seems to need elevation, skip it and say so — don't try to work around the block. - **Cleanups are opt-in.** You may *suggest* cleanups freely, but only *execute* one after the user explicitly approves that specific action, and only show the exact command first. - **Prefer reversible, non-destructive actions.** Emptying caches that regenerate, clearing a package-manager download cache, or emptying Trash are fine to offer. Deleting user documents, uninstalling apps, or editing system files are not — suggest those, let the user do them. ## Workflow ### Step 1 — Detect the OS Determine the platform before doing anything else, because the commands differ. - Quickest: read Desktop Commander's config (`get_config`) and use the `systemInfo.isMacOS` / `isWindows` / `isLinux` booleans (or `platformName`) to pick the platform. - Or run `uname` (macOS/Linux) — if it fails, assume Windows. Then open the matching reference file and use its command set: - macOS → [`references/macos.md`](references/macos.md) - Windows → [`references/windows.md`](references/windows.md) - Linux → [`references/linux.md`](references/linux.md) Read **only** the one that matches. Each file contains a single batched collection script plus interpretation notes and cleanup commands. ### Step 2 — Collect (read-only) Run the batched collection script from the reference file with `start_process`. Batching everything into one call is much faster than many small calls and keeps the output tidy. Guidance: - Keep outputs bounded (`head`, `Select-Object -First`, etc.) so a long process list or file listing doesn't flood the response. - Skip the genuinely slow / network checks (full OS-update list, internet speed test) on the first pass unless the user asked about updates or network. Mention they're available. - If a single command errors (e.g., a tool isn't installed), continue — partial data is fine. ### Step 3 — Score each area Rate each category 🟢 Good / 🟡 Watch / 🔴 Act using the rubric below, then compute a simple overall score. Start at 100 and subtract 8 per 🟡 and 18 per 🔴; floor at 0. Report the number and a one-word verdict (90+ Excellent, 75–89 Good, 60–74 Fair, <60 Needs attention). | Area | 🟢 Good | 🟡 Watch | 🔴 Act | |---|---|---|---| | Free disk space | >20% free | 10–20% | <10% | | Disk health (SMART) | Verified / OK / PASSED | — | failing / not supported & errors present | | Memory pressure | low swap, free pages healthy | noticeable swap/compression | heavy swapping, near-zero free | | Battery (laptops) | ≥80% max capacity, Normal | 70–80% | <70% or "Service/Replace" | | Maintenance | uptime <7d, no pending updates | uptime 7–30d or minor updates | uptime >30d or security updates pending | | Startup load | few third-party login items | moderate | many heavy third-party agents | | Live resource hogs | nothing >50% at idle | one sustained heavy process | multiple / runaway processes | Battery is laptop-only — skip it on desktops/VMs. Reclaimable space is reported as an informational figure, not scored. ### Step 4 — Report in the chat Use this exact structure. Keep it tight and scannable — this is the deliverable. ``` 🖥️ Health Check — <Model>, <OS version> Score: <N>/100 (<verdict>) 🟢/🟡/🔴 Storage — <free> free of <total> (<%>). Reclaimable: ~<X> GB 🟢/🟡/🔴 Memory — <one-line state> 🟢/🟡/🔴 Battery — <cycles> cycles, <max capacity>%, <condition> 🟢/🟡/🔴 Maintenance — up <days>d, <updates state> 🟢/🟡/🔴 Startup — <count> login items (<notable ones>) 🟢/🟡/🔴 Right now — top: <proc> <cpu%>, <proc> <cpu%> Top recommendations 1. <highest-impact action> (<expected benefit, e.g. frees ~13 GB>) 2. <next> 3. <next> ``` List at most the 3–5 highest-impact recommendations, ordered by benefit. Don't dump every finding — the goal is signal, not a wall of text. ### Step 5 — Suggest cleanups, execute only on approval For each recommendation that maps to a concrete command (see the reference file's "Cleanup" section), offer it and show the exact command. Then: - **Safe, reversible** (offer to run on a yes): empty Trash, package-manager cache cleanup (`brew cleanup`, `npm cache clean`), clearing a regenerating user cache folder. (On Linux, `apt-get clean` / `dnf clean` need root — suggest, don't auto-run.) - **Needs the user to decide / act** (suggest, don't auto-run): disabling login items, installing OS updates (requires restart), uninstalling apps, deleting files in Downloads. - **Never**: anything requiring sudo/admin, removing system files, disk/partition operations. When the user approves a safe action, run it, then report what changed (e.g., space freed). Re-running Step 2's storage check afterward is a nice confirmation. ## Recommendation rules (findings → advice) These are the high-value mappings; adapt the wording to the platform. - **Uptime > 30 days** → "Restart your computer — it's been up <N> days. A reboot clears memory and applies pending updates." (Highest ROI, lowest effort.) - **Pending OS/security updates** → platform update step; flag security updates as higher priority. - **Free space < 15%** → lead with the biggest reclaimable buckets you measured. - **Large Downloads / Caches / Trash** → empty Trash; review largest Downloads items by name; clear caches that regenerate. - **Package manager has many outdated items / big cache** → `upgrade` + cache cleanup. - **Battery max capacity < 80%** → explain wear is normal; consider a battery service if it's affecting runtime. - **Many third-party startup agents** → name them and suggest disabling the ones the user doesn't recognize/need (point to System Settings / Task Manager — don't edit them directly). - **A process pinned high at idle** → name it and suggest quitting/investigating. ## Notes & pitfalls - **Don't assume — measure.** Always run the commands and report real numbers. Never fabricate sizes, cycle counts, or statuses. - **Bounded output.** Process and file listings can be huge; always cap them. - **Optional deep checks** (mention, run on request): internet speed test, full update list, per-folder disk scan of the whole home directory, crash-report trend analysis. - **Privacy.** This reads local system metadata only. Don't send anything off the machine; the public-IP check is optional and should be labeled. - **Cross-platform parity.** The three reference files mirror the same categories so the report looks the same regardless of OS.
- plugins/claude/skills/desktop-commander-overview/SKILL.md (12282 bytes)
--- name: desktop-commander-overview description: Use for Desktop Commander MCP capabilities — persistent shells and REPLs, long-running processes, filesystem beyond the workspace, structured files (.xlsx, .docx, .pdf, images) and large local data files such as CSVs, ripgrep search at scale, SSH, or cross-turn state. version: 0.1.0 audience: agent --- # Desktop Commander MCP Desktop Commander gives the agent reach across the user's actual computer — files, folders, terminals, processes, structured documents, and remote machines reachable over SSH. The tools' detailed schemas (parameters, return shapes, format-specific behavior) live in the MCP itself; this skill explains what they enable and how they compose into common workflows. ## What this MCP gives the agent **Persistent shell sessions.** Desktop Commander keeps a started process or session alive across tool calls. Inside a single long-lived shell, REPL, or SSH session, state carries forward — environment variables, working directory, activated virtualenvs, open connections, REPL variables — so the agent can `cd`, activate a venv, then send commands or code into that same session many turns later without re-setup. (Note: separate `start_process` calls open separate sessions and do **not** share shell state with each other; persistence is inside one session, not across them.) **Long-running processes.** Start a dev server, watcher, build, training run, or test suite in the background and keep working. The MCP returns a process handle the agent can tail, interact with, or terminate across many turns. Long-running commands don't need to block the workflow waiting for a foreground command to exit. **Filesystem reach beyond the IDE workspace.** Read, write, move, list, and inspect files anywhere the user has granted scope — Downloads, Documents, project folders outside the IDE, or any other granted folders. Useful for organize-and-clean tasks, batch document work, and any "look at the file my coworker just sent me" request that doesn't fit inside the IDE sandbox. **Surgical edits to existing files.** The `edit_block` tool does exact-string find-and-replace with built-in safety: ambiguous matches fail loudly instead of silently overwriting the wrong thing, and an `expected_replacements` count prevents partial-match disasters. Lower data-loss risk than rewriting whole files based on the slice you happened to read — though a wrong `old_string` or wrong `expected_replacements` can still corrupt content, so review the changed content before considering the edit done. **Binary and structured files handled directly by the MCP.** Excel, DOCX, and PDF are first-class — read and modified through format-specific mechanisms rather than text-only approximations: Excel via cell-range JSON, DOCX via raw-XML edits, PDF via page-level operations on a new output file. The result is the real file in its original format, not a regenerated approximation. Images and PDFs return as viewable content for the agent. **Search at scale.** Streaming, ripgrep-backed search across whole projects or folder trees. The agent picks between filename search and in-file content search, pages through results progressively without flooding context, and runs multiple concurrent searches when the query is ambiguous. **Remote machines via SSH.** A long-lived SSH session inside a persistent shell turns the agent into a real ops tool: connect once, then tail logs, run diagnostics, deploy, or debug across many turns without reconnecting each step. **Process management.** List, inspect, tail, and kill accessible processes (subject to OS permissions). Useful for cleaning up stale dev servers from previous sessions and for diagnosing CPU / memory issues. ## Example workflows Each example names the actual tool sequence. Calls below are written in pseudocode shorthand (`tool_name("arg", flag=value)`); the real tools take object-shaped arguments. Tool descriptions and full parameter sets live in the MCP itself. ### "Debug this production issue" Before running production-impacting SSH commands, explain the intended action and get user confirmation when the risk is non-trivial. `start_process("ssh [email protected]", timeout_ms=...)` opens a long-lived SSH session and returns a PID. `interact_with_process(pid, "tail -f /var/log/app.log\n")` starts streaming logs. Subsequent turns: `read_process_output(pid, offset=-50)` to see the last 50 lines as they arrive, `interact_with_process(pid, "...")` to run diagnostic commands in the same session. `force_terminate(pid)` to close the session when done — for sessions opened by `start_process`, `force_terminate` is the correct cleanup tool; `kill_process` is for arbitrary OS PIDs found via `list_processes`. ### "Deploy this to staging" Before deploys, restarts, migrations, or other environment-changing commands, summarize the action and confirm with the user unless they already explicitly asked for that exact operation. `start_process` for the deploy command (could be a script, an SSH-piped command, or `kubectl`/`gh` etc.). `read_process_output` to track output and surface errors. If the deploy needs an interactive confirmation, `interact_with_process(pid, "yes\n")`. The session stays alive while the agent watches for completion or rollback. ### "Run the dev server and iterate on the API" `start_process("npm run dev", timeout_ms=...)` keeps the server up. The agent then loops: `edit_block` on the route file, `read_process_output(pid, offset=-30)` to see the server's reload, `start_process("curl -s http://localhost:3000/api/...")` for a one-shot test, repeat. The dev server never has to restart between code changes. ### "Refactor across this monorepo" `start_search(pattern="oldFunctionName", path=repo_root, searchType="content")` scopes every call site. `get_more_search_results(sessionId)` pages through. `read_multiple_files(paths=[...])` confirms ambiguous hits in context. `edit_block(file_path, old_string, new_string)` per site, with `expected_replacements` set when the same substring legitimately appears multiple times in one file. Verify by re-running `start_search` on the old name and paging the results with `get_more_search_results(sessionId)` until the run completes — only then can you confirm zero remaining hits. ### "Update the Q3 numbers in this spreadsheet and tweak the summary in the report" `read_file(path="/.../q3.xlsx", sheet="Revenue", range="A1:F50")` returns the existing numbers as a JSON 2D array. `edit_block(file_path="/.../q3.xlsx", range="Revenue!C12:C24", content=[[12345], ...])` updates the cells in place. For the report, DOCX editing is a two-read flow: first `read_file(path="/.../report.docx")` (offset 0) returns the document's outline (headings + paragraph text) so you can locate the summary section. Then `read_file(path="/.../report.docx", offset=N, length=...)` with **`N > 0`** returns the raw underlying XML around that section — a non-zero offset is what flips the read into XML mode. Copy an XML fragment from that output as `old_string` and call `edit_block(file_path, old_string, new_string)` with the rewritten XML. The user gets back real `.xlsx` and `.docx` files, not regenerated approximations. ### "Generate the Q3 report as a PDF" Compose markdown content (header, table, charts via embedded HTML), then call `write_pdf` to render it to a new PDF file. The MCP's `write_pdf` tool description specifies the exact parameters and filename rules — follow that. ### "Insert a cover page into this PDF" `write_pdf` also supports modifying existing PDFs via an operations array (insert / delete pages). Use it for existing-PDF edits that produce a new PDF — adding a cover page, removing a section, merging in content from another file. See the `write_pdf` tool description for the operation shapes and parameter rules. ### "Analyze this 200MB CSV" `start_process("python3 -i", timeout_ms=...)` opens a Python REPL and returns a PID. `interact_with_process(pid, "import pandas as pd; df = pd.read_csv('/abs/path.csv')")` loads it once. Every subsequent question — `df.describe()`, `df.groupby('col').size()`, plot a chart — runs in the same already-loaded REPL. Libraries don't re-import, the dataframe doesn't re-load. The MCP itself recommends this workflow for any local data-file analysis. ### "Run a quick Node script" `start_process("node:local", timeout_ms=...)` opens a stateless Node execution mode on the MCP server itself — ES imports supported. `start_process` opens the runner; each piece of JS is sent via `interact_with_process(pid, "<your JS here>")` and runs independently (no shared state between calls). Good for one-shot transformations where keeping a long-lived REPL alive isn't worth it. Don't try to put code into the `start_process` command argument — only the runner type (`node:local`) goes there. ### "Explain this codebase" `list_directory(path=repo_root, depth=3)` for shape. `start_search(pattern="export ", path=repo_root, searchType="content")` to find the public surface. `read_multiple_files(paths=[entrypoints])` for the actual code. The agent can keep narrowing without re-asking the user where to look. ### "Organize my Downloads folder" Resolve the path to absolute first (e.g., `/Users/<user>/Downloads`, not `~/Downloads`). Then `list_directory(path="/Users/<user>/Downloads", depth=1)` to see what's there. `start_search(pattern="*.pdf", path="/Users/<user>/Downloads", searchType="files")` and similar for other types. `create_directory` for new folders. `move_file` per item. Preview the move plan before executing destructive ops. ### "Onboard me — what was happening last session?" `get_recent_tool_calls(maxResults=200)` returns recent activity with arguments and outputs. `list_sessions` shows still-running terminal sessions. `list_searches` shows in-flight searches. `list_processes` shows what's still alive. Together they reconstruct the work without asking the user to recap. ### "Why isn't the REPL responding?" `list_sessions` — if `Blocked: true`, the REPL is waiting for input rather than hung. `read_process_output(pid, offset=-100)` to see what it last printed (often a prompt). `interact_with_process(pid, "<the input it's waiting for>\n")` unblocks it. ## Core tool inventory Grouped index of the tools an agent reaches for most often. Not exhaustive — the MCP exposes additional config / diagnostics / feedback tools beyond this list. Detailed parameters and return shapes for every tool are in the MCP's own tool descriptions. - **Process / shell:** `start_process`, `interact_with_process`, `read_process_output`, `list_processes`, `list_sessions`, `kill_process`, `force_terminate` - **Files (read/write):** `read_file`, `read_multiple_files`, `write_file`, `edit_block`, `write_pdf` - **Filesystem:** `list_directory`, `get_file_info`, `move_file`, `create_directory` - **Search:** `start_search`, `get_more_search_results`, `list_searches`, `stop_search` - **Diagnostics / config:** `get_recent_tool_calls`, `get_config` ## Conventions **Prefer absolute paths.** Relative paths may fail depending on the working directory, and tilde paths (`~/...`) may not expand in all contexts. Absolute paths are the most reliable; pass them whenever you can. **Allowed-directory scope.** File operations only work inside the user's configured `allowedDirectories`. Expect `[DENIED]` markers in `list_directory` output and rejections from `read_file` / `write_file` when the path is out of scope. Surface the rejected path to the user — don't retry. **When running on macOS:** default shell is zsh. Use `python3` not `python`. Some GNU tools have prefixed names (`gsed` for GNU sed). `brew` is the typical package manager. `open` opens files / apps from the terminal, `mdfind` is the fastest path to exact-filename search via Spotlight. Detect the host platform via `get_config` (or by inspecting `process.platform` / `uname` from a shell) before assuming any of the above — Windows and Linux hosts behave differently. **Pagination.** Long outputs (file reads, process output, search results) all support `offset` and `length`. Negative offsets read from the end (tail mode). Use these instead of dumping huge results into context. - plugins/claude/skills/knowledge-base/SKILL.md (8791 bytes)
--- name: knowledge-base version: 0.1.0 audience: agent description: >- Create and maintain a Markdown knowledge base that any AI agent can read, search, and update. Use when the user wants to start a knowledge base, add or update notes, organize docs/notes for an agent or LLM to consume, build an index of notes, or run a cleanup/maintenance pass on an existing MD knowledge base. Triggers include "knowledge base", "KB", "notes for the agent", "index of notes", "second brain", "docs for AI context", "add a note", "update the KB". --- # Knowledge Base (Markdown, agent-readable) A knowledge base (KB) here is a folder of Markdown files designed so **any** AI agent can navigate it without a vector database: the agent reads one index file, picks the relevant notes by their descriptions, and opens only those. Keep the whole KB readable and the index lean — the index is what gets loaded into context, so it must be high-signal. Apply the rules below when creating a new KB, adding/editing notes, or doing a maintenance pass. When the user's request is ambiguous (new KB vs. add note vs. cleanup), ask which one before acting. ## Core principles (the "why") 1. **Index-first navigation.** The index is a map, not a container. An agent reads `INDEX.md`, selects notes by their one-line descriptions, then opens only those files. No note is "in" the KB unless it's registered in the index. 2. **Atomicity.** One topic per note. If a title needs an "and", it's probably two notes. Atomic notes are easier to find, link, and reuse. 3. **Stable IDs.** Every note has a permanent ID that never changes and is never reused, so links survive renames and moves. 4. **Linked with reason.** When two notes connect, state *why* (prerequisite, supports, contrasts, see-also). Connections carry as much value as the notes. 5. **Lean instructions.** Keep `INDEX.md` instructions short and high-signal — it competes for the agent's context budget. Bodies load on demand. 6. **Structured for retrieval.** Clear H1 title and H2/H3 sections so an agent can grab the relevant slice of a note, not the whole thing. ## Folder structure (nested by topic) ``` knowledge-base/ INDEX.md # entry point: instructions + full note registry topics/ <topic>/ _topic.md # topic map: what this topic covers + its notes <slug>.md # one atomic note assets/ # images / attachments referenced by notes ``` - Topic folders are short, lowercase nouns (`auth`, `billing`, `deploys`). - `_topic.md` is the topic-level map of content (MOC): a short intro plus links to every note in that topic. It is a convenience view; `INDEX.md` remains the source of truth. ## Naming rules - Lowercase **kebab-case**, predictable and greppable: `topics/auth/session-tokens.md`. - No spaces, no uppercase, no dates in filenames (dates live in frontmatter). - The filename slug should match the note's `id` slug portion. ## Required frontmatter (every note) ```yaml --- id: 20260618-session-tokens # ID scheme: YYYYMMDD-slug. Stable. Never reuse or change. title: Session tokens # human title, also the note's H1 tags: [auth, security] # only tags from the controlled list in INDEX.md created: 2026-06-18 updated: 2026-06-18 related: [20260618-auth-flow] # IDs of linked notes summary: One scannable sentence describing what this note covers. --- ``` - `id`: `YYYYMMDD-slug`. Sortable, readable, stable. Different-titled same-day notes differ by slug; if two same-day notes would collide on the same slug, append `-2`, `-3`, … (check the `INDEX.md` registry before assigning). Once assigned, the id is permanent. - `summary`: this exact sentence is what goes in the index registry — write it to help an agent decide whether to open the note. - `updated`: bump it whenever the body changes. ## Note body shape ```markdown # Session tokens > Summary: One sentence (mirrors frontmatter summary). ## Context Why this note exists / when it applies. ## Details The actual content, in short H2/H3 sections. ## Related - [Auth flow](auth-flow.md) — prerequisite: tokens are issued during the auth flow. - [Rate limiting](../api/rate-limiting.md) — see-also: tokens carry the rate-limit key. ``` - Use **relative links** between notes and annotate the relationship in a phrase. - Every link target should also appear in the note's `related` frontmatter. ## INDEX.md (the single source of truth) `INDEX.md` has two parts: operating instructions for agents, and the registry. ```markdown # Knowledge Base — Index ## How to use this KB (for agents) 1. Read this index first. Pick notes by their descriptions; open only those. 2. To answer a question, prefer opening 1–3 specific notes over scanning everything. 3. Cite the note `id` when you use information from it. ## How to update this KB (for agents) - New idea → create a new note (atomic). Same idea changed → edit the note in place and bump `updated`. - Any create / rename / delete MUST update this registry and the topic's `_topic.md` in the same change. - Use only tags from the controlled vocabulary below; add a new tag here before using it. ## Controlled tags `auth`, `security`, `billing`, `api`, `ops` <!-- extend deliberately --> ## Registry ### auth - `20260618-auth-flow` — **Authentication flow** — `topics/auth/auth-flow.md` — How a user session is established end to end. - `20260618-session-tokens` — **Session tokens** — `topics/auth/session-tokens.md` — Token format, lifetime, and rotation. ### billing - `20260618-invoicing` — **Invoicing** — `topics/billing/invoicing.md` — How invoices are generated and sent. ``` Registry line format: `` `id` — **Title** — `path` — one-line description.`` ## _topic.md (topic map) ```markdown # Auth Notes covering authentication, sessions, and access control. - [Authentication flow](auth-flow.md) — how a session is established. - [Session tokens](session-tokens.md) — token format, lifetime, rotation. ``` ## Workflows ### Create a new KB 1. `create_directory` for the folder structure above. 2. `write_file` `INDEX.md` with the instructions block, an empty controlled-tag list, and an empty registry. 3. Add the first topic folder + `_topic.md`, then the first note (each via `write_file`). 4. Register the note in `INDEX.md` and link it from `_topic.md` — `edit_block` both so you touch only the changed lines. ### Add a note 1. Pick or create the topic folder (`list_directory` to see what's there). 2. `write_file` the note (kebab-case slug) with full frontmatter and the body shape. 3. Add cross-links (and mirror them in `related`). 4. Register it in `INDEX.md` and link it in `_topic.md` with `edit_block` — same change. ### Update a note - Same idea, new information → `edit_block` the note in place, bump `updated`, and `edit_block` the registry line if the scope changed. - Genuinely new idea → `write_file` a new atomic note instead of expanding this one. ### Maintenance pass (run on demand) Use `start_search` (ripgrep) for text scans and `get_file_info` / `list_directory` for existence checks — together they make this tractable at scale: - **Orphans** (no *inbound* links — outbound doesn't matter): `start_search` the KB for the note's `id` and filename slug, then discount the self-matches that always exist — the note's own file, `INDEX.md`, and its `_topic.md`. Anything left is a genuine inbound reference; nothing left = orphan, so link it from a relevant note/MOC or archive it. - **Broken links / drift**: don't infer resolution from a text hit — a string existing doesn't mean the file does. Confirm each registry path and `related:` target exists with `get_file_info` (or `list_directory` per topic), and that every file on disk is registered. Use a text compare only for the titles/summaries-out-of-sync half. - **Non-atomic notes**: notes that grew to cover multiple topics → split them. - **Duplicates**: near-identical notes → merge, keep one `id`, redirect links. - **Tag sprawl**: read the controlled list from `INDEX.md`, then `start_search` the frontmatter `tags:` lines and flag any tag not on the list → reconcile. Pull candidates in bulk with `read_multiple_files`, apply fixes with `edit_block`, and report what changed. ## Checklist before finishing any KB edit - [ ] Every new/changed note has complete, valid frontmatter. - [ ] `id` is unique and unchanged; filename slug matches the id slug. - [ ] All links resolve and are mirrored in `related`. - [ ] `INDEX.md` registry and the topic `_topic.md` reflect the change. - [ ] Tags are from the controlled vocabulary. - [ ] `updated` bumped on every changed note. - plugins/claude/skills/obsidian-vault/SKILL.md (8950 bytes)
--- name: obsidian-vault version: 0.1.0 audience: agent description: >- Organize Obsidian vaults with MOCs, wikilinks, frontmatter/properties, dashboards, orphan-note checks, and cleanup workflows. Use ONLY when the user explicitly refers to Obsidian — by naming "Obsidian", an Obsidian "vault", or an Obsidian-specific feature such as wikilinks ("[[ ]]"), the Dataview or Bases plugins, or Obsidian Properties. Within that Obsidian context it covers creating Maps of Content, adding/fixing wikilinks, finding orphan notes, normalizing YAML frontmatter, generating Dataview/Bases dashboards, organizing folders, deduplicating or renaming notes, and preparing the vault for AI use. Do NOT use this skill for generic note-taking, Markdown, or knowledge-base requests that don't mention Obsidian. --- # Obsidian Vault Assistant Help the user organize and maintain an Obsidian vault: build navigation with MOCs and wikilinks, normalize metadata, generate dashboards, find and fix orphans, organize folders, deduplicate/rename, and prepare the vault for AI use. Obsidian-specific facts that shape every rule here: - Links are **wikilinks** resolved by **filename**, not path: `[[Note title]]`. Renaming a note auto-updates links inside Obsidian, but moving files outside Obsidian breaks them — always rename via Obsidian when possible. - Metadata is **Properties** (YAML frontmatter) at the top of a note. - Dashboards come from **Dataview** (query language, read-only, flexible) or **Bases** (native, editable tables, fast on big vaults, properties-only). Before acting, confirm the vault's root folder and whether the user has the Dataview plugin installed (Bases is built in since Obsidian 1.9). When a request is ambiguous (organize vs. clean up vs. dashboard), ask which task. ## Wikilinks - Basic: `[[Three laws of motion]]` — resolves by filename, no extension/path. - Display text (pipe): `[[atomic-habits|James Clear — Atomic Habits]]`. - Heading link: `[[Note#Section]]`. Block link: `[[Note#^block-id]]`. - Embed/transclude: `![[Note]]`, `![[Note#Section]]`, `![[image.png]]`. - Aliases: add an `aliases` property so the note resolves under other names. - Avoid `# | ^ : %` and `[ ]` in filenames — they have special meaning in links. - Prefer wikilinks for internal navigation; use standard Markdown links only if the vault is also published to a tool that can't parse wikilinks. When adding links, also surface **unlinked mentions**: if a note's title appears as plain text in other notes, convert those to wikilinks. ## Maps of Content (MOCs) A MOC is a note that links the related notes on a topic — the vault's navigation layer (more flexible than folders or tags, and needs no institutional knowledge). Conventions: - Name MOCs clearly and tag them: `tags: [moc]` (or a `type: moc` property) so every MOC is itself discoverable. - Keep a top-level **Home / Index MOC** that links to all topic MOCs. - A MOC holds a short intro plus grouped wikilinks; it can be hand-curated or auto-generated with a Dataview/Bases query (see Dashboards). MOC template: ```markdown --- type: moc tags: [moc] updated: 2026-06-18 --- # Auth — Map of Content Notes on authentication, sessions, and access control. ## Core - [[auth-flow]] - [[session-tokens]] ## Related MOCs - [[security-moc]] ``` ## Frontmatter / Properties Add a consistent property block to every note. Recommended baseline: ```yaml --- title: Session tokens aliases: [tokens, session token] tags: [auth, security] type: note # note | moc | dashboard | template | person | project created: 2026-06-18 updated: 2026-06-18 status: evergreen # seedling | growing | evergreen related: ["[[auth-flow]]"] --- ``` Rules: - Use a **controlled tag vocabulary** — decide tags up front and reuse them; nested tags (`auth/tokens`) are fine. Don't let tags sprawl. - `tags` use no `#` in frontmatter. Dates in ISO `YYYY-MM-DD`. - Keep property **names and types consistent across the vault** — Bases and Dataview both depend on this. When normalizing, pick one name per concept (e.g. `created`, not `created`/`date`/`Created`) and migrate the rest. ## Dashboards Pick the engine based on the user's setup: **Bases** (native, editable, fast — best for operational boards): - Create a `.base` file or a `base` code block; it builds table/board views from properties. Each cell edits the underlying note's frontmatter. - Use for task lists, reading lists, project pipelines, anything point-and-click. **Dataview** (plugin, read-only, most flexible — best for reports/auto-MOCs): ```dataview TABLE status, updated, tags FROM #auth WHERE type = "note" SORT updated DESC ``` Auto-MOC of everything in a topic: ```dataview LIST FROM #auth WHERE type != "moc" SORT file.name ASC ``` Recently updated: ```dataview TABLE updated FROM "" WHERE updated >= date(today) - dur(7 days) SORT updated DESC ``` Note: large vaults can lag with heavy Dataview queries — prefer Bases there. ## Orphan notes & link hygiene An orphan is a note with no inbound or outbound links. To find and fix: 1. **From Desktop Commander** (no app needed, scales to big vaults): `start_search` the vault for `[[ ]]` links to each note's title — zero hits means no inbound links (an *unlinked* note); to confirm a true orphan (no inbound **and** no outbound), also scan the note's own body for `[[...]]`. The same searches surface **unlinked mentions** (the title as plain text, not wrapped in `[[ ]]`) and **broken links** (a `[[target]]` whose file is missing). 2. **Graph view** (Cmd/Ctrl+G): orphans float as isolated dots at the edges. 3. **Dataview** query for notes with no links: ```dataview LIST WHERE length(file.inlinks) = 0 AND length(file.outlinks) = 0 ``` 4. For each orphan: link it from a relevant MOC/note (`edit_block` to insert the wikilink), tag it `#needs-link` for a batch pass, or archive if obsolete. 5. Convert unlinked mentions into real wikilinks and fix broken links with `edit_block`; resolve the rest from Obsidian's right sidebar. ## Folder organization - Folders are for coarse buckets; **MOCs + tags do the real organizing**. Don't over-nest folders. - A workable layout: ``` 00-inbox/ # unsorted captures 10-notes/ # atomic notes 20-mocs/ # maps of content 30-projects/ 90-assets/ # images/attachments 99-archive/ templates/ ``` - Set the attachment folder in Settings so embeds land in `90-assets/`. - **Moves/renames must happen inside Obsidian** so wikilinks update automatically — do **not** use `move_file` for these, it breaks every `[[link]]`. From Desktop Commander, only edit *content* (`edit_block` / `write_file`); leave moving and renaming to the user in the app. ## Deduplicate & rename - **Duplicates**: `start_search` titles/aliases to find near-identical notes; merge into one, keep the most-linked filename, copy unique content with `edit_block`, then `start_search` for inbound `[[links]]` to the discarded note and repoint them before deleting it. - **Renames**: do them inside Obsidian (Rename note / `F2`) so backlinks update — not via `move_file`. Keep an `aliases` entry for the old name if it was widely referenced. - Standardize filenames: pick one convention (kebab-case or Title Case) and apply it consistently; avoid the special characters listed above. ## Prepare the vault for AI use - Ensure **consistent frontmatter** (same property names/types) so an agent can filter and reason over metadata. - Maintain a **Home/Index MOC** as the single entry point an agent reads first. - Write a one-line `summary`/`description` property per note for quick scanning. - Reduce orphans and broken links so the link graph is a reliable map. - Keep notes **atomic** (one idea each) — easier for an agent to retrieve and cite. - Consider exporting wikilinks to standard Markdown links if the AI tool can't parse `[[ ]]`. ## Workflows - **Build navigation**: `write_file` topic MOCs → `edit_block` notes to link them in → refresh the Home MOC → convert unlinked mentions. - **Normalize metadata**: `read_multiple_files` to audit properties → pick canonical names → `edit_block` each note → add missing baseline properties. - **Cleanup pass**: `start_search` for orphans, broken links, and unlinked mentions → dedupe → report what changed (renames stay in Obsidian). - **Dashboard**: confirm Dataview vs. Bases → `write_file` the view from properties/tags. ## Checklist before finishing - [ ] New/changed notes have consistent frontmatter (canonical property names). - [ ] Renames/moves done inside Obsidian; no links broken. - [ ] New notes linked from at least one MOC or note (no new orphans). - [ ] Tags drawn from the controlled vocabulary. - [ ] Dashboards reference properties/tags that actually exist. - [ ] `updated` bumped on changed notes. - plugins/claude/skills/terminal/SKILL.md (10761 bytes)
--- name: terminal version: 0.1.0 audience: agent description: >- Use Desktop Commander for terminal and command-line work, especially anything that needs a shell whose state persists across turns: Python/Node REPLs, database shells, dev servers and other long-running processes, SSH into remote machines, and Windows PowerShell. Also handles everyday terminal tasks — navigating folders, choosing the right command for the user's shell (PowerShell, cmd, bash, zsh), running Docker/curl/cloud-CLI commands, inspecting processes and ports, and saving recurring workflows as scripts — even when the user doesn't say "Desktop Commander" or "terminal." Reach for it on pasted errors like "command not found", "permission denied", "EADDRINUSE", "address already in use", "npm ERR!", "ModuleNotFoundError", or "ENOENT", and on intents like "what's using port 3000", "kill that process", "ssh into my server", or "why won't my dev server start". Works on Windows, macOS, and Linux. Never run destructive commands without explicit confirmation. --- # Terminal Command Assistant Be a calm, safe, cross-platform terminal copilot. The user may be an expert or may be opening a terminal for the first time — read their cues and match them. Explain what a command does in plain language, run it through Desktop Commander, read the real output, and explain the result. The user's machine is the source of truth; never assume the OS, shell, or installed tools — detect them. ## 1. Detect the environment first (do this before suggesting commands) Different OSes and shells need different commands. Before recommending or running anything non-trivial, call **`get_config`** (Desktop Commander) and read `systemInfo`: - `platformName` / `isWindows` / `isMacOS` / `isLinux` — which OS. - `defaultShell` and `uiHints.availableShells` — which shell to target. - `pythonInfo`, `nodeInfo` — whether Python/Node exist and their versions. - `blockedCommands` — commands Desktop Commander refuses to run (see §7). - `allowedDirectories` — `[]` means full access; otherwise commands/paths are scoped to those directories. This one cheap call prevents the most common mistake: handing a macOS user a PowerShell command, or assuming `python3` exists when it doesn't. Cache what you learn for the rest of the session; re-check only if something seems off. ## 2. Choosing the right command for the shell Pick syntax by the detected shell, not by habit. Common equivalents: | Task | bash / zsh (macOS, Linux) | PowerShell (Windows) | cmd (Windows) | |---|---|---|---| | List files | `ls -la` | `Get-ChildItem` / `ls` | `dir` | | Current dir | `pwd` | `Get-Location` / `pwd` | `cd` | | Find file | `find . -name "*.log"` | `Get-ChildItem -Recurse -Filter *.log` | `dir /s *.log` | | Search text | `grep -r "TODO" .` | `Get-ChildItem -Recurse \| Select-String TODO` | `findstr /s TODO *` | | Env var | `echo $HOME` | `$env:USERPROFILE` | `echo %USERPROFILE%` | | Set env (session) | `export KEY=val` | `$env:KEY="val"` | `set KEY=val` | | Delete file | `rm file` | `Remove-Item file` | `del file` | | Copy | `cp a b` | `Copy-Item a b` | `copy a b` | | Path separator | `/` | `\` (or `/`) | `\` | Notes that bite people: Windows paths use `\` and often need quoting when they contain spaces; PowerShell and bash quote/escape differently; `~` expands in bash/zsh but not in cmd. When in doubt, prefer the cross-platform tool the user already has (e.g. `python`, `node`, `git`) over shell-specific syntax. ## 3. Running commands with Desktop Commander **Always use absolute paths.** Relative paths depend on a working directory that isn't carried between calls, so they fail unpredictably. - **One-shot commands** → `start_process` with the command and a timeout. It returns output and a PID. If output is truncated or the process is still running, call `read_process_output` with the PID for more. - **Long-running / interactive sessions** (REPLs, SSH, DB shells, `npm create`, anything that prompts) → `start_process` to launch, then `interact_with_process(pid, "...")` to send input and `read_process_output` to read responses. End with `force_terminate` if it won't exit on its own. - Navigation is just inspection: use `list_directory` and `get_file_info` rather than relying on a persistent `cd`. If you must `cd`, do it inside the same command (`cd /abs/path && some-command`). ### Interactive REPL pattern (the workhorse) This keeps state across calls and is the right way to drive Python, Node, a database shell, or SSH: ``` start_process("python3 -i") # or "node -i", "ssh user@host", "psql ..." interact_with_process(pid, "import pandas as pd") interact_with_process(pid, "df = pd.read_csv('/abs/path/data.csv')") interact_with_process(pid, "print(df.describe())") read_process_output(pid) # pull more output if needed ``` ## 4. Running specific CLIs - **Python**: prefer `python3 -i` as an interactive session for multi-step work; for a quick one-off use `python3 /abs/script.py`. Check `pythonInfo.command` from §1 (`python` vs `python3`). - **Node**: `node -i` for an interactive session, `node /abs/script.js` for a one-off. `npm`/`pnpm`/`yarn` installs can be slow — give a generous timeout and read remaining output rather than assuming failure. - **Docker**: `docker ps`, `docker logs <id>`, `docker compose up -d`. Long builds/runs: launch then poll with `read_process_output`. Treat `docker system prune`, `docker rm`, `docker volume rm` as destructive (§7). - **SSH**: launch with `start_process("ssh user@host")`, then drive it with `interact_with_process`. Remote destructive commands deserve the same confirmation rules as local ones. - **curl / HTTP**: fine for inspection (`curl -i https://...`). Be careful with anything that pipes a downloaded script straight into a shell (`curl ... | sh`) — that's untrusted code execution; show it and confirm first. - **Cloud CLIs** (`aws`, `gcloud`, `az`): read-only commands (`describe`, `list`, `get`) are safe to run; anything that creates, deletes, scales, or changes IAM is high-impact — preview the exact command and confirm. Never echo secrets or credentials into the terminal output. ## 5. Inspecting processes and ports - **Processes**: `list_processes` (Desktop Commander) for a structured view, or `ps aux` (Unix) / `Get-Process` (PowerShell). Stop one with `kill_process` by PID (`force_terminate` ends a session you started). - **What's using a port**: - macOS/Linux: `lsof -i :3000` or `lsof -nP -iTCP -sTCP:LISTEN` - Linux: `ss -ltnp` - Windows PowerShell: `Get-NetTCPConnection -LocalPort 3000` - Windows cmd: `netstat -ano | findstr :3000` (then map the PID) - When killing a process, confirm the PID belongs to what the user thinks it does — show the process line before terminating it. ## 6. Explaining errors in plain English When a command fails, don't just retry blindly: 1. Read the **actual** error text from the process output — the real cause is usually in the last few lines, not the first. 2. Name the cause in one plain sentence (e.g. "the port's already taken", "that package isn't installed", "permission denied because the file's owned by root"). 3. Give the concrete fix command for *their* shell, and explain what it does. 4. If the fix is risky or guesswork, say so and offer the safe diagnostic first. Common ones worth recognizing fast: `command not found` / `not recognized` (not installed or not on PATH), `EADDRINUSE` (port in use — see §5), `permission denied` / `EACCES` (ownership/permissions, not always fixable with elevation), `ENOENT` (path doesn't exist — check absolute path), `npm ERR!` blocks (read the resolved error line), non-zero exit codes (report the code). ## 7. Safety: destructive commands and chaining Desktop Commander already refuses a built-in `blockedCommands` list (things like `sudo`, `mkfs`, `format`, `dd`, `fdisk`, `shutdown`, `reboot`, `diskpart`, `reg`, `net`). Read the live list from `get_config`; don't assume it. Beyond that list, treat these as **destructive — never run without the user's explicit confirmation**, even if they'd technically succeed: - Recursive/forced deletes: `rm -rf`, `Remove-Item -Recurse -Force`, `del /s`, `rd /s`. - Overwriting or moving over existing files; wildcard deletes. - Disk/format/partition operations. - `git reset --hard`, `git clean -fd`, `git push --force` (history/data loss). - Database drops/truncates: `DROP`, `TRUNCATE`, `DELETE` without a `WHERE`. - `chmod -R` / `chown -R` on broad paths, `killall`, mass process kills. - Cloud deletes/scaling/IAM changes; `docker ... prune`/`rm`/volume removal. - Anything piping remote content into a shell (`curl ... | sh`). For these: show the exact command, explain in one line what it will irreversibly do, and wait for a clear "yes". Prefer a dry run or a read-only check first (e.g. `ls` the glob before `rm` it, `--dry-run` where the tool supports it). **Chaining safely**: `&&` runs the next only if the previous succeeded; `;` runs regardless; `||` runs only on failure. PowerShell historically uses `;` to sequence (it supports `&&`/`||` in v7+, but not all hosts). Keep chains short. If any step in a chain is destructive, don't chain it — run the safe steps, confirm, then run the risky one alone so a failure can't cascade. ## 8. Turning repeated workflows into scripts When the user runs the same sequence repeatedly (or asks to "save this"), offer to capture it as a script instead of retyping: - Unix → a `.sh` file with `#!/usr/bin/env bash` (or `zsh`), `set -euo pipefail` for safety, comments explaining each step; make it executable (`chmod +x`). - Windows → a `.ps1` (PowerShell) script with comment-based help at the top. - Write the file with `write_file` to an absolute path the user chooses, echo it back, and explain how to run it. Parameterize the bits that change (paths, names) rather than hard-coding. - If the workflow needs to run on both Windows and Unix, either keep the logic in a cross-platform tool (a small Python/Node script) or provide both a `.sh` and a `.ps1`. Don't pretend one shell script runs everywhere. Keep scripts small and readable — the goal is something the user can open, trust, and edit later, not a black box. ## Operating etiquette - Preview risky commands before running; run read-only inspection first. - Use absolute paths; respect `allowedDirectories`. - Never print secrets, tokens, or passwords into output; redact if they appear. - Match the user's level: explain jargon when they seem new, stay terse when they're fluent. - After a failed command, diagnose from the real output before retrying. - plugins/cursor/skills/ai-tools-setup/references/claude-desktop-mcp.md (3767 bytes)
# Claude Desktop & MCP Servers How to install Claude Desktop, add MCP servers, and inspect / validate / repair MCP configuration files. This is the most common and most mechanical task — high success rate when done carefully. ## Config file locations MCP-capable clients each keep their own config. Find the right one first. | Client | macOS | Windows | |---|---|---| | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | `%APPDATA%\Claude\claude_desktop_config.json` | | Claude Code (per project) | `<project>/.claude/mcp.json` or `.mcp.json` | same | | LM Studio | `~/.lmstudio/mcp.json` | `%USERPROFILE%\.lmstudio\mcp.json` | | Cursor | `~/.cursor/mcp.json` | `%USERPROFILE%\.cursor\mcp.json` | If the file doesn't exist yet, create it with a minimal valid skeleton: ```json { "mcpServers": {} } ``` ## Anatomy of an MCP server entry A stdio server entry has a launch `command`, `args`, and optional `env`: ```json { "mcpServers": { "example": { "command": "npx", "args": ["-y", "@scope/some-mcp-server"], "env": { "SOME_API_KEY": "..." } } } } ``` Notes: - On Windows, `npx` sometimes must be invoked as `cmd /c npx ...` — if a server fails to launch on Windows but works on macOS, try wrapping the command. - Use absolute paths for local scripts; `~` is not expanded inside JSON. - Secrets belong in `env` here (or the server's own config), never pasted into chat. ## Add a server end-to-end 1. **Confirm prerequisites.** Most MCP servers need Node (check `node -v`; many need 18+). Some need Python or Docker. Install the runtime if missing. 2. **Back up the config** (`claude_desktop_config.json` → `claude_desktop_config.json.bak`). 3. **Add the server block** under `mcpServers`. Preserve existing entries. 4. **Validate the JSON** (parse it; check for trailing commas, unescaped backslashes in Windows paths, missing quotes). 5. **Fully restart the client.** Claude Desktop must be quit and reopened — a window reload is not enough. 6. **Verify.** Confirm the server appears and its tools are listed. If the client shows a "failed" server, read its MCP log. ## Inspect, validate, repair (the core job) When a user says MCP "isn't working," diagnose in this order: 1. **Read the config file** and pretty-print it. Most breakages are here. 2. **Validate JSON.** The frequent culprits: - trailing comma after the last entry - single backslashes in Windows paths (need `\\` or forward slashes) - smart quotes from copy-paste instead of straight quotes - a server block pasted at the wrong nesting level 3. **Check the launch command resolves** — does `command` exist on PATH? Run it manually in a terminal to see the real error. 4. **Check credentials** — is the required `env` key present and valid? 5. **Repair, back up first, restart the client, then re-verify.** ## Connection health check Separate the three failure classes so you fix the right thing: - **Config typo** → client shows the server as failed immediately on start; the JSON or command is wrong. Fix the file. - **Server down / crashes** → server starts then exits; running the command manually reproduces the crash. Fix deps/runtime. - **Auth failure** → server starts and lists tools, but calls fail with 401/403. Fix the API key/token. ## Claude Desktop install If Claude Desktop itself isn't installed, point the user to the official download and confirm the app launches before touching MCP config. Don't side-load from unofficial mirrors. ## Safety - Only add MCP servers from sources the user trusts; an MCP server runs with the user's privileges. - Back up before editing; redact secrets in summaries; restart the client to apply changes. - plugins/cursor/skills/ai-tools-setup/references/hermes.md (3902 bytes)
# Hermes **Disambiguate first — "Hermes" means two different things:** 1. **Hermes Agent** — the self-improving AI agent framework built by Nous Research (a learning loop that creates/improves skills, persistent memory, runs across many platforms). This is almost always what users mean when they say "set up Hermes." Docs: https://hermes-agent.nousresearch.com/docs/ 2. **Hermes 3 (and other Hermes models)** — Nous Research's open-weight LLMs. "Set up Hermes 3" usually just means running a local model: `ollama pull hermes3` then `ollama run hermes3`. If that's the goal, treat it as ordinary local-model setup and stop here. The rest of this file covers **Hermes Agent**. MIT licensed. For current commands, fetch the docs (there's also `/docs/llms.txt` for a compact index). ## Install **Desktop app (Windows/macOS):** download the Hermes Desktop installer from https://hermes-agent.nousresearch.com/ and run it (installs CLI + desktop app). **CLI only:** ```bash # Linux / macOS / WSL2 / Android (Termux) curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` ```powershell # Windows (native), in PowerShell iex (irm https://hermes-agent.nousresearch.com/install.ps1) ``` See the full Installation Guide for what the installer does, per-user vs. root layout, and Windows notes. ## Fastest path to a working agent ```bash hermes setup --portal ``` One OAuth via **Nous Portal** covers a model plus the four Tool Gateway tools (web search, image generation, TTS, browser). This is the smoothest first run — recommend it unless the user specifically wants their own provider keys. ## Providers & config Hermes works with **Nous Portal, OpenRouter, OpenAI, or any compatible endpoint**. Configuration lives in Hermes' config file (see the Configuration docs). Common requests: - Wire OpenRouter / OpenAI / a custom endpoint with the user's own key — verify the key works before going further. - "Use my workspace Gemini / no API cost" and similar — set the matching provider/model in config; confirm the model ID is current and supported. - If a Portal login code is rejected, re-run `hermes setup --portal` and check the user is pasting the current code. ## Key features to configure - **Personality (`SOUL.md`)** — defines the agent's default voice/tone. Users often ask to generate or update it. Keep it a plain Markdown persona file. - **Memory** — persistent, grows across sessions; mostly automatic. - **Skills** — procedural memory the agent creates and reuses; compatible with the open agentskills.io standard, so skills are portable. - **MCP integration** — Hermes can connect to MCP servers and filter their tools. For config-file mechanics, see `claude-desktop-mcp.md`; for Hermes-side specifics see the docs' MCP page. - **Messaging gateway** — Telegram, Discord, Slack, WhatsApp, Signal, Teams, and 20+ platforms from one gateway. Telegram is the quickest to validate. - **Backends** — Hermes can run on 6 terminal backends: local, Docker, SSH, Daytona, Singularity, Modal. Daytona/Modal give serverless persistence (idle ≈ free). Pick local for a first run; Docker if the user wants isolation. ## Troubleshooting checklist 1. **Install/update stuck** → check the installer/log output; confirm the runtime and PATH; on Windows watch for permission/antivirus interference. Re-run the installer if needed. 2. **"Agent won't respond / got stuck"** → run the generic diagnostic: provider key valid + has credit → model exists and supports tools → process running → read logs for the first real error. 3. **Portal/auth errors** → re-run `hermes setup --portal`; verify the account and code. 4. **Provider model errors (404/402/403)** → switch to a current, available model. See the FAQ & Troubleshooting page in the docs for tool- and platform-specific fixes.
- plugins/cursor/skills/ai-tools-setup/references/openclaw.md (3867 bytes)
# OpenClaw OpenClaw is a self-hosted, multi-channel **gateway for AI agents** — one Gateway process bridges chat apps (Discord, iMessage, Signal, Slack, Telegram, WhatsApp, and more) to an AI agent. MIT licensed. Official docs: https://docs.openclaw.ai/ (append `/index.md` or use the "View as Markdown" links for clean text). Always confirm current commands against the docs — OpenClaw releases often. ## Install & first run Requirements: Node 24 recommended (Node 22.19+ works), plus an API key from a model provider. ```bash # Install npm install -g openclaw@latest # Guided onboarding + install the background service openclaw onboard --install-daemon # Open the browser Control UI openclaw dashboard ``` The Control UI default is `http://127.0.0.1:18789/`. (Some versions/setups use a nearby port — if 18789 doesn't load, check the onboarding output or `openclaw doctor` for the actual port.) Fastest way to chat from a phone: connect the **Telegram** channel. ## Config - Main config lives at `~/.openclaw/openclaw.json`. - With no config, OpenClaw uses its bundled agent runtime with per-sender sessions. - Lock-down basics: channel allowlists (e.g. `channels.whatsapp.allowFrom`) and group mention rules. Run the built-in diagnostics whenever something is off: ```bash openclaw doctor ``` If it reports "Config invalid," fix the JSON (back it up first) and re-run. ## Providers & models (the most common pain) OpenClaw needs a model provider configured. Recurring issues and fixes: - **"No API key found for provider X"** — auth is configured per agent. Add the provider's credentials for the active agent (via onboarding/`openclaw agents`), or copy the auth profile from the main agent. Confirm the key is valid and has credit *before* further setup. - **Model doesn't support tools** — some local models (e.g. certain distilled reasoning models) can't do tool-calling, which the agent needs. Switch to a model that supports tools. - **Local models** — running via Ollama or LM Studio is common for cost reasons. Watch for: the local server not running, the wrong base URL/port, GPU not engaged / high RAM, and prompt-template mismatches (LM Studio "jinja" errors — switch the model's preset/template). See the docs' Models/Providers section. - **Provider churn** — model names get deprecated and accounts get rate-limited or model-blocked. When you hit a 402/403/404 from a provider, switch to a current, available model rather than retrying. For best quality and security the docs recommend the strongest current-gen model available. ## Channels Each chat platform is a "channel" with its own setup (token/pairing). Telegram is the quickest to validate. Configure one channel, confirm a round-trip message, then add others. See https://docs.openclaw.ai/channels. ## Remote access To reach the gateway from outside the machine, use the documented patterns (SSH / tailnet). Tailscale is covered at https://docs.openclaw.ai/gateway/tailscale. Avoid exposing the dashboard directly to the public internet. ## Troubleshooting checklist 1. `openclaw doctor` — start here. 2. **Gateway `Unauthorized`** at the dashboard URL → the gateway token/auth isn't set or the URL/port is wrong; re-check onboarding output and config. 3. **Connects but `disconnected (1006): no reason`** on first message → almost always a provider/model problem (missing key, unsupported model), not the network. Run the provider/model checks above. 4. **Module/runtime errors** → confirm Node version; reinstall if needed. 5. Read logs with `openclaw logs --follow`. ## Uninstall / cleanup - Stop the service/daemon, then `npm uninstall -g openclaw`. - Remove residual files in `~/.openclaw/` (back up first if it holds config the user may want). - Disable any autostart entry created during onboarding.
- plugins/cursor/skills/ai-tools-setup/SKILL.md (5759 bytes)
--- name: ai-tools-setup version: 0.1.0 audience: agent description: >- Set up, connect, validate, and repair Claude Desktop and MCP servers using Desktop Commander — inspecting and fixing mcp.json / claude_desktop_config.json, getting MCP servers to connect, and diagnosing local AI tooling. Use when a user wants to install, configure, connect, validate, or fix Claude Desktop, an MCP server, an MCP config file, or a local AI agent/gateway. Trigger on the symptoms that actually bring people in: "Claude can't see my tools", "my MCP server isn't showing up", "tools aren't loading in Claude", "add an MCP server", "my MCP isn't connecting", "fix my Claude Desktop config", "the agent won't respond", "wire up Ollama / LM Studio", "restart Claude Desktop". Also covers local agent gateways like OpenClaw and Hermes. --- # AI Tools Setup Assistant Help users install, configure, and repair AI tooling on their own machine using Desktop Commander's file and terminal tools. The work is usually **configure-and-troubleshoot**, not clean installs — assume something already exists and may be half-broken. ## Golden rules (read before doing anything) 1. **Detect the OS and shell first.** Read `get_config` and use its `systemInfo` and `allowedDirectories` — file paths, commands, and config locations differ across macOS, Windows, and Linux, so confirm the platform before assuming anything. 2. **Verify the model/API key works before you build.** The most common reason these sessions dead-end is a provider auth or billing error discovered *after* a lot of setup work. Make one tiny test call with `start_process` (a quick curl to the provider) early, and tell the user plainly if the key is invalid or out of credit. 3. **Translate errors, don't dump them.** When a tool returns a raw JSON/HTTP error, explain in one line what it means and what to do next. If a model is missing, deprecated, rate-limited, or doesn't support tool-calling, suggest a concrete working alternative instead of retrying the same thing. 4. **Never echo secrets.** API keys, tokens, and passwords go *into the right config or `.env` file* — never repeated back in chat. If a user pastes a live secret, warn them, use it, and suggest they rotate it if it was shared insecurely. Redact secrets in any output, logs, or summaries you produce. 5. **Back up before you edit.** Copy the config to a `.bak` first with `start_process` (`cp file.json file.json.bak`, or `copy` on Windows), then make the change with `edit_block` so existing entries survive — reach for `write_file` only on a from-scratch config. Validate the JSON after every edit by parsing it with `start_process`. 6. **Verify, then stop.** After a change, actually confirm it worked — use `list_processes` to confirm the process is running and `start_process` (`lsof`/`netstat`) to confirm the port is listening, then check the client reconnected and its tools are listed. Don't declare success on a guess. 7. **Make it repeatable.** Once something works, offer to save the steps as a short note or script so the user can redo it later. ## What this skill covers This skill routes to one of three reference files depending on the task. Read the relevant file before acting — they contain the exact paths, commands, and known failure modes. - **Claude Desktop & MCP servers** — installing Claude Desktop, adding MCP servers, and inspecting / validating / repairing MCP config files (`claude_desktop_config.json`, `.claude/mcp.json`, `~/.lmstudio/mcp.json`, and similar). Also connection health checks. → Read `references/claude-desktop-mcp.md` - **OpenClaw** — a self-hosted multi-channel gateway for AI agents. Install, onboard, wire a model/provider, connect channels (Telegram, Slack, iMessage, etc.), diagnose the gateway, and uninstall. → Read `references/openclaw.md` - **Hermes** — disambiguate first: **Hermes Agent** (the Nous Research self-improving agent framework) vs. **Hermes 3** (just a local LLM you run via Ollama). Install, run `hermes setup --portal`, configure providers, personality (`SOUL.md`), memory/skills, MCP, and messaging. → Read `references/hermes.md` When in doubt about a tool's current behavior, fetch the official docs: OpenClaw — https://docs.openclaw.ai/ · Hermes — https://hermes-agent.nousresearch.com/docs/ ## General workflow 1. **Clarify the goal and platform.** Install vs. configure vs. fix? Which OS? Which tool/client? 2. **Inspect current state.** `read_file` the relevant config files and use `list_processes` to check whether the relevant process/port/service is already running before changing anything. 3. **Read the matching reference file** for exact paths and commands. 4. **Make the smallest change that moves forward**, backing up configs first. 5. **Verify** the result concretely. 6. **Summarize** what changed, where, and how to undo it — with secrets redacted. ## A generic "my agent isn't responding" diagnostic Use this order for OpenClaw, Hermes, or any local agent/gateway: 1. **Provider/auth** — is a valid API key configured for the active provider, and does it have credit? (Most failures stop here.) 2. **Model** — does the chosen model exist, and does it support tool-calling? Local models especially often don't. 3. **Process/port** — is the gateway/daemon actually running and listening on its port? Is another process holding that port? 4. **Connection** — for chat clients/websockets, does it connect but drop on first message? That usually points back to provider/model, not networking. 5. **Logs** — read the tool's logs for the first real error, not the last one.
- plugins/cursor/skills/computer-health-check/references/linux.md (3477 bytes)
# Linux command set Read-only diagnostics, **no sudo**. Targets common distros (Debian/Ubuntu, Fedora, Arch). Some tools (`smartctl`, `upower`) may be absent or need root for full detail — degrade gracefully. ## Collection script (run as one batched process) ```bash bash -c ' echo "== SYSTEM =="; (. /etc/os-release 2>/dev/null; echo "$PRETTY_NAME"); uname -r; uptime -p 2>/dev/null || uptime echo "== HARDWARE =="; echo "CPUs: $(nproc)"; grep -m1 "model name" /proc/cpuinfo | cut -d: -f2 | sed "s/^ //" echo "== DISK =="; df -h / /home 2>/dev/null | grep -v tmpfs echo "== DISK HEALTH =="; lsblk -d -o NAME,SIZE,ROTA,MODEL 2>/dev/null echo "== MEMORY =="; free -h echo "swap:"; swapon --show 2>/dev/null || echo "none" echo "== TOP CPU =="; ps -eo pid,pcpu,pmem,comm --sort=-pcpu | head -n 8 echo "== TOP MEM =="; ps -eo pid,pcpu,pmem,comm --sort=-rss | head -n 8 echo "== BATTERY =="; for b in /sys/class/power_supply/BAT*; do [ -d "$b" ] && { echo "capacity: $(cat $b/capacity 2>/dev/null)%"; echo "health: $(cat $b/health 2>/dev/null)"; cf=$(cat $b/charge_full 2>/dev/null); cd=$(cat $b/charge_full_design 2>/dev/null); [ -n "$cf" ] && [ -n "$cd" ] && echo "wear: $((100*cf/cd))% of design"; }; done echo "== STARTUP =="; echo "enabled user services: $(systemctl --user list-unit-files --state=enabled 2>/dev/null | grep -c enabled)"; ls -1 "$HOME/.config/autostart" 2>/dev/null echo "== STORAGE HOTSPOTS ==" for d in "$HOME/Downloads" "$HOME/.cache" "$HOME/.local/share/Trash"; do [ -d "$d" ] && printf "%s\t%s\n" "$(du -sh "$d" 2>/dev/null | cut -f1)" "${d/#$HOME/~}" done echo "== PACKAGES ==" if command -v apt >/dev/null 2>&1; then echo "apt upgradable: $(apt list --upgradable 2>/dev/null | grep -c upgradable)" elif command -v dnf >/dev/null 2>&1; then echo "dnf updates: $(dnf check-update -q 2>/dev/null | grep -c .)" elif command -v pacman >/dev/null 2>&1; then echo "pacman updates: $(checkupdates 2>/dev/null | wc -l)"; fi echo "== DONE =="' ``` ## How to read it - **Memory:** `free -h` — focus on the `available` column (real headroom) and whether swap `used` is climbing. High swap use with low available = 🟡/🔴. - **Disk health:** `lsblk` confirms devices; full SMART needs `sudo smartctl -H /dev/sdX` (skip — needs root). Report SMART as "not available without elevation" rather than guessing. - **Battery:** the `charge_full / charge_full_design` ratio is the wear %. Skip if no `BAT*`. - **Startup:** `~/.config/autostart` and enabled `--user` units are the actionable third-party items. ## Optional deeper checks (run only if asked) ```bash journalctl -p 3 -b --no-pager | tail -n 30 # recent boot errors (may need group access) du -xh "$HOME" 2>/dev/null | sort -rh | head -n 15 # biggest dirs in home ping -c 4 8.8.8.8 # connectivity ``` ## Cleanup commands (suggest; run only on approval) - **Empty Trash (safe):** `rm -rf "$HOME/.local/share/Trash/"*`. - **User cache (safe, regenerates):** review `du -sh ~/.cache/* | sort -rh | head` then clear specific large entries; avoid blanket deletion. - **Package cache (user action; usually needs sudo):** `apt-get clean`, `dnf clean all`, or `pacman -Sc` — note these typically require root, so suggest rather than run. - **Updates (user action; needs sudo):** `apt upgrade` / `dnf upgrade` / `pacman -Syu`. - **Startup items (user action):** remove `.desktop` files from `~/.config/autostart`, or `systemctl --user disable <unit>`. - plugins/cursor/skills/computer-health-check/references/macos.md (3364 bytes)
# macOS command set All commands here are read-only and run **without sudo**. Verified on macOS 26 / Apple Silicon. ## Collection script (run as one batched process) Run this with `start_process` (timeout ~30s). It prints labeled sections you can parse. ```bash zsh -c ' echo "== SYSTEM =="; sw_vers; echo "uptime:"; uptime echo "== HARDWARE =="; system_profiler SPHardwareDataType 2>/dev/null | grep -Ei "Model Name|Chip|Total Number of Cores|Memory:" echo "== DISK =="; df -h / diskutil info / 2>/dev/null | grep -Ei "SMART|Free Space" echo "== MEMORY =="; vm_stat | head -n 8 echo "swap:"; sysctl -n vm.swapusage echo "== TOP CPU =="; ps -Ao pid,pcpu,pmem,comm -r | head -n 8 echo "== TOP MEM =="; ps -Ao pid,pcpu,pmem,comm -m | head -n 8 echo "== BATTERY =="; pmset -g batt | head -n 2 system_profiler SPPowerDataType 2>/dev/null | grep -Ei "Cycle Count|Condition|Maximum Capacity" echo "== THERMAL =="; pmset -g therm 2>/dev/null | head -n 3 echo "== STARTUP =="; echo "user agents:"; ls -1 "$HOME/Library/LaunchAgents" 2>/dev/null echo "service count: $(launchctl list 2>/dev/null | wc -l | tr -d " ")" echo "== STORAGE HOTSPOTS ==" for d in "$HOME/Downloads" "$HOME/Library/Caches" "$HOME/.Trash" "$HOME/Library/Logs"; do [ -d "$d" ] && printf "%s\t%s\n" "$(du -sh "$d" 2>/dev/null | cut -f1)" "${d/#$HOME/~}" done echo "== PACKAGES ==" command -v brew >/dev/null 2>&1 && echo "brew outdated: $(brew outdated 2>/dev/null | wc -l | tr -d " "), cache: $(du -sh "$(brew --cache)" 2>/dev/null | cut -f1)" || echo "brew: not installed" echo "== CRASH REPORTS =="; ls -1 "$HOME/Library/Logs/DiagnosticReports" 2>/dev/null | wc -l echo "== DONE =="' ``` ## How to read it - **Memory pressure:** page size is 16 KB on Apple Silicon. Healthy = meaningful free+inactive pages and near-zero swap "used". If `vm.swapusage` shows hundreds of MB / GB used, that's 🟡/🔴. - **Battery:** `Maximum Capacity` is the wear indicator; `Condition: Normal` is good. "Service Recommended" is 🔴. Skip battery entirely if `pmset -g batt` shows no internal battery (desktop). - **SMART:** `Verified` = healthy. Anything else → 🔴. - **Startup:** named third-party `LaunchAgents` are the actionable ones (e.g. updaters, helper daemons, redundant DB services). The raw `launchctl` count is mostly Apple system services. ## Optional deeper checks (run only if asked) ```bash softwareupdate -l 2>&1 | head -n 20 # pending OS updates (network, slow) networkQuality 2>/dev/null # internet up/down + responsiveness (slow) mdfind 'kMDItemFSSize > 1073741824' 2>/dev/null | head -n 20 # files >1GB, Spotlight-fast ``` ## Cleanup commands (suggest; run only on approval) - **Empty Trash (safe):** `rm -rf "$HOME/.Trash/"*` — or tell the user to empty it from Finder. - **Homebrew (safe):** `brew cleanup` (removes old versions + cache). Upgrade: `brew upgrade`. - **User caches (safe, regenerate):** clear specific large subfolders of `~/Library/Caches/<app>` — review with `du -sh ~/Library/Caches/* | sort -rh | head` first; never blanket-delete. - **Login items (user action):** System Settings → General → Login Items, or remove the specific `~/Library/LaunchAgents/<name>.plist` only if the user confirms they don't want it. - **OS updates (user action, needs restart):** System Settings → General → Software Update. - plugins/cursor/skills/computer-health-check/references/windows.md (4052 bytes)
# Windows command set Read-only diagnostics via PowerShell. None require admin. Run through `start_process` with `powershell -NoProfile -Command "..."` (or `pwsh`). Keep outputs bounded with `Select-Object`. ## Collection script (run as one batched process) ```powershell powershell -NoProfile -Command " Write-Output '== SYSTEM =='; (Get-CimInstance Win32_OperatingSystem | Select Caption,Version,LastBootUpTime | Format-List | Out-String).Trim() Write-Output '== HARDWARE =='; (Get-CimInstance Win32_ComputerSystem | Select Manufacturer,Model,@{n='RAM_GB';e={[math]::Round($_.TotalPhysicalMemory/1GB,1)}} | Format-List | Out-String).Trim() Write-Output '== DISK =='; Get-CimInstance Win32_LogicalDisk -Filter 'DriveType=3' | ForEach-Object { '{0} {1}% free ({2:N1} of {3:N1} GB)' -f \$_.DeviceID, [math]::Round(\$_.FreeSpace/\$_.Size*100), (\$_.FreeSpace/1GB), (\$_.Size/1GB) } Write-Output '== DISK HEALTH =='; (Get-PhysicalDisk | Select FriendlyName,HealthStatus,OperationalStatus | Format-Table -Auto | Out-String).Trim() Write-Output '== MEMORY =='; \$os=Get-CimInstance Win32_OperatingSystem; '{0:N1} GB free of {1:N1} GB' -f (\$os.FreePhysicalMemory/1MB),(\$os.TotalVisibleMemorySize/1MB) Write-Output '== TOP CPU =='; (Get-Process | Sort CPU -Desc | Select -First 8 Name,CPU,@{n='MB';e={[math]::Round(\$_.WS/1MB)}} | Format-Table -Auto | Out-String).Trim() Write-Output '== TOP MEM =='; (Get-Process | Sort WS -Desc | Select -First 8 Name,@{n='MB';e={[math]::Round(\$_.WS/1MB)}} | Format-Table -Auto | Out-String).Trim() Write-Output '== BATTERY =='; (Get-CimInstance Win32_Battery | Select EstimatedChargeRemaining,BatteryStatus | Format-List | Out-String).Trim() Write-Output '== STARTUP =='; (Get-CimInstance Win32_StartupCommand | Select Name,Location | Format-Table -Auto | Out-String).Trim() Write-Output '== STORAGE HOTSPOTS =='; \$d=\$env:USERPROFILE; foreach(\$p in 'Downloads','AppData\Local\Temp'){ \$f=Join-Path \$d \$p; if(Test-Path \$f){ \$s=(Get-ChildItem \$f -Recurse -EA SilentlyContinue | Measure Length -Sum).Sum; '{0:N1} GB {1}' -f (\$s/1GB), \$p } } Write-Output '== PACKAGES =='; if(Get-Command winget -EA SilentlyContinue){ (winget upgrade 2>\$null | Measure-Object -Line).Lines } else { 'winget: n/a' } Write-Output '== DONE ==' " ``` ## How to read it - **Battery health detail:** the deep wear report needs `powercfg /batteryreport` (writes an HTML file to disk) — run only on request, then read the generated file. `Win32_Battery` gives charge %, not wear. Skip battery on desktops (no `Win32_Battery` instance). - **Disk health:** `HealthStatus = Healthy` is 🟢; `Warning`/`Unhealthy` is 🔴. - **Memory:** compare free vs total; sustained <10% free under load is 🟡/🔴. Pagefile thrash shows up as high disk + low free RAM. - **Startup:** `Win32_StartupCommand` plus the Run registry keys are the actionable third-party items. - **Packages:** the winget value is a raw output-line count, not an exact upgrade count — read it as "updates pending or not," and run `winget upgrade` for the real list. ## Optional deeper checks (run only if asked) ```powershell powercfg /batteryreport /output "$env:TEMP\battery.html" # then read the file for wear % Get-WindowsUpdate # if PSWindowsUpdate module present Test-Connection -Count 4 8.8.8.8 # basic connectivity ``` ## Cleanup commands (suggest; run only on approval) - **Empty Recycle Bin (safe):** `Clear-RecycleBin -Force` (PowerShell). - **Temp files (safe, regenerate):** remove contents of `$env:TEMP` — show size first with `(Get-ChildItem $env:TEMP -Recurse -EA SilentlyContinue | Measure Length -Sum).Sum/1GB`. - **Package upgrades (user action):** `winget upgrade --all` (may prompt / need elevation per app). - **Startup items (user action):** Task Manager → Startup tab, or Settings → Apps → Startup. - **Windows updates (user action, needs restart):** Settings → Windows Update. - **Disk Cleanup (user action):** `cleanmgr` for system-level reclaim. - plugins/cursor/skills/computer-health-check/SKILL.md (8532 bytes)
--- name: computer-health-check version: 0.1.0 audience: agent description: >- Run a comprehensive, read-only health check on the user's computer and return a scored chat summary with prioritized, plain-English recommendations and safe cleanup suggestions. Use this whenever the user wants to check their computer's health, speed it up, free up / reclaim disk space, find what's eating CPU / memory / storage, check battery health and wear, audit login & startup items, see pending updates, or asks for a "tune-up", "checkup", "system report", "health check", or "is my Mac/PC/laptop healthy". Trigger even on casual phrasing like "my laptop feels slow", "why is my fan so loud", "my computer is laggy", "running out of space", or "clean up my machine". Works on macOS, Windows, and Linux. This is a Desktop Commander skill: it relies on a real local shell (start_process / interact_with_process) and is strictly read-only by default — it never needs sudo and only performs cleanups the user explicitly approves. --- # Computer Health Check ## What this skill does Give the user a fast, trustworthy picture of their computer's health and a short list of actions worth taking — the way a good technician would: look first, explain plainly, fix only with permission. It runs entirely through Desktop Commander's local shell, gathers a batch of **read-only** diagnostics, scores each area, prints a concise summary **in the chat**, and then offers cleanup suggestions the user can approve one by one. ## The safety contract (read this first) This is the part that makes users trust the skill, so honor it strictly: - **Read-only by default.** The collection phase only *observes* (sizes, counts, status). It changes nothing. - **Never use `sudo` or elevation.** DC blocks `sudo`, `shutdown`, `reboot`, `dd`, `mount`, `mkfs`, `diskpart`, etc. for good reason. Every check below is designed to work without them. If something seems to need elevation, skip it and say so — don't try to work around the block. - **Cleanups are opt-in.** You may *suggest* cleanups freely, but only *execute* one after the user explicitly approves that specific action, and only show the exact command first. - **Prefer reversible, non-destructive actions.** Emptying caches that regenerate, clearing a package-manager download cache, or emptying Trash are fine to offer. Deleting user documents, uninstalling apps, or editing system files are not — suggest those, let the user do them. ## Workflow ### Step 1 — Detect the OS Determine the platform before doing anything else, because the commands differ. - Quickest: read Desktop Commander's config (`get_config`) and use the `systemInfo.isMacOS` / `isWindows` / `isLinux` booleans (or `platformName`) to pick the platform. - Or run `uname` (macOS/Linux) — if it fails, assume Windows. Then open the matching reference file and use its command set: - macOS → `references/macos.md` - Windows → `references/windows.md` - Linux → `references/linux.md` Read **only** the one that matches. Each file contains a single batched collection script plus interpretation notes and cleanup commands. ### Step 2 — Collect (read-only) Run the batched collection script from the reference file with `start_process`. Batching everything into one call is much faster than many small calls and keeps the output tidy. Guidance: - Keep outputs bounded (`head`, `Select-Object -First`, etc.) so a long process list or file listing doesn't flood the response. - Skip the genuinely slow / network checks (full OS-update list, internet speed test) on the first pass unless the user asked about updates or network. Mention they're available. - If a single command errors (e.g., a tool isn't installed), continue — partial data is fine. ### Step 3 — Score each area Rate each category 🟢 Good / 🟡 Watch / 🔴 Act using the rubric below, then compute a simple overall score. Start at 100 and subtract 8 per 🟡 and 18 per 🔴; floor at 0. Report the number and a one-word verdict (90+ Excellent, 75–89 Good, 60–74 Fair, <60 Needs attention). | Area | 🟢 Good | 🟡 Watch | 🔴 Act | |---|---|---|---| | Free disk space | >20% free | 10–20% | <10% | | Disk health (SMART) | Verified / OK / PASSED | — | failing / not supported & errors present | | Memory pressure | low swap, free pages healthy | noticeable swap/compression | heavy swapping, near-zero free | | Battery (laptops) | ≥80% max capacity, Normal | 70–80% | <70% or "Service/Replace" | | Maintenance | uptime <7d, no pending updates | uptime 7–30d or minor updates | uptime >30d or security updates pending | | Startup load | few third-party login items | moderate | many heavy third-party agents | | Live resource hogs | nothing >50% at idle | one sustained heavy process | multiple / runaway processes | Battery is laptop-only — skip it on desktops/VMs. Reclaimable space is reported as an informational figure, not scored. ### Step 4 — Report in the chat Use this exact structure. Keep it tight and scannable — this is the deliverable. ``` 🖥️ Health Check — <Model>, <OS version> Score: <N>/100 (<verdict>) 🟢/🟡/🔴 Storage — <free> free of <total> (<%>). Reclaimable: ~<X> GB 🟢/🟡/🔴 Memory — <one-line state> 🟢/🟡/🔴 Battery — <cycles> cycles, <max capacity>%, <condition> 🟢/🟡/🔴 Maintenance — up <days>d, <updates state> 🟢/🟡/🔴 Startup — <count> login items (<notable ones>) 🟢/🟡/🔴 Right now — top: <proc> <cpu%>, <proc> <cpu%> Top recommendations 1. <highest-impact action> (<expected benefit, e.g. frees ~13 GB>) 2. <next> 3. <next> ``` List at most the 3–5 highest-impact recommendations, ordered by benefit. Don't dump every finding — the goal is signal, not a wall of text. ### Step 5 — Suggest cleanups, execute only on approval For each recommendation that maps to a concrete command (see the reference file's "Cleanup" section), offer it and show the exact command. Then: - **Safe, reversible** (offer to run on a yes): empty Trash, package-manager cache cleanup (`brew cleanup`, `npm cache clean`), clearing a regenerating user cache folder. (On Linux, `apt-get clean` / `dnf clean` need root — suggest, don't auto-run.) - **Needs the user to decide / act** (suggest, don't auto-run): disabling login items, installing OS updates (requires restart), uninstalling apps, deleting files in Downloads. - **Never**: anything requiring sudo/admin, removing system files, disk/partition operations. When the user approves a safe action, run it, then report what changed (e.g., space freed). Re-running Step 2's storage check afterward is a nice confirmation. ## Recommendation rules (findings → advice) These are the high-value mappings; adapt the wording to the platform. - **Uptime > 30 days** → "Restart your computer — it's been up <N> days. A reboot clears memory and applies pending updates." (Highest ROI, lowest effort.) - **Pending OS/security updates** → platform update step; flag security updates as higher priority. - **Free space < 15%** → lead with the biggest reclaimable buckets you measured. - **Large Downloads / Caches / Trash** → empty Trash; review largest Downloads items by name; clear caches that regenerate. - **Package manager has many outdated items / big cache** → `upgrade` + cache cleanup. - **Battery max capacity < 80%** → explain wear is normal; consider a battery service if it's affecting runtime. - **Many third-party startup agents** → name them and suggest disabling the ones the user doesn't recognize/need (point to System Settings / Task Manager — don't edit them directly). - **A process pinned high at idle** → name it and suggest quitting/investigating. ## Notes & pitfalls - **Don't assume — measure.** Always run the commands and report real numbers. Never fabricate sizes, cycle counts, or statuses. - **Bounded output.** Process and file listings can be huge; always cap them. - **Optional deep checks** (mention, run on request): internet speed test, full update list, per-folder disk scan of the whole home directory, crash-report trend analysis. - **Privacy.** This reads local system metadata only. Don't send anything off the machine; the public-IP check is optional and should be labeled. - **Cross-platform parity.** The three reference files mirror the same categories so the report looks the same regardless of OS.
- plugins/cursor/skills/desktop-commander-overview/SKILL.md (12282 bytes)
--- name: desktop-commander-overview description: Use for Desktop Commander MCP capabilities — persistent shells and REPLs, long-running processes, filesystem beyond the workspace, structured files (.xlsx, .docx, .pdf, images) and large local data files such as CSVs, ripgrep search at scale, SSH, or cross-turn state. version: 0.1.0 audience: agent --- # Desktop Commander MCP Desktop Commander gives the agent reach across the user's actual computer — files, folders, terminals, processes, structured documents, and remote machines reachable over SSH. The tools' detailed schemas (parameters, return shapes, format-specific behavior) live in the MCP itself; this skill explains what they enable and how they compose into common workflows. ## What this MCP gives the agent **Persistent shell sessions.** Desktop Commander keeps a started process or session alive across tool calls. Inside a single long-lived shell, REPL, or SSH session, state carries forward — environment variables, working directory, activated virtualenvs, open connections, REPL variables — so the agent can `cd`, activate a venv, then send commands or code into that same session many turns later without re-setup. (Note: separate `start_process` calls open separate sessions and do **not** share shell state with each other; persistence is inside one session, not across them.) **Long-running processes.** Start a dev server, watcher, build, training run, or test suite in the background and keep working. The MCP returns a process handle the agent can tail, interact with, or terminate across many turns. Long-running commands don't need to block the workflow waiting for a foreground command to exit. **Filesystem reach beyond the IDE workspace.** Read, write, move, list, and inspect files anywhere the user has granted scope — Downloads, Documents, project folders outside the IDE, or any other granted folders. Useful for organize-and-clean tasks, batch document work, and any "look at the file my coworker just sent me" request that doesn't fit inside the IDE sandbox. **Surgical edits to existing files.** The `edit_block` tool does exact-string find-and-replace with built-in safety: ambiguous matches fail loudly instead of silently overwriting the wrong thing, and an `expected_replacements` count prevents partial-match disasters. Lower data-loss risk than rewriting whole files based on the slice you happened to read — though a wrong `old_string` or wrong `expected_replacements` can still corrupt content, so review the changed content before considering the edit done. **Binary and structured files handled directly by the MCP.** Excel, DOCX, and PDF are first-class — read and modified through format-specific mechanisms rather than text-only approximations: Excel via cell-range JSON, DOCX via raw-XML edits, PDF via page-level operations on a new output file. The result is the real file in its original format, not a regenerated approximation. Images and PDFs return as viewable content for the agent. **Search at scale.** Streaming, ripgrep-backed search across whole projects or folder trees. The agent picks between filename search and in-file content search, pages through results progressively without flooding context, and runs multiple concurrent searches when the query is ambiguous. **Remote machines via SSH.** A long-lived SSH session inside a persistent shell turns the agent into a real ops tool: connect once, then tail logs, run diagnostics, deploy, or debug across many turns without reconnecting each step. **Process management.** List, inspect, tail, and kill accessible processes (subject to OS permissions). Useful for cleaning up stale dev servers from previous sessions and for diagnosing CPU / memory issues. ## Example workflows Each example names the actual tool sequence. Calls below are written in pseudocode shorthand (`tool_name("arg", flag=value)`); the real tools take object-shaped arguments. Tool descriptions and full parameter sets live in the MCP itself. ### "Debug this production issue" Before running production-impacting SSH commands, explain the intended action and get user confirmation when the risk is non-trivial. `start_process("ssh [email protected]", timeout_ms=...)` opens a long-lived SSH session and returns a PID. `interact_with_process(pid, "tail -f /var/log/app.log\n")` starts streaming logs. Subsequent turns: `read_process_output(pid, offset=-50)` to see the last 50 lines as they arrive, `interact_with_process(pid, "...")` to run diagnostic commands in the same session. `force_terminate(pid)` to close the session when done — for sessions opened by `start_process`, `force_terminate` is the correct cleanup tool; `kill_process` is for arbitrary OS PIDs found via `list_processes`. ### "Deploy this to staging" Before deploys, restarts, migrations, or other environment-changing commands, summarize the action and confirm with the user unless they already explicitly asked for that exact operation. `start_process` for the deploy command (could be a script, an SSH-piped command, or `kubectl`/`gh` etc.). `read_process_output` to track output and surface errors. If the deploy needs an interactive confirmation, `interact_with_process(pid, "yes\n")`. The session stays alive while the agent watches for completion or rollback. ### "Run the dev server and iterate on the API" `start_process("npm run dev", timeout_ms=...)` keeps the server up. The agent then loops: `edit_block` on the route file, `read_process_output(pid, offset=-30)` to see the server's reload, `start_process("curl -s http://localhost:3000/api/...")` for a one-shot test, repeat. The dev server never has to restart between code changes. ### "Refactor across this monorepo" `start_search(pattern="oldFunctionName", path=repo_root, searchType="content")` scopes every call site. `get_more_search_results(sessionId)` pages through. `read_multiple_files(paths=[...])` confirms ambiguous hits in context. `edit_block(file_path, old_string, new_string)` per site, with `expected_replacements` set when the same substring legitimately appears multiple times in one file. Verify by re-running `start_search` on the old name and paging the results with `get_more_search_results(sessionId)` until the run completes — only then can you confirm zero remaining hits. ### "Update the Q3 numbers in this spreadsheet and tweak the summary in the report" `read_file(path="/.../q3.xlsx", sheet="Revenue", range="A1:F50")` returns the existing numbers as a JSON 2D array. `edit_block(file_path="/.../q3.xlsx", range="Revenue!C12:C24", content=[[12345], ...])` updates the cells in place. For the report, DOCX editing is a two-read flow: first `read_file(path="/.../report.docx")` (offset 0) returns the document's outline (headings + paragraph text) so you can locate the summary section. Then `read_file(path="/.../report.docx", offset=N, length=...)` with **`N > 0`** returns the raw underlying XML around that section — a non-zero offset is what flips the read into XML mode. Copy an XML fragment from that output as `old_string` and call `edit_block(file_path, old_string, new_string)` with the rewritten XML. The user gets back real `.xlsx` and `.docx` files, not regenerated approximations. ### "Generate the Q3 report as a PDF" Compose markdown content (header, table, charts via embedded HTML), then call `write_pdf` to render it to a new PDF file. The MCP's `write_pdf` tool description specifies the exact parameters and filename rules — follow that. ### "Insert a cover page into this PDF" `write_pdf` also supports modifying existing PDFs via an operations array (insert / delete pages). Use it for existing-PDF edits that produce a new PDF — adding a cover page, removing a section, merging in content from another file. See the `write_pdf` tool description for the operation shapes and parameter rules. ### "Analyze this 200MB CSV" `start_process("python3 -i", timeout_ms=...)` opens a Python REPL and returns a PID. `interact_with_process(pid, "import pandas as pd; df = pd.read_csv('/abs/path.csv')")` loads it once. Every subsequent question — `df.describe()`, `df.groupby('col').size()`, plot a chart — runs in the same already-loaded REPL. Libraries don't re-import, the dataframe doesn't re-load. The MCP itself recommends this workflow for any local data-file analysis. ### "Run a quick Node script" `start_process("node:local", timeout_ms=...)` opens a stateless Node execution mode on the MCP server itself — ES imports supported. `start_process` opens the runner; each piece of JS is sent via `interact_with_process(pid, "<your JS here>")` and runs independently (no shared state between calls). Good for one-shot transformations where keeping a long-lived REPL alive isn't worth it. Don't try to put code into the `start_process` command argument — only the runner type (`node:local`) goes there. ### "Explain this codebase" `list_directory(path=repo_root, depth=3)` for shape. `start_search(pattern="export ", path=repo_root, searchType="content")` to find the public surface. `read_multiple_files(paths=[entrypoints])` for the actual code. The agent can keep narrowing without re-asking the user where to look. ### "Organize my Downloads folder" Resolve the path to absolute first (e.g., `/Users/<user>/Downloads`, not `~/Downloads`). Then `list_directory(path="/Users/<user>/Downloads", depth=1)` to see what's there. `start_search(pattern="*.pdf", path="/Users/<user>/Downloads", searchType="files")` and similar for other types. `create_directory` for new folders. `move_file` per item. Preview the move plan before executing destructive ops. ### "Onboard me — what was happening last session?" `get_recent_tool_calls(maxResults=200)` returns recent activity with arguments and outputs. `list_sessions` shows still-running terminal sessions. `list_searches` shows in-flight searches. `list_processes` shows what's still alive. Together they reconstruct the work without asking the user to recap. ### "Why isn't the REPL responding?" `list_sessions` — if `Blocked: true`, the REPL is waiting for input rather than hung. `read_process_output(pid, offset=-100)` to see what it last printed (often a prompt). `interact_with_process(pid, "<the input it's waiting for>\n")` unblocks it. ## Core tool inventory Grouped index of the tools an agent reaches for most often. Not exhaustive — the MCP exposes additional config / diagnostics / feedback tools beyond this list. Detailed parameters and return shapes for every tool are in the MCP's own tool descriptions. - **Process / shell:** `start_process`, `interact_with_process`, `read_process_output`, `list_processes`, `list_sessions`, `kill_process`, `force_terminate` - **Files (read/write):** `read_file`, `read_multiple_files`, `write_file`, `edit_block`, `write_pdf` - **Filesystem:** `list_directory`, `get_file_info`, `move_file`, `create_directory` - **Search:** `start_search`, `get_more_search_results`, `list_searches`, `stop_search` - **Diagnostics / config:** `get_recent_tool_calls`, `get_config` ## Conventions **Prefer absolute paths.** Relative paths may fail depending on the working directory, and tilde paths (`~/...`) may not expand in all contexts. Absolute paths are the most reliable; pass them whenever you can. **Allowed-directory scope.** File operations only work inside the user's configured `allowedDirectories`. Expect `[DENIED]` markers in `list_directory` output and rejections from `read_file` / `write_file` when the path is out of scope. Surface the rejected path to the user — don't retry. **When running on macOS:** default shell is zsh. Use `python3` not `python`. Some GNU tools have prefixed names (`gsed` for GNU sed). `brew` is the typical package manager. `open` opens files / apps from the terminal, `mdfind` is the fastest path to exact-filename search via Spotlight. Detect the host platform via `get_config` (or by inspecting `process.platform` / `uname` from a shell) before assuming any of the above — Windows and Linux hosts behave differently. **Pagination.** Long outputs (file reads, process output, search results) all support `offset` and `length`. Negative offsets read from the end (tail mode). Use these instead of dumping huge results into context. - plugins/cursor/skills/knowledge-base/SKILL.md (8791 bytes)
--- name: knowledge-base version: 0.1.0 audience: agent description: >- Create and maintain a Markdown knowledge base that any AI agent can read, search, and update. Use when the user wants to start a knowledge base, add or update notes, organize docs/notes for an agent or LLM to consume, build an index of notes, or run a cleanup/maintenance pass on an existing MD knowledge base. Triggers include "knowledge base", "KB", "notes for the agent", "index of notes", "second brain", "docs for AI context", "add a note", "update the KB". --- # Knowledge Base (Markdown, agent-readable) A knowledge base (KB) here is a folder of Markdown files designed so **any** AI agent can navigate it without a vector database: the agent reads one index file, picks the relevant notes by their descriptions, and opens only those. Keep the whole KB readable and the index lean — the index is what gets loaded into context, so it must be high-signal. Apply the rules below when creating a new KB, adding/editing notes, or doing a maintenance pass. When the user's request is ambiguous (new KB vs. add note vs. cleanup), ask which one before acting. ## Core principles (the "why") 1. **Index-first navigation.** The index is a map, not a container. An agent reads `INDEX.md`, selects notes by their one-line descriptions, then opens only those files. No note is "in" the KB unless it's registered in the index. 2. **Atomicity.** One topic per note. If a title needs an "and", it's probably two notes. Atomic notes are easier to find, link, and reuse. 3. **Stable IDs.** Every note has a permanent ID that never changes and is never reused, so links survive renames and moves. 4. **Linked with reason.** When two notes connect, state *why* (prerequisite, supports, contrasts, see-also). Connections carry as much value as the notes. 5. **Lean instructions.** Keep `INDEX.md` instructions short and high-signal — it competes for the agent's context budget. Bodies load on demand. 6. **Structured for retrieval.** Clear H1 title and H2/H3 sections so an agent can grab the relevant slice of a note, not the whole thing. ## Folder structure (nested by topic) ``` knowledge-base/ INDEX.md # entry point: instructions + full note registry topics/ <topic>/ _topic.md # topic map: what this topic covers + its notes <slug>.md # one atomic note assets/ # images / attachments referenced by notes ``` - Topic folders are short, lowercase nouns (`auth`, `billing`, `deploys`). - `_topic.md` is the topic-level map of content (MOC): a short intro plus links to every note in that topic. It is a convenience view; `INDEX.md` remains the source of truth. ## Naming rules - Lowercase **kebab-case**, predictable and greppable: `topics/auth/session-tokens.md`. - No spaces, no uppercase, no dates in filenames (dates live in frontmatter). - The filename slug should match the note's `id` slug portion. ## Required frontmatter (every note) ```yaml --- id: 20260618-session-tokens # ID scheme: YYYYMMDD-slug. Stable. Never reuse or change. title: Session tokens # human title, also the note's H1 tags: [auth, security] # only tags from the controlled list in INDEX.md created: 2026-06-18 updated: 2026-06-18 related: [20260618-auth-flow] # IDs of linked notes summary: One scannable sentence describing what this note covers. --- ``` - `id`: `YYYYMMDD-slug`. Sortable, readable, stable. Different-titled same-day notes differ by slug; if two same-day notes would collide on the same slug, append `-2`, `-3`, … (check the `INDEX.md` registry before assigning). Once assigned, the id is permanent. - `summary`: this exact sentence is what goes in the index registry — write it to help an agent decide whether to open the note. - `updated`: bump it whenever the body changes. ## Note body shape ```markdown # Session tokens > Summary: One sentence (mirrors frontmatter summary). ## Context Why this note exists / when it applies. ## Details The actual content, in short H2/H3 sections. ## Related - [Auth flow](auth-flow.md) — prerequisite: tokens are issued during the auth flow. - [Rate limiting](../api/rate-limiting.md) — see-also: tokens carry the rate-limit key. ``` - Use **relative links** between notes and annotate the relationship in a phrase. - Every link target should also appear in the note's `related` frontmatter. ## INDEX.md (the single source of truth) `INDEX.md` has two parts: operating instructions for agents, and the registry. ```markdown # Knowledge Base — Index ## How to use this KB (for agents) 1. Read this index first. Pick notes by their descriptions; open only those. 2. To answer a question, prefer opening 1–3 specific notes over scanning everything. 3. Cite the note `id` when you use information from it. ## How to update this KB (for agents) - New idea → create a new note (atomic). Same idea changed → edit the note in place and bump `updated`. - Any create / rename / delete MUST update this registry and the topic's `_topic.md` in the same change. - Use only tags from the controlled vocabulary below; add a new tag here before using it. ## Controlled tags `auth`, `security`, `billing`, `api`, `ops` <!-- extend deliberately --> ## Registry ### auth - `20260618-auth-flow` — **Authentication flow** — `topics/auth/auth-flow.md` — How a user session is established end to end. - `20260618-session-tokens` — **Session tokens** — `topics/auth/session-tokens.md` — Token format, lifetime, and rotation. ### billing - `20260618-invoicing` — **Invoicing** — `topics/billing/invoicing.md` — How invoices are generated and sent. ``` Registry line format: `` `id` — **Title** — `path` — one-line description.`` ## _topic.md (topic map) ```markdown # Auth Notes covering authentication, sessions, and access control. - [Authentication flow](auth-flow.md) — how a session is established. - [Session tokens](session-tokens.md) — token format, lifetime, rotation. ``` ## Workflows ### Create a new KB 1. `create_directory` for the folder structure above. 2. `write_file` `INDEX.md` with the instructions block, an empty controlled-tag list, and an empty registry. 3. Add the first topic folder + `_topic.md`, then the first note (each via `write_file`). 4. Register the note in `INDEX.md` and link it from `_topic.md` — `edit_block` both so you touch only the changed lines. ### Add a note 1. Pick or create the topic folder (`list_directory` to see what's there). 2. `write_file` the note (kebab-case slug) with full frontmatter and the body shape. 3. Add cross-links (and mirror them in `related`). 4. Register it in `INDEX.md` and link it in `_topic.md` with `edit_block` — same change. ### Update a note - Same idea, new information → `edit_block` the note in place, bump `updated`, and `edit_block` the registry line if the scope changed. - Genuinely new idea → `write_file` a new atomic note instead of expanding this one. ### Maintenance pass (run on demand) Use `start_search` (ripgrep) for text scans and `get_file_info` / `list_directory` for existence checks — together they make this tractable at scale: - **Orphans** (no *inbound* links — outbound doesn't matter): `start_search` the KB for the note's `id` and filename slug, then discount the self-matches that always exist — the note's own file, `INDEX.md`, and its `_topic.md`. Anything left is a genuine inbound reference; nothing left = orphan, so link it from a relevant note/MOC or archive it. - **Broken links / drift**: don't infer resolution from a text hit — a string existing doesn't mean the file does. Confirm each registry path and `related:` target exists with `get_file_info` (or `list_directory` per topic), and that every file on disk is registered. Use a text compare only for the titles/summaries-out-of-sync half. - **Non-atomic notes**: notes that grew to cover multiple topics → split them. - **Duplicates**: near-identical notes → merge, keep one `id`, redirect links. - **Tag sprawl**: read the controlled list from `INDEX.md`, then `start_search` the frontmatter `tags:` lines and flag any tag not on the list → reconcile. Pull candidates in bulk with `read_multiple_files`, apply fixes with `edit_block`, and report what changed. ## Checklist before finishing any KB edit - [ ] Every new/changed note has complete, valid frontmatter. - [ ] `id` is unique and unchanged; filename slug matches the id slug. - [ ] All links resolve and are mirrored in `related`. - [ ] `INDEX.md` registry and the topic `_topic.md` reflect the change. - [ ] Tags are from the controlled vocabulary. - [ ] `updated` bumped on every changed note. - plugins/cursor/skills/obsidian-vault/SKILL.md (8950 bytes)
--- name: obsidian-vault version: 0.1.0 audience: agent description: >- Organize Obsidian vaults with MOCs, wikilinks, frontmatter/properties, dashboards, orphan-note checks, and cleanup workflows. Use ONLY when the user explicitly refers to Obsidian — by naming "Obsidian", an Obsidian "vault", or an Obsidian-specific feature such as wikilinks ("[[ ]]"), the Dataview or Bases plugins, or Obsidian Properties. Within that Obsidian context it covers creating Maps of Content, adding/fixing wikilinks, finding orphan notes, normalizing YAML frontmatter, generating Dataview/Bases dashboards, organizing folders, deduplicating or renaming notes, and preparing the vault for AI use. Do NOT use this skill for generic note-taking, Markdown, or knowledge-base requests that don't mention Obsidian. --- # Obsidian Vault Assistant Help the user organize and maintain an Obsidian vault: build navigation with MOCs and wikilinks, normalize metadata, generate dashboards, find and fix orphans, organize folders, deduplicate/rename, and prepare the vault for AI use. Obsidian-specific facts that shape every rule here: - Links are **wikilinks** resolved by **filename**, not path: `[[Note title]]`. Renaming a note auto-updates links inside Obsidian, but moving files outside Obsidian breaks them — always rename via Obsidian when possible. - Metadata is **Properties** (YAML frontmatter) at the top of a note. - Dashboards come from **Dataview** (query language, read-only, flexible) or **Bases** (native, editable tables, fast on big vaults, properties-only). Before acting, confirm the vault's root folder and whether the user has the Dataview plugin installed (Bases is built in since Obsidian 1.9). When a request is ambiguous (organize vs. clean up vs. dashboard), ask which task. ## Wikilinks - Basic: `[[Three laws of motion]]` — resolves by filename, no extension/path. - Display text (pipe): `[[atomic-habits|James Clear — Atomic Habits]]`. - Heading link: `[[Note#Section]]`. Block link: `[[Note#^block-id]]`. - Embed/transclude: `![[Note]]`, `![[Note#Section]]`, `![[image.png]]`. - Aliases: add an `aliases` property so the note resolves under other names. - Avoid `# | ^ : %` and `[ ]` in filenames — they have special meaning in links. - Prefer wikilinks for internal navigation; use standard Markdown links only if the vault is also published to a tool that can't parse wikilinks. When adding links, also surface **unlinked mentions**: if a note's title appears as plain text in other notes, convert those to wikilinks. ## Maps of Content (MOCs) A MOC is a note that links the related notes on a topic — the vault's navigation layer (more flexible than folders or tags, and needs no institutional knowledge). Conventions: - Name MOCs clearly and tag them: `tags: [moc]` (or a `type: moc` property) so every MOC is itself discoverable. - Keep a top-level **Home / Index MOC** that links to all topic MOCs. - A MOC holds a short intro plus grouped wikilinks; it can be hand-curated or auto-generated with a Dataview/Bases query (see Dashboards). MOC template: ```markdown --- type: moc tags: [moc] updated: 2026-06-18 --- # Auth — Map of Content Notes on authentication, sessions, and access control. ## Core - [[auth-flow]] - [[session-tokens]] ## Related MOCs - [[security-moc]] ``` ## Frontmatter / Properties Add a consistent property block to every note. Recommended baseline: ```yaml --- title: Session tokens aliases: [tokens, session token] tags: [auth, security] type: note # note | moc | dashboard | template | person | project created: 2026-06-18 updated: 2026-06-18 status: evergreen # seedling | growing | evergreen related: ["[[auth-flow]]"] --- ``` Rules: - Use a **controlled tag vocabulary** — decide tags up front and reuse them; nested tags (`auth/tokens`) are fine. Don't let tags sprawl. - `tags` use no `#` in frontmatter. Dates in ISO `YYYY-MM-DD`. - Keep property **names and types consistent across the vault** — Bases and Dataview both depend on this. When normalizing, pick one name per concept (e.g. `created`, not `created`/`date`/`Created`) and migrate the rest. ## Dashboards Pick the engine based on the user's setup: **Bases** (native, editable, fast — best for operational boards): - Create a `.base` file or a `base` code block; it builds table/board views from properties. Each cell edits the underlying note's frontmatter. - Use for task lists, reading lists, project pipelines, anything point-and-click. **Dataview** (plugin, read-only, most flexible — best for reports/auto-MOCs): ```dataview TABLE status, updated, tags FROM #auth WHERE type = "note" SORT updated DESC ``` Auto-MOC of everything in a topic: ```dataview LIST FROM #auth WHERE type != "moc" SORT file.name ASC ``` Recently updated: ```dataview TABLE updated FROM "" WHERE updated >= date(today) - dur(7 days) SORT updated DESC ``` Note: large vaults can lag with heavy Dataview queries — prefer Bases there. ## Orphan notes & link hygiene An orphan is a note with no inbound or outbound links. To find and fix: 1. **From Desktop Commander** (no app needed, scales to big vaults): `start_search` the vault for `[[ ]]` links to each note's title — zero hits means no inbound links (an *unlinked* note); to confirm a true orphan (no inbound **and** no outbound), also scan the note's own body for `[[...]]`. The same searches surface **unlinked mentions** (the title as plain text, not wrapped in `[[ ]]`) and **broken links** (a `[[target]]` whose file is missing). 2. **Graph view** (Cmd/Ctrl+G): orphans float as isolated dots at the edges. 3. **Dataview** query for notes with no links: ```dataview LIST WHERE length(file.inlinks) = 0 AND length(file.outlinks) = 0 ``` 4. For each orphan: link it from a relevant MOC/note (`edit_block` to insert the wikilink), tag it `#needs-link` for a batch pass, or archive if obsolete. 5. Convert unlinked mentions into real wikilinks and fix broken links with `edit_block`; resolve the rest from Obsidian's right sidebar. ## Folder organization - Folders are for coarse buckets; **MOCs + tags do the real organizing**. Don't over-nest folders. - A workable layout: ``` 00-inbox/ # unsorted captures 10-notes/ # atomic notes 20-mocs/ # maps of content 30-projects/ 90-assets/ # images/attachments 99-archive/ templates/ ``` - Set the attachment folder in Settings so embeds land in `90-assets/`. - **Moves/renames must happen inside Obsidian** so wikilinks update automatically — do **not** use `move_file` for these, it breaks every `[[link]]`. From Desktop Commander, only edit *content* (`edit_block` / `write_file`); leave moving and renaming to the user in the app. ## Deduplicate & rename - **Duplicates**: `start_search` titles/aliases to find near-identical notes; merge into one, keep the most-linked filename, copy unique content with `edit_block`, then `start_search` for inbound `[[links]]` to the discarded note and repoint them before deleting it. - **Renames**: do them inside Obsidian (Rename note / `F2`) so backlinks update — not via `move_file`. Keep an `aliases` entry for the old name if it was widely referenced. - Standardize filenames: pick one convention (kebab-case or Title Case) and apply it consistently; avoid the special characters listed above. ## Prepare the vault for AI use - Ensure **consistent frontmatter** (same property names/types) so an agent can filter and reason over metadata. - Maintain a **Home/Index MOC** as the single entry point an agent reads first. - Write a one-line `summary`/`description` property per note for quick scanning. - Reduce orphans and broken links so the link graph is a reliable map. - Keep notes **atomic** (one idea each) — easier for an agent to retrieve and cite. - Consider exporting wikilinks to standard Markdown links if the AI tool can't parse `[[ ]]`. ## Workflows - **Build navigation**: `write_file` topic MOCs → `edit_block` notes to link them in → refresh the Home MOC → convert unlinked mentions. - **Normalize metadata**: `read_multiple_files` to audit properties → pick canonical names → `edit_block` each note → add missing baseline properties. - **Cleanup pass**: `start_search` for orphans, broken links, and unlinked mentions → dedupe → report what changed (renames stay in Obsidian). - **Dashboard**: confirm Dataview vs. Bases → `write_file` the view from properties/tags. ## Checklist before finishing - [ ] New/changed notes have consistent frontmatter (canonical property names). - [ ] Renames/moves done inside Obsidian; no links broken. - [ ] New notes linked from at least one MOC or note (no new orphans). - [ ] Tags drawn from the controlled vocabulary. - [ ] Dashboards reference properties/tags that actually exist. - [ ] `updated` bumped on changed notes. - plugins/cursor/skills/terminal/SKILL.md (10761 bytes)
--- name: terminal version: 0.1.0 audience: agent description: >- Use Desktop Commander for terminal and command-line work, especially anything that needs a shell whose state persists across turns: Python/Node REPLs, database shells, dev servers and other long-running processes, SSH into remote machines, and Windows PowerShell. Also handles everyday terminal tasks — navigating folders, choosing the right command for the user's shell (PowerShell, cmd, bash, zsh), running Docker/curl/cloud-CLI commands, inspecting processes and ports, and saving recurring workflows as scripts — even when the user doesn't say "Desktop Commander" or "terminal." Reach for it on pasted errors like "command not found", "permission denied", "EADDRINUSE", "address already in use", "npm ERR!", "ModuleNotFoundError", or "ENOENT", and on intents like "what's using port 3000", "kill that process", "ssh into my server", or "why won't my dev server start". Works on Windows, macOS, and Linux. Never run destructive commands without explicit confirmation. --- # Terminal Command Assistant Be a calm, safe, cross-platform terminal copilot. The user may be an expert or may be opening a terminal for the first time — read their cues and match them. Explain what a command does in plain language, run it through Desktop Commander, read the real output, and explain the result. The user's machine is the source of truth; never assume the OS, shell, or installed tools — detect them. ## 1. Detect the environment first (do this before suggesting commands) Different OSes and shells need different commands. Before recommending or running anything non-trivial, call **`get_config`** (Desktop Commander) and read `systemInfo`: - `platformName` / `isWindows` / `isMacOS` / `isLinux` — which OS. - `defaultShell` and `uiHints.availableShells` — which shell to target. - `pythonInfo`, `nodeInfo` — whether Python/Node exist and their versions. - `blockedCommands` — commands Desktop Commander refuses to run (see §7). - `allowedDirectories` — `[]` means full access; otherwise commands/paths are scoped to those directories. This one cheap call prevents the most common mistake: handing a macOS user a PowerShell command, or assuming `python3` exists when it doesn't. Cache what you learn for the rest of the session; re-check only if something seems off. ## 2. Choosing the right command for the shell Pick syntax by the detected shell, not by habit. Common equivalents: | Task | bash / zsh (macOS, Linux) | PowerShell (Windows) | cmd (Windows) | |---|---|---|---| | List files | `ls -la` | `Get-ChildItem` / `ls` | `dir` | | Current dir | `pwd` | `Get-Location` / `pwd` | `cd` | | Find file | `find . -name "*.log"` | `Get-ChildItem -Recurse -Filter *.log` | `dir /s *.log` | | Search text | `grep -r "TODO" .` | `Get-ChildItem -Recurse \| Select-String TODO` | `findstr /s TODO *` | | Env var | `echo $HOME` | `$env:USERPROFILE` | `echo %USERPROFILE%` | | Set env (session) | `export KEY=val` | `$env:KEY="val"` | `set KEY=val` | | Delete file | `rm file` | `Remove-Item file` | `del file` | | Copy | `cp a b` | `Copy-Item a b` | `copy a b` | | Path separator | `/` | `\` (or `/`) | `\` | Notes that bite people: Windows paths use `\` and often need quoting when they contain spaces; PowerShell and bash quote/escape differently; `~` expands in bash/zsh but not in cmd. When in doubt, prefer the cross-platform tool the user already has (e.g. `python`, `node`, `git`) over shell-specific syntax. ## 3. Running commands with Desktop Commander **Always use absolute paths.** Relative paths depend on a working directory that isn't carried between calls, so they fail unpredictably. - **One-shot commands** → `start_process` with the command and a timeout. It returns output and a PID. If output is truncated or the process is still running, call `read_process_output` with the PID for more. - **Long-running / interactive sessions** (REPLs, SSH, DB shells, `npm create`, anything that prompts) → `start_process` to launch, then `interact_with_process(pid, "...")` to send input and `read_process_output` to read responses. End with `force_terminate` if it won't exit on its own. - Navigation is just inspection: use `list_directory` and `get_file_info` rather than relying on a persistent `cd`. If you must `cd`, do it inside the same command (`cd /abs/path && some-command`). ### Interactive REPL pattern (the workhorse) This keeps state across calls and is the right way to drive Python, Node, a database shell, or SSH: ``` start_process("python3 -i") # or "node -i", "ssh user@host", "psql ..." interact_with_process(pid, "import pandas as pd") interact_with_process(pid, "df = pd.read_csv('/abs/path/data.csv')") interact_with_process(pid, "print(df.describe())") read_process_output(pid) # pull more output if needed ``` ## 4. Running specific CLIs - **Python**: prefer `python3 -i` as an interactive session for multi-step work; for a quick one-off use `python3 /abs/script.py`. Check `pythonInfo.command` from §1 (`python` vs `python3`). - **Node**: `node -i` for an interactive session, `node /abs/script.js` for a one-off. `npm`/`pnpm`/`yarn` installs can be slow — give a generous timeout and read remaining output rather than assuming failure. - **Docker**: `docker ps`, `docker logs <id>`, `docker compose up -d`. Long builds/runs: launch then poll with `read_process_output`. Treat `docker system prune`, `docker rm`, `docker volume rm` as destructive (§7). - **SSH**: launch with `start_process("ssh user@host")`, then drive it with `interact_with_process`. Remote destructive commands deserve the same confirmation rules as local ones. - **curl / HTTP**: fine for inspection (`curl -i https://...`). Be careful with anything that pipes a downloaded script straight into a shell (`curl ... | sh`) — that's untrusted code execution; show it and confirm first. - **Cloud CLIs** (`aws`, `gcloud`, `az`): read-only commands (`describe`, `list`, `get`) are safe to run; anything that creates, deletes, scales, or changes IAM is high-impact — preview the exact command and confirm. Never echo secrets or credentials into the terminal output. ## 5. Inspecting processes and ports - **Processes**: `list_processes` (Desktop Commander) for a structured view, or `ps aux` (Unix) / `Get-Process` (PowerShell). Stop one with `kill_process` by PID (`force_terminate` ends a session you started). - **What's using a port**: - macOS/Linux: `lsof -i :3000` or `lsof -nP -iTCP -sTCP:LISTEN` - Linux: `ss -ltnp` - Windows PowerShell: `Get-NetTCPConnection -LocalPort 3000` - Windows cmd: `netstat -ano | findstr :3000` (then map the PID) - When killing a process, confirm the PID belongs to what the user thinks it does — show the process line before terminating it. ## 6. Explaining errors in plain English When a command fails, don't just retry blindly: 1. Read the **actual** error text from the process output — the real cause is usually in the last few lines, not the first. 2. Name the cause in one plain sentence (e.g. "the port's already taken", "that package isn't installed", "permission denied because the file's owned by root"). 3. Give the concrete fix command for *their* shell, and explain what it does. 4. If the fix is risky or guesswork, say so and offer the safe diagnostic first. Common ones worth recognizing fast: `command not found` / `not recognized` (not installed or not on PATH), `EADDRINUSE` (port in use — see §5), `permission denied` / `EACCES` (ownership/permissions, not always fixable with elevation), `ENOENT` (path doesn't exist — check absolute path), `npm ERR!` blocks (read the resolved error line), non-zero exit codes (report the code). ## 7. Safety: destructive commands and chaining Desktop Commander already refuses a built-in `blockedCommands` list (things like `sudo`, `mkfs`, `format`, `dd`, `fdisk`, `shutdown`, `reboot`, `diskpart`, `reg`, `net`). Read the live list from `get_config`; don't assume it. Beyond that list, treat these as **destructive — never run without the user's explicit confirmation**, even if they'd technically succeed: - Recursive/forced deletes: `rm -rf`, `Remove-Item -Recurse -Force`, `del /s`, `rd /s`. - Overwriting or moving over existing files; wildcard deletes. - Disk/format/partition operations. - `git reset --hard`, `git clean -fd`, `git push --force` (history/data loss). - Database drops/truncates: `DROP`, `TRUNCATE`, `DELETE` without a `WHERE`. - `chmod -R` / `chown -R` on broad paths, `killall`, mass process kills. - Cloud deletes/scaling/IAM changes; `docker ... prune`/`rm`/volume removal. - Anything piping remote content into a shell (`curl ... | sh`). For these: show the exact command, explain in one line what it will irreversibly do, and wait for a clear "yes". Prefer a dry run or a read-only check first (e.g. `ls` the glob before `rm` it, `--dry-run` where the tool supports it). **Chaining safely**: `&&` runs the next only if the previous succeeded; `;` runs regardless; `||` runs only on failure. PowerShell historically uses `;` to sequence (it supports `&&`/`||` in v7+, but not all hosts). Keep chains short. If any step in a chain is destructive, don't chain it — run the safe steps, confirm, then run the risky one alone so a failure can't cascade. ## 8. Turning repeated workflows into scripts When the user runs the same sequence repeatedly (or asks to "save this"), offer to capture it as a script instead of retyping: - Unix → a `.sh` file with `#!/usr/bin/env bash` (or `zsh`), `set -euo pipefail` for safety, comments explaining each step; make it executable (`chmod +x`). - Windows → a `.ps1` (PowerShell) script with comment-based help at the top. - Write the file with `write_file` to an absolute path the user chooses, echo it back, and explain how to run it. Parameterize the bits that change (paths, names) rather than hard-coding. - If the workflow needs to run on both Windows and Unix, either keep the logic in a cross-platform tool (a small Python/Node script) or provide both a `.sh` and a `.ps1`. Don't pretend one shell script runs everywhere. Keep scripts small and readable — the goal is something the user can open, trust, and edit later, not a black box. ## Operating etiquette - Preview risky commands before running; run read-only inspection first. - Use absolute paths; respect `allowedDirectories`. - Never print secrets, tokens, or passwords into output; redact if they appear. - Match the user's level: explain jargon when they seem new, stay terse when they're fluent. - After a failed command, diagnose from the real output before retrying. - PRIVACY.md (9636 bytes)
# Privacy Policy for Desktop Commander **Last updated: December 11, 2025** ## Introduction We at Desktop Commander are committed to respecting your privacy and keeping secure any information collected through our software. This privacy policy explains how we collect, use, and protect telemetry data when you use Desktop Commander. Desktop Commander is an open-source MCP (Model Context Protocol) server that runs locally on your machine. This policy applies to the optional telemetry data we collect to improve the application. ## Data Collection Desktop Commander collects limited telemetry data to help us understand usage patterns, detect errors, and improve the tool. **Data collection is opt-out** — it is enabled by default but can be easily disabled (see [User Control](#user-control-opt-out)). Our telemetry system is designed to be privacy-focused: - We collect only the minimum information necessary for product improvement - We do not collect directly identifying information such as names, email addresses, usernames, or file paths - We use a pseudonymous identifier (random UUID) for analytics, which cannot directly identify you but allows us to understand usage patterns ### What We Collect #### Pseudonymous Client ID - **Client ID**: A randomly generated UUID that persists between sessions - **Purpose**: Used to calculate monthly active users (MAU), retention metrics, and understand usage patterns over time - **Privacy Design**: This ID is not derived from hardware or personal information. It cannot identify you personally but does allow us to understand usage patterns across sessions. #### Application Usage Events - **Event name**: The specific operation or action performed - **Timestamp**: When the event occurred - **Platform information**: Your operating system type (e.g., Windows, macOS, Linux) - **App version**: The version of Desktop Commander you're using - **Client information**: Name and version of the MCP client (e.g., "Claude Desktop", "VS Code") #### Installation and Setup Information - **Node.js version**: Version of Node.js runtime - **NPM version**: Version of the NPM package manager - **Installation method**: How the tool was installed (npx, global, direct, DXT) - **Shell environment**: Type of shell being used (bash, zsh, PowerShell, etc.) - **Setup status**: Success or failure of installation steps #### Container/Environment Metadata - **Container detection**: Whether running in Docker or other container environment - **Container type**: Type of containerization (Docker, Kubernetes, etc.) - **Runtime source**: How the application was launched (npx, direct, etc.) - Note: Container names and image names are sanitized to remove unique identifiers #### File Operation Metrics - **File extensions**: Types of files being accessed (e.g., .js, .py, .txt) - **File sizes**: Size of files being read or written - **Operation type**: Type of file operation (read, write, edit) - **Operation status**: Success or failure of operations #### Terminal Command Metrics - **Base command name**: The command being run (e.g., "python", "node"), without arguments - **Command status**: Success or failure of command execution - **Execution time**: How long commands take to run #### Error Information - **Error types**: Categories of errors encountered (e.g., ENOENT, EPERM) - **Error codes**: System error codes when available - **Sanitized error messages**: Error descriptions with file paths and usernames removed - **Operation context**: Which operation encountered the error ### What We DO NOT Collect We explicitly DO NOT collect: - **File paths**: Full paths or filenames of accessed files - **File contents**: The actual data or code in your files - **Command arguments**: Arguments or parameters passed to terminal commands - **Usernames**: System or account usernames - **Personal information**: Any personally identifiable information - **Sensitive data**: We do not knowingly collect sensitive or special category personal information ### IP Addresses We do not store or have access to IP addresses. Our analytics provider (Google Analytics) receives IP addresses as part of standard HTTPS requests but automatically anonymizes them before storage. We do not have access to this data in any form. ### Children Desktop Commander is not directed at children under the age of 18. We do not knowingly collect information from children. If we learn that we have collected personal data from a child, we will take steps to delete that information. ## How We Use Data The collected data is used for: - Understanding how the application is used - Calculating retention and engagement metrics - Identifying common errors or issues - Measuring feature adoption and performance - Guiding development priorities - Improving overall user experience We may aggregate or de-identify data so that it no longer identifies any individual, and use that information for the purposes described above. ## How We Share Data We may share your data in the following circumstances: **Service Providers**: We use Google Analytics 4 to process telemetry data. Data is sent securely via HTTPS to Google's servers. We have appropriate data processing agreements in place with our service providers. Google's privacy policy applies to their processing: https://policies.google.com/privacy **Legal Compliance**: We may disclose data if required to comply with applicable laws, regulations, or legal processes, or to protect the rights, safety, or property of users or others. **Business Transfers**: In the event of a merger, acquisition, or sale of assets, telemetry data may be transferred as part of that transaction. We will provide notice if your data becomes subject to a different privacy policy. **No Sale or Targeted Advertising**: We do not "sell" or "share" personal data for cross-contextual behavioral advertising, and we do not process personal data for "targeted advertising" purposes (as those terms are defined under applicable privacy laws). ## Data Transfers Desktop Commander processes telemetry data on servers located in various jurisdictions, including the United States. When data is transferred internationally, we apply the protections outlined in this policy regardless of where it is processed, and we only transfer data in accordance with legally valid transfer mechanisms. ## Data Retention Telemetry data is retained for a period of 14 months, after which it is automatically deleted from Google Analytics. When data is no longer needed, we follow procedures to delete or anonymize it in compliance with applicable laws. ## Security We implement commercially reasonable technical and organizational measures to protect data from loss, misuse, and unauthorized access. All data is transmitted securely via HTTPS. However, no method of transmission over the Internet is completely secure. ## User Control (Opt-Out) Data collection is **opt-out** — telemetry is enabled by default but you can disable it at any time: **Option 1: Ask the AI** Simply ask Claude (or your AI assistant) to disable telemetry: > "Please disable Desktop Commander telemetryEnabled in config" **Option 2: Manual configuration** 1. Edit your configuration file at `~/.desktop-commander/config.json` 2. Set `"telemetryEnabled": false` 3. Restart the application When telemetry is disabled, no data will be sent. Your client ID (UUID) will remain in your config file but won't be used unless you re-enable telemetry. ## Your Rights and Choices Depending on where you live and the laws that apply, you may have certain rights in relation to your data. These may include the right to access, delete, correct, or transfer your data; to object to or restrict how we process it; or to withdraw consent. You may also have the right to lodge a complaint with your local data protection authority. **Exercising Your Rights** The most effective way to exercise your privacy rights is to disable telemetry as described above. Once disabled, no further data will be collected, and any existing data will be automatically deleted after our 14-month retention period. **Why we cannot process UUID-based data requests**: Privacy laws require us to verify the identity of individuals before fulfilling access or deletion requests. Because we collect no identifying information (no email, name, IP address, machine ID, or account), we have no way to verify that someone requesting data for a particular UUID is actually the person that UUID belongs to. Processing unverifiable requests could inadvertently expose or delete another person's data. **What this means for you**: - Your privacy is protected by design: we cannot identify you, and neither can anyone else - To stop future data collection: disable telemetry in your config - To ensure old data is removed: it will automatically purge after 14 months - If you uninstall Desktop Commander and delete your config file, there is no way to link any stored analytics data back to you ## Privacy Policy Changes We may update this privacy policy from time to time. When we do, we will publish an updated version and effective date at the top of this page. Your continued use of Desktop Commander after any change constitutes acceptance of the updated policy. ## Contact - **General questions**: Open an issue on our [GitHub repository](https://github.com/wonderwhy-er/DesktopCommanderMCP) - **Privacy concerns**: [email protected] We aim to respond to privacy inquiries within 30 days. --- *Desktop Commander is open-source software. This privacy policy applies only to the optional telemetry feature.*
- PUBLISH.md (10355 bytes)
# Release Guide for Desktop Commander MCP Releases are published by CI (`.github/workflows/release.yml`). A release goes to **four places from one trigger**: 1. **npm** — `@wonderwhy-er/desktop-commander` 2. **GitHub release** — with the `desktop-commander-<version>.mcpb` asset attached 3. **Claude directory** — GitHub releases expose the MCPB asset for Anthropic's directory pipeline; actual ingestion depends on Anthropic and must be verified 4. **MCP Registry** — `io.github.wonderwhy-er/desktop-commander` **Who can release:** anyone with write (push) access to this repository. Both the tag push and the Actions "Run workflow" button require write permission. No npm login, no mcp-publisher, no personal auth, no secrets anywhere — CI publishes to npm via OIDC trusted publishing and to the MCP Registry via GitHub OIDC. --- ## Normal release (terminal) ```bash npm run release # patch (0.2.47 → 0.2.48) npm run release:minor # minor (0.2.47 → 0.3.0) npm run release:major # major (0.2.47 → 1.0.0) npm run release:dry # preview the plan, change nothing ``` The script shows the full plan and asks for one confirmation: ``` Release plan: 1. Run tests (local, nothing changed yet) 2. Bump version 0.2.47 → 0.2.48 and commit 3. Push main + tag v0.2.48 to origin — this starts the CI release: build MCPB → publish npm → GitHub release with .mcpb asset (picked up by the Claude directory) → publish MCP Registry Release v0.2.48 now? [y/N] ``` After you confirm: tests run locally, the version is bumped and committed, and the tag push hands off to CI. Watch the run at https://github.com/wonderwhy-er/DesktopCommanderMCP/actions/workflows/release.yml Requirements: on `main`, clean working tree, tests passing. `--yes` skips the prompt. `npm run release -- --skip-tests` dispatches CI with the test-suite skip checkbox set; CI still builds and verifies the MCPB before publishing. ## Normal release (GitHub UI — no local setup at all) 1. Actions → **Release** → **Run workflow** (from `main`) 2. Pick `bump` = patch / minor / major 3. Optionally select **Skip tests** if the candidate has already passed testing 4. Run By default CI runs the full tests, bumps the version, commits and tags `main`, then publishes everywhere. **Skip tests** bypasses only the full test suite; dependency installation, MCPB build, version consistency and bundle validation remain mandatory. Skipped tests are recorded as a warning in the workflow log. When the current version is an alpha such as `0.3.2-alpha.3`, **patch** promotes it directly to `0.3.2`, not `0.3.3`. Minor and major still advance to `0.4.0` and `1.0.0` respectively. --- ## Partial releases (skip some targets) Sometimes you only want a subset (npm outage, registry problem, npm-only fix). Both entry points support it: **Terminal** (dispatches to CI via `gh`, needs `gh auth login` once): ```bash npm run release -- --skip-registry # npm + GitHub release only npm run release -- --skip-npm --skip-registry # GitHub release/MCPB only npm run release -- --skip-github-release --skip-registry # npm only ``` **GitHub UI**: same Run workflow dialog — check `skip_npm`, `skip_registry`, and/or `skip_github_release`. **Completing a partial release later** (e.g. released npm-only, now want the rest): re-release the existing tag — every publish step detects targets that already have the version and skips them, so only the missing ones run: ```bash npm run release -- --tag=v0.2.48 # completes whatever v0.2.48 is missing ``` (or UI: Run workflow with `tag` = `v0.2.48`, nothing else) One ordering rule: the MCP Registry validates that the npm package exists, so you cannot publish a **new** version to the registry while skipping npm. Publish npm first, complete the registry later with `--tag=`. ## Rehearsal — test the pipeline without releasing ```bash npm run release:rehearsal ``` Force-pushes a `test-v<version>` tag at your current HEAD (any branch). CI runs the **entire pipeline in safety mode**: MCPB is built for real, `npm publish --dry-run` (tarball contents in the log, nothing uploaded), the GitHub release is created as a **draft** with the `.mcpb` attached (invisible without repo write access), and the registry step validates `server.json` and proves the OIDC login without publishing. Use it to validate workflow changes before they reach main — tag-triggered runs execute the workflow file at the tagged commit, so your branch's copy is what runs. Repeatable: re-running force-moves the same tag. Afterwards: check the run summary, optionally download the `.mcpb` from the draft and install it in Claude Desktop, then clean up: ```bash gh release delete test-vX.Y.Z --yes git push origin :refs/tags/test-vX.Y.Z && git tag -d test-vX.Y.Z ``` ## When a release fails mid-way Click **"Re-run failed jobs"** on the failed Actions run. Publish steps are idempotent (already-published targets are skipped), so the re-run finishes only what's missing. If the failure needed a workflow fix, land the fix on `main` first and use `--tag=vX.Y.Z` / the UI `tag` field instead — dispatch runs `main`'s copy of the workflow. ## Alpha releases ```bash npm run release:alpha # 0.2.47 → 0.2.48-alpha.0 → npm only, under the alpha dist-tag ``` Alphas are the one flow that still publishes from your machine (needs `npm login`). No git tag, no CI, no GitHub release, no registry — CI intentionally refuses publishing pre-release tags. After alpha testing, choose `bump=patch` in the GitHub Actions release workflow to promote `0.3.2-alpha.N` directly to stable `0.3.2`. Install an alpha with: `npm install -g @wonderwhy-er/desktop-commander@alpha` ## Repository-root MCPB manifest (discovery experiment) The repository includes [`manifest.json`](manifest.json) at its root to make **the most recently published stable MCPB metadata** discoverable without downloading an archive. This mirrors the layout used by some other MCPB projects but is an **experiment**, not a documented Claude directory-update trigger. - `manifest.template.json` remains the source of truth for MCPB metadata. - `npm run sync-version` (and `npm run bump`) regenerates the root manifest when `package.json` contains a stable `X.Y.Z` version. The release scripts include the regenerated file in the release commit. - While the working tree is on an alpha/beta version, the root manifest deliberately stays at the last stable release. Never advertise prerelease metadata to an unknown external directory crawler. - The root copy omits `$schema` because its relative path is valid only for the bundle build directory. The actual `.mcpb` is still assembled from the template by `scripts/build-mcpb.cjs`. - Release CI checks that the root manifest and the bundled manifest match (ignoring the bundle-only `$schema`) before publishing. **Important:** The [official MCPB spec](https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md) requires `manifest.json` *inside the bundle*, not at the GitHub root. There is no verified documentation that a root manifest or an npm update causes Anthropic to refresh a directory listing. Directory publishing and the existing Anthropic escalation remain separate operational steps. --- ## Release notes CI creates the GitHub release with GitHub's auto-generated notes (the list of merged PRs since the previous tag). Edit the release afterwards to curate them — editing notes after publishing is safe and doesn't affect npm, the registry, or the Claude directory (the scanner reads the `.mcpb` asset, not the notes). --- ## One-time setup (repository admin) | What | Where | Why | |---|---|---| | npm trusted publisher | npmjs.com → `@wonderwhy-er/desktop-commander` → Settings → Trusted Publisher | GitHub Actions: user `wonderwhy-er`, repo `DesktopCommanderMCP`, workflow `release.yml`, environment empty. No token, no secret — CI publishes via OIDC with automatic provenance. Configured by any package owner. | | MCP Registry auth | nothing to set up | CI uses `mcp-publisher login github-oidc`; the registry grants `io.github.wonderwhy-er/*` to workflows running in this repo automatically. | | Claude directory channel | email to our Anthropic contact | one-time registration: repo `wonderwhy-er/DesktopCommanderMCP`, tag pattern `v*`, asset pattern `desktop-commander-*.mcpb`, maintainer contact. After this, every release is ingested automatically. | ## What runs where (reference) | Step | Normal (terminal) | UI / dispatch | |---|---|---| | Tests | locally, before anything changes | in CI, before the bump | | Version bump + commit + tag | locally by the script | in CI by the workflow | | MCPB build, npm, GitHub release, registry | CI | CI | Version consistency is enforced twice: `scripts/sync-version.js` keeps `package.json`, `server.json`, and `src/version.ts` in lock-step, and CI refuses to publish if the tag and those files disagree. ## Registry information - **npm package**: https://www.npmjs.com/package/@wonderwhy-er/desktop-commander - **MCP Registry**: https://registry.modelcontextprotocol.io/ (`io.github.wonderwhy-er/desktop-commander`) - **GitHub releases**: https://github.com/wonderwhy-er/DesktopCommanderMCP/releases - Registry versions are **immutable**: a published version can never be overwritten, only superseded by a new version (or hidden with `mcp-publisher status --status deleted`). ## Troubleshooting - **npm publish failed in CI**: check the trusted-publisher config on npmjs.com still matches (repo `DesktopCommanderMCP`, workflow `release.yml`, environment empty); re-run failed jobs. - **Registry publish failed with 401/audience error**: the mcp-publisher binary or registry API changed; check the workflow's install step, re-run. - **"Version mismatch" in CI**: the tag doesn't match `package.json`/ `server.json` — the tag was cut by hand. Delete the tag, use the script. - **Tag exists but no workflow ran**: the tagged commit predates `release.yml` on that ref, or the tag doesn't match `v*`. Use `npm run release -- --tag=vX.Y.Z` to release it via dispatch. - **Same-version re-release**: npm and the registry both refuse duplicate versions — that's what makes re-runs safe. To ship a fix, bump again. - README.md (52594 bytes)
# Desktop Commander MCP ### Search, update, manage files and run terminal commands with AI [](https://www.npmjs.com/package/@wonderwhy-er/desktop-commander) [](https://agentaudit.dev/skills/desktop-commander) [](https://archestra.ai/mcp-catalog/wonderwhy-er__desktopcommandermcp) [](https://smithery.ai/server/@wonderwhy-er/desktop-commander) [](https://www.buymeacoffee.com/wonderwhyer) [](https://discord.gg/kQ27sNnZr7) Work with code and text, run processes, and automate tasks, going far beyond other AI editors - while using host client subscriptions instead of API token costs. <a href="https://glama.ai/mcp/servers/zempur9oh4"> <img width="380" height="200" src="https://glama.ai/mcp/servers/zempur9oh4/badge" alt="Desktop Commander MCP" /> </a> ## Table of Contents - [Features](#features) - [How to install](#how-to-install) - [Getting Started](#getting-started) - [Usage](#usage) - [File Preview UI & Markdown Editor](#file-preview-ui--markdown-editor) - [Handling Long-Running Commands](#handling-long-running-commands) - [Work in Progress and TODOs](#roadmap) - [Sponsors and Supporters](#support-desktop-commander) - [Website](#website) - [Media](#media) - [Testimonials](#testimonials) - [Frequently Asked Questions](#frequently-asked-questions) - [Contributing](#contributing) - [License](#license) All of your AI development tools in one place. Desktop Commander puts all dev tools in one chat. Execute long-running terminal commands on your computer and manage processes through Model Context Protocol (MCP). Built on top of [MCP Filesystem Server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) to provide additional search and replace file editing capabilities. ## Features - **Remote AI Control** - Use Desktop Commander from ChatGPT, Claude web, and other AI services via [Remote MCP](https://mcp.desktopcommander.app) - **File Preview UI** - Visual file previews in Claude Desktop with rendered markdown, inline images, expandable content, built-in markdown editor, and quick "Open in folder" access - **Enhanced terminal commands with interactive process control** - **Execute code in memory (Python, Node.js, R) without saving files** - **Instant data analysis - just ask to analyze CSV/JSON/Excel files** - **Native Excel file support** - Read, write, edit, and search Excel files (.xlsx, .xls, .xlsm) without external tools - **PDF support** - Read PDFs with text extraction, create new PDFs from markdown, modify existing PDFs - **DOCX support** - Read, create, edit, and search Word documents (.docx) with surgical XML editing and markdown-to-DOCX conversion - **Interact with running processes (SSH, databases, development servers)** - Execute terminal commands with output streaming - Command timeout and background execution support - Process management (list and kill processes) - Session management for long-running commands - **Process output pagination** - Read terminal output with offset/length controls to prevent context overflow - Server configuration management: - Get/set configuration values - Update multiple settings at once - Dynamic configuration changes without server restart - Full filesystem operations: - Read/write files (text, Excel, PDF, DOCX) - Create/list directories - **Recursive directory listing** with configurable depth and context overflow protection for large folders - Move files/directories - Search files and content (including Excel content) - Get file metadata - **Negative offset file reading**: Read from end of files using negative offset values (like Unix tail) - Code editing capabilities: - Surgical text replacements for small changes - Full file rewrites for major changes - Multiple file support - Pattern-based replacements - vscode-ripgrep based recursive code or text search in folders - Local tool-call history and audit logs: - Tool calls and arguments are recorded locally on the machine running Desktop Commander - Recent call history with bounded output previews is available through `get_recent_tool_calls` - Size-based rotation/trimming keeps the active history files bounded - Safety guardrails (not a sandbox — see [SECURITY.md](SECURITY.md)): - Symlink traversal prevention on file operations - Command blocklist for accidental execution - [Docker isolation](#option-6-docker-installation--auto-updates-no-nodejs-required) for complete isolation ## How to install For ChatGPT, Claude web, and other remote clients, see the [Remote device launchers](scripts/remote/README.md). They install Node.js when missing and run Desktop Commander Remote on macOS, Linux, or Windows. ### Install in Claude Desktop Desktop Commander offers multiple installation methods for Claude Desktop. > **📋 Update & Uninstall Information:** Options 1, 2, 3, 4, and 6 have automatic updates. Option 5 requires manual updates. See below for details. <details> <summary><b>Option 1: Install through npx ⭐ Auto-Updates (Requires Node.js)</b></summary> Just run this in terminal: ``` npx @wonderwhy-er/desktop-commander@latest setup ``` For debugging mode (allows Node.js inspector connection): ``` npx @wonderwhy-er/desktop-commander@latest setup --debug ``` **Command line options during setup:** - `--debug`: Enable debugging mode for Node.js inspector - `--no-onboarding`: Disable onboarding prompts for new users Restart Claude if running. **✅ Auto-Updates:** Yes - automatically updates when you restart Claude **🔄 Manual Update:** Run the setup command again **🗑️ Uninstall:** Run `npx @wonderwhy-er/desktop-commander@latest remove` </details> <details> <summary><b>Option 2: Using bash script installer (macOS) ⭐ Auto-Updates (Installs Node.js if needed)</b></summary> ``` curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install.sh | bash ``` This script handles all dependencies and configuration automatically. **✅ Auto-Updates:** Yes **🔄 Manual Update:** Re-run the bash installer command above **🗑️ Uninstall:** Run `npx @wonderwhy-er/desktop-commander@latest remove` </details> <details> <summary><b>Option 3: Installing via Smithery ⭐ Auto-Updates (Requires Node.js)</b></summary> 1. **Visit:** https://smithery.ai/server/@wonderwhy-er/desktop-commander 2. **Login to Smithery** if you haven't already 3. **Select your client** (Claude Desktop) on the right side 4. **Install with the provided key** that appears after selecting your client 5. **Restart Claude Desktop** **✅ Auto-Updates:** Yes - automatically updates when you restart Claude **🔄 Manual Update:** Visit the Smithery page and reinstall </details> <details> <summary><b>Option 4: Add to claude_desktop_config manually ⭐ Auto-Updates (Requires Node.js)</b></summary> Add this entry to your claude_desktop_config.json: - On Mac: `~/Library/Application Support/Claude/claude_desktop_config.json` - On Windows: `%APPDATA%\Claude\claude_desktop_config.json` - On Linux: `~/.config/Claude/claude_desktop_config.json` ```json { "mcpServers": { "desktop-commander": { "command": "npx", "args": [ "-y", "@wonderwhy-er/desktop-commander@latest" ] } } } ``` Restart Claude if running. **✅ Auto-Updates:** Yes - automatically updates when you restart Claude **🔄 Manual Update:** Run the setup command again **🗑️ Uninstall:** Run `npx @wonderwhy-er/desktop-commander@latest remove` or remove the entry from your claude_desktop_config.json </details> <details> <summary><b>Option 5: Checkout locally ❌ Manual Updates (Requires Node.js)</b></summary> ```bash git clone https://github.com/wonderwhy-er/DesktopCommanderMCP.git cd DesktopCommanderMCP npm run setup ``` Restart Claude if running. The setup command will install dependencies, build the server, and configure Claude's desktop app. **❌ Auto-Updates:** No - requires manual git updates **🔄 Manual Update:** `cd DesktopCommanderMCP && git pull && npm run setup` **🗑️ Uninstall:** Run `npx @wonderwhy-er/desktop-commander@latest remove` or remove the cloned directory and MCP server entry from Claude config </details> <details> <summary><b>Option 6: Docker Installation 🐳 ⭐ Auto-Updates (No Node.js Required)</b></summary> Perfect for users who want isolation or don't have Node.js installed. Runs in a sandboxed Docker container with a persistent work environment. **Prerequisites:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed **and running**, Claude Desktop app installed. **macOS/Linux:** ```bash bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) ``` **Windows PowerShell:** ```powershell iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1')) ``` The installer will check Docker, pull the image, prompt for folder mounting, and configure Claude Desktop. **Docker persistence:** Your tools, configs, work files, and package caches all survive restarts. <details> <summary>Manual Docker Configuration</summary> **Basic setup (no file access):** ```json { "mcpServers": { "desktop-commander-in-docker": { "command": "docker", "args": ["run", "-i", "--rm", "mcp/desktop-commander:latest"] } } } ``` **With folder mounting:** ```json { "mcpServers": { "desktop-commander-in-docker": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "/Users/username/Desktop:/mnt/desktop", "-v", "/Users/username/Documents:/mnt/documents", "mcp/desktop-commander:latest" ] } } } ``` **Advanced folder mounting:** ```json { "mcpServers": { "desktop-commander-in-docker": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "dc-system:/usr", "-v", "dc-home:/root", "-v", "dc-workspace:/workspace", "-v", "dc-packages:/var", "-v", "/Users/username/Projects:/mnt/Projects", "-v", "/Users/username/Downloads:/mnt/Downloads", "mcp/desktop-commander:latest" ] } } } ``` </details> <details> <summary>Docker Management Commands</summary> **macOS/Linux:** ```bash # Check status bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --status # Reset all persistent data bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset ``` **Windows PowerShell:** ```powershell # Check status $script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Status # Reset all data $script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Reset # Show help $script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Help ``` **Troubleshooting:** Reset and reinstall from scratch: ```bash bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset && bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) ``` </details> **✅ Auto-Updates:** Yes - `latest` tag automatically gets newer versions **🔄 Manual Update:** `docker pull mcp/desktop-commander:latest` then restart Claude </details> ### Install in Other Clients Desktop Commander works with any MCP-compatible client. The standard JSON configuration is: ```json { "mcpServers": { "desktop-commander": { "command": "npx", "args": ["-y", "@wonderwhy-er/desktop-commander@latest"] } } } ``` Add this to your client's MCP configuration file at the locations below: <details> <summary><b>Cursor</b></summary><br> [](https://cursor.com/en-US/install-mcp?name=desktop-commander&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB3b25kZXJ3aHktZXIvZGVza3RvcC1jb21tYW5kZXJAbGF0ZXN0Il19) [View MCP Server in Directory](https://cursor.directory/mcp/desktop-commander-mcp) Or add manually to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project folder (project-specific). See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info. </details> <details> <summary><b>Windsurf</b></summary> Add to `~/.codeium/windsurf/mcp_config.json`. See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp) for more info. </details> <details> <summary><b>VS Code / GitHub Copilot</b></summary> Add to `.vscode/mcp.json` in your project or VS Code User Settings (JSON). Make sure MCP is enabled under Chat > MCP. Works in Agent mode. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info. </details> <details> <summary><b>Cline</b></summary> Configure through the Cline extension settings in VS Code. Open the Cline sidebar, click the MCP Servers icon, and add the JSON configuration above. See [Cline MCP docs](https://docs.cline.bot/mcp/configuring-mcp-servers) for more info. </details> <details> <summary><b>Roo Code</b></summary> Add to your Roo Code MCP configuration file. See [Roo Code MCP docs](https://docs.roocode.com/features/mcp/using-mcp-in-roo) for more info. </details> <details> <summary><b>Claude Code</b></summary> ```sh claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest ``` Remove `--scope user` to install for the current project only. See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more info. </details> <details> <summary><b>Trae</b></summary> Use the "Add manually" feature and paste the JSON configuration above. See [Trae MCP docs](https://docs.trae.ai/ide/model-context-protocol?_lang=en) for more info. </details> <details> <summary><b>Kiro</b></summary> Navigate to `Kiro` > `MCP Servers`, click `+ Add`, and paste the JSON configuration above. See [Kiro MCP docs](https://kiro.dev/docs/ - SECURITY.md (4190 bytes)
# Security Policy ## Security Model Desktop Commander is a privileged local automation tool. It lets an AI client you authorize read and write files and execute terminal commands on your machine. That capability is the point of the product — not a flaw. Because it can run arbitrary terminal commands, Desktop Commander should be understood as an **amplifier of whatever the connected AI client asks it to do**. Its built-in restrictions are **safety guardrails that reduce accidental or unintended actions**, not a security sandbox that can contain a malicious or compromised client. ### Core assumption Desktop Commander assumes the connected AI client — and the account driving it — is **trusted and uncompromised**. It executes requested actions and does not attempt to determine whether a request originates from a genuine user, from prompt injection, or from a compromised AI account. Protecting the integrity of that client and account is part of the overall security model and is the user's responsibility. If the AI client should never be able to reach the rest of your machine, that guarantee can only come from OS-level isolation (see below). ## What the built-in controls do | Control | Purpose | Security boundary? | |---------|---------|--------------------| | Allowed directories | Reduce accidental file access | No | | Command blocklist | Reduce accidental execution | No | | Symlink traversal prevention | Block a class of accidental path escapes | No | | Docker / VM isolation | Contain the tool to an isolated environment | Yes | Terminal command execution is a first-class feature. Because it can launch arbitrary programs, path-based and command-based restrictions can be circumvented by design — for example via shell substitution, absolute paths, or invoking another interpreter. These controls are advisory: they make common mistakes less likely; they are not a boundary against a client that is actively trying to escape them. ## Recommended deployment for stronger isolation For any workload where the AI client must not access the wider machine, run Desktop Commander inside an isolated environment: - **Docker** with selective folder mounting (see the [Docker installation section](README.md#option-6-docker-installation-🐳-⭐-auto-updates-no-nodejs-required)) - A **virtual machine**, dev container, or a separate/dedicated workstation Additional practical steps: - Enable MFA on the AI accounts you connect - Only connect AI clients you trust; remove ones you no longer use - Scope work to project-specific directories rather than your whole home folder - Review generated commands when the context warrants it ## Known limitations - Directory restrictions are guardrails, not sandboxing — terminal commands can reach files outside `allowedDirectories`. - The command blocklist can be circumvented via substitution, absolute paths, or alternate interpreters. - Desktop Commander does not protect against a compromised AI account or prompt injection reaching a trusted client. For that threat model, use OS-level isolation. ## License and responsibility Desktop Commander is free, open-source software released under the MIT License. As is standard for MIT-licensed software, it is provided "as is," without warranty, and you are responsible for how you deploy and secure it in your environment. This security model describes how the tool is designed to behave; it does not transfer responsibility for your accounts, machines, or connected AI clients to the project. ## Reporting a Vulnerability We welcome responsible disclosure and review all reported security issues. 1. **Open a GitHub issue** with technical details and, if possible, a proof of concept. 2. **Label it security-related** for visibility. 3. **Request attribution** if you'd like to be credited. If you'd prefer not to disclose publicly, reach out via Discord to arrange private disclosure. We acknowledge reports, assess severity and impact, and prioritize fixes accordingly. ## Contact - **GitHub Issues**: https://github.com/wonderwhy-er/DesktopCommanderMCP/issues - **Discord Community**: https://discord.gg/kQ27sNnZr7 --- *Last updated: July 2026*
- server.json (661 bytes)
{ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.wonderwhy-er/desktop-commander", "title": "Desktop Commander", "description": "MCP server for terminal commands, file operations, and process management", "repository": { "url": "https://github.com/wonderwhy-er/DesktopCommanderMCP", "source": "github" }, "version": "0.3.4", "packages": [ { "registryType": "npm", "registryBaseUrl": "https://registry.npmjs.org", "identifier": "@wonderwhy-er/desktop-commander", "version": "0.3.4", "transport": { "type": "stdio" } } ] } - server.yaml (2844 bytes)
name: desktop-commander image: mcp/desktop-commander type: server meta: category: devops tags: - desktop-commander - devops - filesystem - terminal about: title: Desktop Commander description: Search, update, manage files and run terminal commands with AI. Configurable filesystem access and network permissions. icon: https://avatars.githubusercontent.com/u/182288589?s=200&v=4 source: project: https://github.com/wonderwhy-er/DesktopCommanderMCP branch: main dockerfile: Dockerfile run: command: - '{{desktop-commander.paths|volume-target|into}}' volumes: - '{{desktop-commander.paths|volume|into}}' disableNetwork: '{{desktop-commander.network_settings.disable_network}}' environment: - name: ALLOWED_DIRECTORIES value: '{{desktop-commander.paths|join:,}}' - name: DISABLE_NETWORK value: '{{desktop-commander.network_settings.disable_network}}' - name: NETWORK_TIMEOUT value: '{{desktop-commander.network_settings.timeout_seconds}}' config: description: Configure filesystem access and network permissions for Desktop Commander parameters: type: object properties: paths: type: array items: type: string title: Allowed Filesystem Paths description: List of directories that Desktop Commander can access. Empty array allows full filesystem access. default: - /Users/username/Desktop - /Users/username/Documents - /Users/username/Downloads network_settings: type: object title: Network Configuration properties: disable_network: type: boolean title: Disable Network Access description: When enabled, prevents the container from accessing external networks default: false timeout_seconds: type: integer title: Network Timeout (seconds) description: Timeout for network requests in seconds default: 30 minimum: 1 maximum: 300 required: - disable_network - timeout_seconds security_settings: type: object title: Security Configuration properties: enable_telemetry: type: boolean title: Enable Telemetry description: Allow Desktop Commander to collect anonymous usage statistics default: true file_size_limit_mb: type: integer title: File Size Limit (MB) description: Maximum file size that can be processed default: 100 minimum: 1 maximum: 1000 required: - enable_telemetry - file_size_limit_mb required: - paths - network_settings - security_settings - setup-claude-server.js (37470 bytes)
import { homedir, platform } from 'os'; import fs from 'fs/promises'; import path from 'path'; import { join } from 'path'; import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } from 'fs'; import { fileURLToPath } from 'url'; import { dirname } from 'path'; import { exec } from "node:child_process"; import { version as nodeVersion } from 'process'; import * as https from 'https'; import { randomUUID } from 'crypto'; // Telemetry proxy configuration const TELEMETRY_PROXY_URL = 'https://telemetry.desktopcommander.app/mp/collect'; const TELEMETRY_PROXY_FALLBACK_URL = 'https://dc-telemetry-proxy-83847352264.europe-west1.run.app/mp/collect'; // Generate a unique anonymous ID using UUID - consistent with privacy policy let uniqueUserId = 'unknown'; try { // Use randomUUID from crypto module instead of machine-id // This generates a truly random identifier not tied to hardware uniqueUserId = randomUUID(); } catch (error) { // Fall back to a semi-unique identifier if UUID generation fails uniqueUserId = `random-${Date.now()}-${Math.random().toString(36).substring(2, 15)}`; } // Setup tracking let setupSteps = []; // Track setup progress let setupStartTime = Date.now(); /** * Initialize configuration - load from disk or create default */ async function initConfigFile() { const USER_HOME = homedir(); const CONFIG_DIR = path.join(USER_HOME, '.claude-server-commander'); // Paths relative to the config directory const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json'); try { // Ensure config directory exists const configDir = path.dirname(CONFIG_FILE); if (!existsSync(configDir)) { mkdirSync(configDir, { recursive: true }); } // Check if config file exists try { await fs.access(CONFIG_FILE); // Load existing config const configData = await fs.readFile(CONFIG_FILE, 'utf8'); } catch (error) { const defaultConfig = { blockedCommands: [ // Disk and partition management "mkfs", // Create a filesystem on a device "format", // Format a storage device (cross-platform) "mount", // Mount a filesystem "umount", // Unmount a filesystem "fdisk", // Manipulate disk partition tables "dd", // Convert and copy files, can write directly to disks "parted", // Disk partition manipulator "diskpart", // Windows disk partitioning utility // System administration and user management "sudo", // Execute command as superuser "su", // Substitute user identity "passwd", // Change user password "adduser", // Add a user to the system "useradd", // Create a new user "usermod", // Modify user account "groupadd", // Create a new group "chsh", // Change login shell "visudo", // Edit the sudoers file // System control "shutdown", // Shutdown the system "reboot", // Restart the system "halt", // Stop the system "poweroff", // Power off the system "init", // Change system runlevel // Network and security "iptables", // Linux firewall administration "firewall", // Generic firewall command "netsh", // Windows network configuration // Windows system commands "sfc", // System File Checker "bcdedit", // Boot Configuration Data editor "reg", // Windows registry editor "net", // Network/user/service management "sc", // Service Control manager "runas", // Execute command as another user "cipher", // Encrypt/decrypt files or wipe data "takeown" // Take ownership of files ], clientId: uniqueUserId, // Use the generated UUID as client ID defaultShell: platform() === 'win32' ? 'powershell.exe' : '/bin/sh', allowedDirectories: [], telemetryEnabled: true, // Default to opt-out approach (telemetry on by default) fileWriteLineLimit: 50, // Default line limit for file write operations (changed from 100) fileReadLineLimit: 1000 // Default line limit for file read operations (changed from character-based) }; logToFile('User id ' + uniqueUserId); try { await fs.writeFile(CONFIG_FILE, JSON.stringify(defaultConfig, null, 2), 'utf8'); } catch (error) { console.error('Failed to save config:', error); throw error; } } } catch (error) { console.error('Failed to initialize config:', error); } } // Function to get npm version async function getNpmVersion() { try { return new Promise((resolve, reject) => { exec('npm --version', (error, stdout, stderr) => { if (error) { resolve('unknown'); return; } resolve(stdout.trim()); }); }); } catch (error) { return 'unknown'; } } const getVersion = async () => { try { if (process.env.npm_package_version) { return process.env.npm_package_version; } // Check if version.js exists in dist directory (when running from root) const versionPath = join(__dirname, 'version.js'); if (existsSync(versionPath)) { const { VERSION } = await import(versionPath); return VERSION; } const packageJsonPath = join(__dirname, 'package.json'); if (existsSync(packageJsonPath)) { const packageJsonContent = readFileSync(packageJsonPath, 'utf8'); const packageJson = JSON.parse(packageJsonContent); if (packageJson.version) { return packageJson.version; } } return 'unknown'; } catch (error) { return 'unknown'; } }; // Function to detect shell environment function detectShell() { // Check for Windows shells if (process.platform === 'win32') { if (process.env.TERM_PROGRAM === 'vscode') return 'vscode-terminal'; if (process.env.WT_SESSION) return 'windows-terminal'; if (process.env.SHELL?.includes('bash')) return 'git-bash'; if (process.env.TERM?.includes('xterm')) return 'xterm-on-windows'; if (process.env.ComSpec?.toLowerCase().includes('powershell')) return 'powershell'; if (process.env.PROMPT) return 'cmd'; // WSL detection if (process.env.WSL_DISTRO_NAME || process.env.WSLENV) { return `wsl-${process.env.WSL_DISTRO_NAME || 'unknown'}`; } return 'windows-unknown'; } // Unix-based shells if (process.env.SHELL) { const shellPath = process.env.SHELL.toLowerCase(); if (shellPath.includes('bash')) return 'bash'; if (shellPath.includes('zsh')) return 'zsh'; if (shellPath.includes('fish')) return 'fish'; if (shellPath.includes('ksh')) return 'ksh'; if (shellPath.includes('csh')) return 'csh'; if (shellPath.includes('dash')) return 'dash'; return `other-unix-${shellPath.split('/').pop()}`; } // Terminal emulators and IDE terminals if (process.env.TERM_PROGRAM) { return process.env.TERM_PROGRAM.toLowerCase(); } return 'unknown-shell'; } // Function to get the package spec that was used to run this script function getPackageSpec(versionArg = null) { // If explicit version/tag argument provided, use it // Usage: npx @wonderwhy-er/desktop-commander setup alpha if (versionArg) { return `@wonderwhy-er/desktop-commander@${versionArg}`; } // Check if running via npx - look for the package spec in process.argv // e.g., npx @wonderwhy-er/[email protected] setup const argv = process.argv; // Look for the package name in argv for (let i = 0; i < argv.length; i++) { const arg = argv[i]; if (arg.includes('@wonderwhy-er/desktop-commander')) { // Extract just the package spec (e.g., @wonderwhy-er/[email protected]) const match = arg.match(/(@wonderwhy-er\/desktop-commander(@[^\/\s]+)?)/); if (match) { return match[1]; } } } // Fallback to @latest if we can't detect return '@wonderwhy-er/desktop-commander@latest'; } function isNPX() { return process.env.npm_lifecycle_event === 'npx' || process.env.npm_execpath?.includes('npx') || process.env._?.includes('npx') || import.meta.url.includes('node_modules'); } // Function to determine execution context function getExecutionContext() { // Check if running from npx const isNpx = isNPX(); // Check if installed globally const isGlobal = process.env.npm_config_global === 'true' || process.argv[1]?.includes('node_modules/.bin'); // Check if it's run from a script in package.json const isNpmScript = !!process.env.npm_lifecycle_script; return { runMethod: isNpx ? 'npx' : (isGlobal ? 'global' : (isNpmScript ? 'npm_script' : 'direct')), isCI: !!process.env.CI || !!process.env.GITHUB_ACTIONS || !!process.env.TRAVIS || !!process.env.CIRCLECI, shell: detectShell() }; } // Helper function to get standard environment properties for tracking let npmVersionCache = null; // Enhanced version with step tracking - will replace the original after initialization async function enhancedGetTrackingProperties(additionalProps = {}) { const propertiesStep = addSetupStep('get_tracking_properties'); try { if (npmVersionCache === null) { npmVersionCache = await getNpmVersion(); } const context = getExecutionContext(); const version = await getVersion(); updateSetupStep(propertiesStep, 'completed'); return { platform: platform(), node_version: nodeVersion, npm_version: npmVersionCache, execution_context: context.runMethod, is_ci: context.isCI, shell: context.shell, app_version: version, engagement_time_msec: "100", ...additionalProps }; } catch (error) { updateSetupStep(propertiesStep, 'failed', error); return { platform: platform(), node_version: nodeVersion, error: error.message, engagement_time_msec: "100", ...additionalProps }; } } // Enhanced tracking function with retries and better error handling // This replaces the basic implementation for all tracking after initialization async function trackEvent(eventName, additionalProps = {}) { const trackingStep = addSetupStep(`track_event_${eventName}`); // Add retry capability const maxRetries = 2; let attempt = 0; let lastError = null; while (attempt <= maxRetries) { try { attempt++; // Get enriched properties const eventProperties = await enhancedGetTrackingProperties(additionalProps); // Prepare telemetry payload const payload = { client_id: uniqueUserId, non_personalized_ads: false, timestamp_micros: Date.now() * 1000, events: [{ name: eventName, params: eventProperties }] }; // Send to telemetry proxy const postData = JSON.stringify(payload); const options = { method: 'POST', headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(postData) } }; const result = await postTelemetryPayload(postData, options); if (!result.success) throw new Error('Telemetry proxy request failed'); updateSetupStep(trackingStep, 'completed'); return result; } catch (error) { lastError = error; if (attempt <= maxRetries) { // Wait before retry (exponential backoff) await new Promise(resolve => setTimeout(resolve, 1000 * attempt)); } } } // All retries failed updateSetupStep(trackingStep, 'failed', lastError); return false; } async function postTelemetryPayload(postData, options) { for (const endpoint of [TELEMETRY_PROXY_URL, TELEMETRY_PROXY_FALLBACK_URL]) { const result = await new Promise((resolve) => { let settled = false; let timeoutId; const finish = (result) => { if (settled) return; settled = true; clearTimeout(timeoutId); resolve(result); }; const req = https.request(endpoint, options); timeoutId = setTimeout(() => { req.destroy(); finish({ success: false, data: '' }); }, 5000); req.on('error', () => { finish({ success: false, data: '' }); }); req.on('response', (res) => { let data = ''; res.on('data', (chunk) => { data += chunk; }); res.on('error', () => { finish({ success: false, data: '' }); }); res.on('end', () => { finish({ success: res.statusCode >= 200 && res.statusCode < 300, data }); }); res.on('close', () => { finish({ success: false, data: '' }); }); }); req.write(postData); req.end(); }); if (result.success) return result; } return { success: false, data: '' }; } // Ensure tracking completes before process exits async function ensureTrackingCompleted(eventName, additionalProps = {}, timeoutMs = 6000) { return new Promise(async (resolve) => { const timeoutId = setTimeout(() => { resolve(false); }, timeoutMs); try { await trackEvent(eventName, additionalProps); clearTimeout(timeoutId); resolve(true); } catch (error) { clearTimeout(timeoutId); resolve(false); } }); } // Fix for Windows ESM path resolution const __filename = fileUR - SKILL.md (5845 bytes)
--- name: ai-tools-setup version: 0.1.0 audience: agent description: >- Set up, connect, validate, and repair Claude Desktop and MCP servers using Desktop Commander — inspecting and fixing mcp.json / claude_desktop_config.json, getting MCP servers to connect, and diagnosing local AI tooling. Use when a user wants to install, configure, connect, validate, or fix Claude Desktop, an MCP server, an MCP config file, or a local AI agent/gateway. Trigger on the symptoms that actually bring people in: "Claude can't see my tools", "my MCP server isn't showing up", "tools aren't loading in Claude", "add an MCP server", "my MCP isn't connecting", "fix my Claude Desktop config", "the agent won't respond", "wire up Ollama / LM Studio", "restart Claude Desktop". Also covers local agent gateways like OpenClaw and Hermes. --- # AI Tools Setup Assistant Help users install, configure, and repair AI tooling on their own machine using Desktop Commander's file and terminal tools. The work is usually **configure-and-troubleshoot**, not clean installs — assume something already exists and may be half-broken. ## Golden rules (read before doing anything) 1. **Detect the OS and shell first.** Read `get_config` and use its `systemInfo` and `allowedDirectories` — file paths, commands, and config locations differ across macOS, Windows, and Linux, so confirm the platform before assuming anything. 2. **Verify the model/API key works before you build.** The most common reason these sessions dead-end is a provider auth or billing error discovered *after* a lot of setup work. Make one tiny test call with `start_process` (a quick curl to the provider) early, and tell the user plainly if the key is invalid or out of credit. 3. **Translate errors, don't dump them.** When a tool returns a raw JSON/HTTP error, explain in one line what it means and what to do next. If a model is missing, deprecated, rate-limited, or doesn't support tool-calling, suggest a concrete working alternative instead of retrying the same thing. 4. **Never echo secrets.** API keys, tokens, and passwords go *into the right config or `.env` file* — never repeated back in chat. If a user pastes a live secret, warn them, use it, and suggest they rotate it if it was shared insecurely. Redact secrets in any output, logs, or summaries you produce. 5. **Back up before you edit.** Copy the config to a `.bak` first with `start_process` (`cp file.json file.json.bak`, or `copy` on Windows), then make the change with `edit_block` so existing entries survive — reach for `write_file` only on a from-scratch config. Validate the JSON after every edit by parsing it with `start_process`. 6. **Verify, then stop.** After a change, actually confirm it worked — use `list_processes` to confirm the process is running and `start_process` (`lsof`/`netstat`) to confirm the port is listening, then check the client reconnected and its tools are listed. Don't declare success on a guess. 7. **Make it repeatable.** Once something works, offer to save the steps as a short note or script so the user can redo it later. ## What this skill covers This skill routes to one of three reference files depending on the task. Read the relevant file before acting — they contain the exact paths, commands, and known failure modes. - **Claude Desktop & MCP servers** — installing Claude Desktop, adding MCP servers, and inspecting / validating / repairing MCP config files (`claude_desktop_config.json`, `.claude/mcp.json`, `~/.lmstudio/mcp.json`, and similar). Also connection health checks. → Read [`references/claude-desktop-mcp.md`](references/claude-desktop-mcp.md) - **OpenClaw** — a self-hosted multi-channel gateway for AI agents. Install, onboard, wire a model/provider, connect channels (Telegram, Slack, iMessage, etc.), diagnose the gateway, and uninstall. → Read [`references/openclaw.md`](references/openclaw.md) - **Hermes** — disambiguate first: **Hermes Agent** (the Nous Research self-improving agent framework) vs. **Hermes 3** (just a local LLM you run via Ollama). Install, run `hermes setup --portal`, configure providers, personality (`SOUL.md`), memory/skills, MCP, and messaging. → Read [`references/hermes.md`](references/hermes.md) When in doubt about a tool's current behavior, fetch the official docs: OpenClaw — https://docs.openclaw.ai/ · Hermes — https://hermes-agent.nousresearch.com/docs/ ## General workflow 1. **Clarify the goal and platform.** Install vs. configure vs. fix? Which OS? Which tool/client? 2. **Inspect current state.** `read_file` the relevant config files and use `list_processes` to check whether the relevant process/port/service is already running before changing anything. 3. **Read the matching reference file** for exact paths and commands. 4. **Make the smallest change that moves forward**, backing up configs first. 5. **Verify** the result concretely. 6. **Summarize** what changed, where, and how to undo it — with secrets redacted. ## A generic "my agent isn't responding" diagnostic Use this order for OpenClaw, Hermes, or any local agent/gateway: 1. **Provider/auth** — is a valid API key configured for the active provider, and does it have credit? (Most failures stop here.) 2. **Model** — does the chosen model exist, and does it support tool-calling? Local models especially often don't. 3. **Process/port** — is the gateway/daemon actually running and listening on its port? Is another process holding that port? 4. **Connection** — for chat clients/websockets, does it connect but drop on first message? That usually points back to provider/model, not networking. 5. **Logs** — read the tool's logs for the first real error, not the last one.
- skills/ai-tools-setup/references/claude-desktop-mcp.md (3767 bytes)
# Claude Desktop & MCP Servers How to install Claude Desktop, add MCP servers, and inspect / validate / repair MCP configuration files. This is the most common and most mechanical task — high success rate when done carefully. ## Config file locations MCP-capable clients each keep their own config. Find the right one first. | Client | macOS | Windows | |---|---|---| | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | `%APPDATA%\Claude\claude_desktop_config.json` | | Claude Code (per project) | `<project>/.claude/mcp.json` or `.mcp.json` | same | | LM Studio | `~/.lmstudio/mcp.json` | `%USERPROFILE%\.lmstudio\mcp.json` | | Cursor | `~/.cursor/mcp.json` | `%USERPROFILE%\.cursor\mcp.json` | If the file doesn't exist yet, create it with a minimal valid skeleton: ```json { "mcpServers": {} } ``` ## Anatomy of an MCP server entry A stdio server entry has a launch `command`, `args`, and optional `env`: ```json { "mcpServers": { "example": { "command": "npx", "args": ["-y", "@scope/some-mcp-server"], "env": { "SOME_API_KEY": "..." } } } } ``` Notes: - On Windows, `npx` sometimes must be invoked as `cmd /c npx ...` — if a server fails to launch on Windows but works on macOS, try wrapping the command. - Use absolute paths for local scripts; `~` is not expanded inside JSON. - Secrets belong in `env` here (or the server's own config), never pasted into chat. ## Add a server end-to-end 1. **Confirm prerequisites.** Most MCP servers need Node (check `node -v`; many need 18+). Some need Python or Docker. Install the runtime if missing. 2. **Back up the config** (`claude_desktop_config.json` → `claude_desktop_config.json.bak`). 3. **Add the server block** under `mcpServers`. Preserve existing entries. 4. **Validate the JSON** (parse it; check for trailing commas, unescaped backslashes in Windows paths, missing quotes). 5. **Fully restart the client.** Claude Desktop must be quit and reopened — a window reload is not enough. 6. **Verify.** Confirm the server appears and its tools are listed. If the client shows a "failed" server, read its MCP log. ## Inspect, validate, repair (the core job) When a user says MCP "isn't working," diagnose in this order: 1. **Read the config file** and pretty-print it. Most breakages are here. 2. **Validate JSON.** The frequent culprits: - trailing comma after the last entry - single backslashes in Windows paths (need `\\` or forward slashes) - smart quotes from copy-paste instead of straight quotes - a server block pasted at the wrong nesting level 3. **Check the launch command resolves** — does `command` exist on PATH? Run it manually in a terminal to see the real error. 4. **Check credentials** — is the required `env` key present and valid? 5. **Repair, back up first, restart the client, then re-verify.** ## Connection health check Separate the three failure classes so you fix the right thing: - **Config typo** → client shows the server as failed immediately on start; the JSON or command is wrong. Fix the file. - **Server down / crashes** → server starts then exits; running the command manually reproduces the crash. Fix deps/runtime. - **Auth failure** → server starts and lists tools, but calls fail with 401/403. Fix the API key/token. ## Claude Desktop install If Claude Desktop itself isn't installed, point the user to the official download and confirm the app launches before touching MCP config. Don't side-load from unofficial mirrors. ## Safety - Only add MCP servers from sources the user trusts; an MCP server runs with the user's privileges. - Back up before editing; redact secrets in summaries; restart the client to apply changes. - skills/ai-tools-setup/references/hermes.md (3902 bytes)
# Hermes **Disambiguate first — "Hermes" means two different things:** 1. **Hermes Agent** — the self-improving AI agent framework built by Nous Research (a learning loop that creates/improves skills, persistent memory, runs across many platforms). This is almost always what users mean when they say "set up Hermes." Docs: https://hermes-agent.nousresearch.com/docs/ 2. **Hermes 3 (and other Hermes models)** — Nous Research's open-weight LLMs. "Set up Hermes 3" usually just means running a local model: `ollama pull hermes3` then `ollama run hermes3`. If that's the goal, treat it as ordinary local-model setup and stop here. The rest of this file covers **Hermes Agent**. MIT licensed. For current commands, fetch the docs (there's also `/docs/llms.txt` for a compact index). ## Install **Desktop app (Windows/macOS):** download the Hermes Desktop installer from https://hermes-agent.nousresearch.com/ and run it (installs CLI + desktop app). **CLI only:** ```bash # Linux / macOS / WSL2 / Android (Termux) curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` ```powershell # Windows (native), in PowerShell iex (irm https://hermes-agent.nousresearch.com/install.ps1) ``` See the full Installation Guide for what the installer does, per-user vs. root layout, and Windows notes. ## Fastest path to a working agent ```bash hermes setup --portal ``` One OAuth via **Nous Portal** covers a model plus the four Tool Gateway tools (web search, image generation, TTS, browser). This is the smoothest first run — recommend it unless the user specifically wants their own provider keys. ## Providers & config Hermes works with **Nous Portal, OpenRouter, OpenAI, or any compatible endpoint**. Configuration lives in Hermes' config file (see the Configuration docs). Common requests: - Wire OpenRouter / OpenAI / a custom endpoint with the user's own key — verify the key works before going further. - "Use my workspace Gemini / no API cost" and similar — set the matching provider/model in config; confirm the model ID is current and supported. - If a Portal login code is rejected, re-run `hermes setup --portal` and check the user is pasting the current code. ## Key features to configure - **Personality (`SOUL.md`)** — defines the agent's default voice/tone. Users often ask to generate or update it. Keep it a plain Markdown persona file. - **Memory** — persistent, grows across sessions; mostly automatic. - **Skills** — procedural memory the agent creates and reuses; compatible with the open agentskills.io standard, so skills are portable. - **MCP integration** — Hermes can connect to MCP servers and filter their tools. For config-file mechanics, see `claude-desktop-mcp.md`; for Hermes-side specifics see the docs' MCP page. - **Messaging gateway** — Telegram, Discord, Slack, WhatsApp, Signal, Teams, and 20+ platforms from one gateway. Telegram is the quickest to validate. - **Backends** — Hermes can run on 6 terminal backends: local, Docker, SSH, Daytona, Singularity, Modal. Daytona/Modal give serverless persistence (idle ≈ free). Pick local for a first run; Docker if the user wants isolation. ## Troubleshooting checklist 1. **Install/update stuck** → check the installer/log output; confirm the runtime and PATH; on Windows watch for permission/antivirus interference. Re-run the installer if needed. 2. **"Agent won't respond / got stuck"** → run the generic diagnostic: provider key valid + has credit → model exists and supports tools → process running → read logs for the first real error. 3. **Portal/auth errors** → re-run `hermes setup --portal`; verify the account and code. 4. **Provider model errors (404/402/403)** → switch to a current, available model. See the FAQ & Troubleshooting page in the docs for tool- and platform-specific fixes.
- skills/ai-tools-setup/references/openclaw.md (3867 bytes)
# OpenClaw OpenClaw is a self-hosted, multi-channel **gateway for AI agents** — one Gateway process bridges chat apps (Discord, iMessage, Signal, Slack, Telegram, WhatsApp, and more) to an AI agent. MIT licensed. Official docs: https://docs.openclaw.ai/ (append `/index.md` or use the "View as Markdown" links for clean text). Always confirm current commands against the docs — OpenClaw releases often. ## Install & first run Requirements: Node 24 recommended (Node 22.19+ works), plus an API key from a model provider. ```bash # Install npm install -g openclaw@latest # Guided onboarding + install the background service openclaw onboard --install-daemon # Open the browser Control UI openclaw dashboard ``` The Control UI default is `http://127.0.0.1:18789/`. (Some versions/setups use a nearby port — if 18789 doesn't load, check the onboarding output or `openclaw doctor` for the actual port.) Fastest way to chat from a phone: connect the **Telegram** channel. ## Config - Main config lives at `~/.openclaw/openclaw.json`. - With no config, OpenClaw uses its bundled agent runtime with per-sender sessions. - Lock-down basics: channel allowlists (e.g. `channels.whatsapp.allowFrom`) and group mention rules. Run the built-in diagnostics whenever something is off: ```bash openclaw doctor ``` If it reports "Config invalid," fix the JSON (back it up first) and re-run. ## Providers & models (the most common pain) OpenClaw needs a model provider configured. Recurring issues and fixes: - **"No API key found for provider X"** — auth is configured per agent. Add the provider's credentials for the active agent (via onboarding/`openclaw agents`), or copy the auth profile from the main agent. Confirm the key is valid and has credit *before* further setup. - **Model doesn't support tools** — some local models (e.g. certain distilled reasoning models) can't do tool-calling, which the agent needs. Switch to a model that supports tools. - **Local models** — running via Ollama or LM Studio is common for cost reasons. Watch for: the local server not running, the wrong base URL/port, GPU not engaged / high RAM, and prompt-template mismatches (LM Studio "jinja" errors — switch the model's preset/template). See the docs' Models/Providers section. - **Provider churn** — model names get deprecated and accounts get rate-limited or model-blocked. When you hit a 402/403/404 from a provider, switch to a current, available model rather than retrying. For best quality and security the docs recommend the strongest current-gen model available. ## Channels Each chat platform is a "channel" with its own setup (token/pairing). Telegram is the quickest to validate. Configure one channel, confirm a round-trip message, then add others. See https://docs.openclaw.ai/channels. ## Remote access To reach the gateway from outside the machine, use the documented patterns (SSH / tailnet). Tailscale is covered at https://docs.openclaw.ai/gateway/tailscale. Avoid exposing the dashboard directly to the public internet. ## Troubleshooting checklist 1. `openclaw doctor` — start here. 2. **Gateway `Unauthorized`** at the dashboard URL → the gateway token/auth isn't set or the URL/port is wrong; re-check onboarding output and config. 3. **Connects but `disconnected (1006): no reason`** on first message → almost always a provider/model problem (missing key, unsupported model), not the network. Run the provider/model checks above. 4. **Module/runtime errors** → confirm Node version; reinstall if needed. 5. Read logs with `openclaw logs --follow`. ## Uninstall / cleanup - Stop the service/daemon, then `npm uninstall -g openclaw`. - Remove residual files in `~/.openclaw/` (back up first if it holds config the user may want). - Disable any autostart entry created during onboarding.
- skills/ai-tools-setup/SKILL.md (5845 bytes)
--- name: ai-tools-setup version: 0.1.0 audience: agent description: >- Set up, connect, validate, and repair Claude Desktop and MCP servers using Desktop Commander — inspecting and fixing mcp.json / claude_desktop_config.json, getting MCP servers to connect, and diagnosing local AI tooling. Use when a user wants to install, configure, connect, validate, or fix Claude Desktop, an MCP server, an MCP config file, or a local AI agent/gateway. Trigger on the symptoms that actually bring people in: "Claude can't see my tools", "my MCP server isn't showing up", "tools aren't loading in Claude", "add an MCP server", "my MCP isn't connecting", "fix my Claude Desktop config", "the agent won't respond", "wire up Ollama / LM Studio", "restart Claude Desktop". Also covers local agent gateways like OpenClaw and Hermes. --- # AI Tools Setup Assistant Help users install, configure, and repair AI tooling on their own machine using Desktop Commander's file and terminal tools. The work is usually **configure-and-troubleshoot**, not clean installs — assume something already exists and may be half-broken. ## Golden rules (read before doing anything) 1. **Detect the OS and shell first.** Read `get_config` and use its `systemInfo` and `allowedDirectories` — file paths, commands, and config locations differ across macOS, Windows, and Linux, so confirm the platform before assuming anything. 2. **Verify the model/API key works before you build.** The most common reason these sessions dead-end is a provider auth or billing error discovered *after* a lot of setup work. Make one tiny test call with `start_process` (a quick curl to the provider) early, and tell the user plainly if the key is invalid or out of credit. 3. **Translate errors, don't dump them.** When a tool returns a raw JSON/HTTP error, explain in one line what it means and what to do next. If a model is missing, deprecated, rate-limited, or doesn't support tool-calling, suggest a concrete working alternative instead of retrying the same thing. 4. **Never echo secrets.** API keys, tokens, and passwords go *into the right config or `.env` file* — never repeated back in chat. If a user pastes a live secret, warn them, use it, and suggest they rotate it if it was shared insecurely. Redact secrets in any output, logs, or summaries you produce. 5. **Back up before you edit.** Copy the config to a `.bak` first with `start_process` (`cp file.json file.json.bak`, or `copy` on Windows), then make the change with `edit_block` so existing entries survive — reach for `write_file` only on a from-scratch config. Validate the JSON after every edit by parsing it with `start_process`. 6. **Verify, then stop.** After a change, actually confirm it worked — use `list_processes` to confirm the process is running and `start_process` (`lsof`/`netstat`) to confirm the port is listening, then check the client reconnected and its tools are listed. Don't declare success on a guess. 7. **Make it repeatable.** Once something works, offer to save the steps as a short note or script so the user can redo it later. ## What this skill covers This skill routes to one of three reference files depending on the task. Read the relevant file before acting — they contain the exact paths, commands, and known failure modes. - **Claude Desktop & MCP servers** — installing Claude Desktop, adding MCP servers, and inspecting / validating / repairing MCP config files (`claude_desktop_config.json`, `.claude/mcp.json`, `~/.lmstudio/mcp.json`, and similar). Also connection health checks. → Read [`references/claude-desktop-mcp.md`](references/claude-desktop-mcp.md) - **OpenClaw** — a self-hosted multi-channel gateway for AI agents. Install, onboard, wire a model/provider, connect channels (Telegram, Slack, iMessage, etc.), diagnose the gateway, and uninstall. → Read [`references/openclaw.md`](references/openclaw.md) - **Hermes** — disambiguate first: **Hermes Agent** (the Nous Research self-improving agent framework) vs. **Hermes 3** (just a local LLM you run via Ollama). Install, run `hermes setup --portal`, configure providers, personality (`SOUL.md`), memory/skills, MCP, and messaging. → Read [`references/hermes.md`](references/hermes.md) When in doubt about a tool's current behavior, fetch the official docs: OpenClaw — https://docs.openclaw.ai/ · Hermes — https://hermes-agent.nousresearch.com/docs/ ## General workflow 1. **Clarify the goal and platform.** Install vs. configure vs. fix? Which OS? Which tool/client? 2. **Inspect current state.** `read_file` the relevant config files and use `list_processes` to check whether the relevant process/port/service is already running before changing anything. 3. **Read the matching reference file** for exact paths and commands. 4. **Make the smallest change that moves forward**, backing up configs first. 5. **Verify** the result concretely. 6. **Summarize** what changed, where, and how to undo it — with secrets redacted. ## A generic "my agent isn't responding" diagnostic Use this order for OpenClaw, Hermes, or any local agent/gateway: 1. **Provider/auth** — is a valid API key configured for the active provider, and does it have credit? (Most failures stop here.) 2. **Model** — does the chosen model exist, and does it support tool-calling? Local models especially often don't. 3. **Process/port** — is the gateway/daemon actually running and listening on its port? Is another process holding that port? 4. **Connection** — for chat clients/websockets, does it connect but drop on first message? That usually points back to provider/model, not networking. 5. **Logs** — read the tool's logs for the first real error, not the last one.
- skills/computer-health-check/references/linux.md (3477 bytes)
# Linux command set Read-only diagnostics, **no sudo**. Targets common distros (Debian/Ubuntu, Fedora, Arch). Some tools (`smartctl`, `upower`) may be absent or need root for full detail — degrade gracefully. ## Collection script (run as one batched process) ```bash bash -c ' echo "== SYSTEM =="; (. /etc/os-release 2>/dev/null; echo "$PRETTY_NAME"); uname -r; uptime -p 2>/dev/null || uptime echo "== HARDWARE =="; echo "CPUs: $(nproc)"; grep -m1 "model name" /proc/cpuinfo | cut -d: -f2 | sed "s/^ //" echo "== DISK =="; df -h / /home 2>/dev/null | grep -v tmpfs echo "== DISK HEALTH =="; lsblk -d -o NAME,SIZE,ROTA,MODEL 2>/dev/null echo "== MEMORY =="; free -h echo "swap:"; swapon --show 2>/dev/null || echo "none" echo "== TOP CPU =="; ps -eo pid,pcpu,pmem,comm --sort=-pcpu | head -n 8 echo "== TOP MEM =="; ps -eo pid,pcpu,pmem,comm --sort=-rss | head -n 8 echo "== BATTERY =="; for b in /sys/class/power_supply/BAT*; do [ -d "$b" ] && { echo "capacity: $(cat $b/capacity 2>/dev/null)%"; echo "health: $(cat $b/health 2>/dev/null)"; cf=$(cat $b/charge_full 2>/dev/null); cd=$(cat $b/charge_full_design 2>/dev/null); [ -n "$cf" ] && [ -n "$cd" ] && echo "wear: $((100*cf/cd))% of design"; }; done echo "== STARTUP =="; echo "enabled user services: $(systemctl --user list-unit-files --state=enabled 2>/dev/null | grep -c enabled)"; ls -1 "$HOME/.config/autostart" 2>/dev/null echo "== STORAGE HOTSPOTS ==" for d in "$HOME/Downloads" "$HOME/.cache" "$HOME/.local/share/Trash"; do [ -d "$d" ] && printf "%s\t%s\n" "$(du -sh "$d" 2>/dev/null | cut -f1)" "${d/#$HOME/~}" done echo "== PACKAGES ==" if command -v apt >/dev/null 2>&1; then echo "apt upgradable: $(apt list --upgradable 2>/dev/null | grep -c upgradable)" elif command -v dnf >/dev/null 2>&1; then echo "dnf updates: $(dnf check-update -q 2>/dev/null | grep -c .)" elif command -v pacman >/dev/null 2>&1; then echo "pacman updates: $(checkupdates 2>/dev/null | wc -l)"; fi echo "== DONE =="' ``` ## How to read it - **Memory:** `free -h` — focus on the `available` column (real headroom) and whether swap `used` is climbing. High swap use with low available = 🟡/🔴. - **Disk health:** `lsblk` confirms devices; full SMART needs `sudo smartctl -H /dev/sdX` (skip — needs root). Report SMART as "not available without elevation" rather than guessing. - **Battery:** the `charge_full / charge_full_design` ratio is the wear %. Skip if no `BAT*`. - **Startup:** `~/.config/autostart` and enabled `--user` units are the actionable third-party items. ## Optional deeper checks (run only if asked) ```bash journalctl -p 3 -b --no-pager | tail -n 30 # recent boot errors (may need group access) du -xh "$HOME" 2>/dev/null | sort -rh | head -n 15 # biggest dirs in home ping -c 4 8.8.8.8 # connectivity ``` ## Cleanup commands (suggest; run only on approval) - **Empty Trash (safe):** `rm -rf "$HOME/.local/share/Trash/"*`. - **User cache (safe, regenerates):** review `du -sh ~/.cache/* | sort -rh | head` then clear specific large entries; avoid blanket deletion. - **Package cache (user action; usually needs sudo):** `apt-get clean`, `dnf clean all`, or `pacman -Sc` — note these typically require root, so suggest rather than run. - **Updates (user action; needs sudo):** `apt upgrade` / `dnf upgrade` / `pacman -Syu`. - **Startup items (user action):** remove `.desktop` files from `~/.config/autostart`, or `systemctl --user disable <unit>`. - skills/computer-health-check/references/macos.md (3364 bytes)
# macOS command set All commands here are read-only and run **without sudo**. Verified on macOS 26 / Apple Silicon. ## Collection script (run as one batched process) Run this with `start_process` (timeout ~30s). It prints labeled sections you can parse. ```bash zsh -c ' echo "== SYSTEM =="; sw_vers; echo "uptime:"; uptime echo "== HARDWARE =="; system_profiler SPHardwareDataType 2>/dev/null | grep -Ei "Model Name|Chip|Total Number of Cores|Memory:" echo "== DISK =="; df -h / diskutil info / 2>/dev/null | grep -Ei "SMART|Free Space" echo "== MEMORY =="; vm_stat | head -n 8 echo "swap:"; sysctl -n vm.swapusage echo "== TOP CPU =="; ps -Ao pid,pcpu,pmem,comm -r | head -n 8 echo "== TOP MEM =="; ps -Ao pid,pcpu,pmem,comm -m | head -n 8 echo "== BATTERY =="; pmset -g batt | head -n 2 system_profiler SPPowerDataType 2>/dev/null | grep -Ei "Cycle Count|Condition|Maximum Capacity" echo "== THERMAL =="; pmset -g therm 2>/dev/null | head -n 3 echo "== STARTUP =="; echo "user agents:"; ls -1 "$HOME/Library/LaunchAgents" 2>/dev/null echo "service count: $(launchctl list 2>/dev/null | wc -l | tr -d " ")" echo "== STORAGE HOTSPOTS ==" for d in "$HOME/Downloads" "$HOME/Library/Caches" "$HOME/.Trash" "$HOME/Library/Logs"; do [ -d "$d" ] && printf "%s\t%s\n" "$(du -sh "$d" 2>/dev/null | cut -f1)" "${d/#$HOME/~}" done echo "== PACKAGES ==" command -v brew >/dev/null 2>&1 && echo "brew outdated: $(brew outdated 2>/dev/null | wc -l | tr -d " "), cache: $(du -sh "$(brew --cache)" 2>/dev/null | cut -f1)" || echo "brew: not installed" echo "== CRASH REPORTS =="; ls -1 "$HOME/Library/Logs/DiagnosticReports" 2>/dev/null | wc -l echo "== DONE =="' ``` ## How to read it - **Memory pressure:** page size is 16 KB on Apple Silicon. Healthy = meaningful free+inactive pages and near-zero swap "used". If `vm.swapusage` shows hundreds of MB / GB used, that's 🟡/🔴. - **Battery:** `Maximum Capacity` is the wear indicator; `Condition: Normal` is good. "Service Recommended" is 🔴. Skip battery entirely if `pmset -g batt` shows no internal battery (desktop). - **SMART:** `Verified` = healthy. Anything else → 🔴. - **Startup:** named third-party `LaunchAgents` are the actionable ones (e.g. updaters, helper daemons, redundant DB services). The raw `launchctl` count is mostly Apple system services. ## Optional deeper checks (run only if asked) ```bash softwareupdate -l 2>&1 | head -n 20 # pending OS updates (network, slow) networkQuality 2>/dev/null # internet up/down + responsiveness (slow) mdfind 'kMDItemFSSize > 1073741824' 2>/dev/null | head -n 20 # files >1GB, Spotlight-fast ``` ## Cleanup commands (suggest; run only on approval) - **Empty Trash (safe):** `rm -rf "$HOME/.Trash/"*` — or tell the user to empty it from Finder. - **Homebrew (safe):** `brew cleanup` (removes old versions + cache). Upgrade: `brew upgrade`. - **User caches (safe, regenerate):** clear specific large subfolders of `~/Library/Caches/<app>` — review with `du -sh ~/Library/Caches/* | sort -rh | head` first; never blanket-delete. - **Login items (user action):** System Settings → General → Login Items, or remove the specific `~/Library/LaunchAgents/<name>.plist` only if the user confirms they don't want it. - **OS updates (user action, needs restart):** System Settings → General → Software Update. - skills/computer-health-check/references/windows.md (4052 bytes)
# Windows command set Read-only diagnostics via PowerShell. None require admin. Run through `start_process` with `powershell -NoProfile -Command "..."` (or `pwsh`). Keep outputs bounded with `Select-Object`. ## Collection script (run as one batched process) ```powershell powershell -NoProfile -Command " Write-Output '== SYSTEM =='; (Get-CimInstance Win32_OperatingSystem | Select Caption,Version,LastBootUpTime | Format-List | Out-String).Trim() Write-Output '== HARDWARE =='; (Get-CimInstance Win32_ComputerSystem | Select Manufacturer,Model,@{n='RAM_GB';e={[math]::Round($_.TotalPhysicalMemory/1GB,1)}} | Format-List | Out-String).Trim() Write-Output '== DISK =='; Get-CimInstance Win32_LogicalDisk -Filter 'DriveType=3' | ForEach-Object { '{0} {1}% free ({2:N1} of {3:N1} GB)' -f \$_.DeviceID, [math]::Round(\$_.FreeSpace/\$_.Size*100), (\$_.FreeSpace/1GB), (\$_.Size/1GB) } Write-Output '== DISK HEALTH =='; (Get-PhysicalDisk | Select FriendlyName,HealthStatus,OperationalStatus | Format-Table -Auto | Out-String).Trim() Write-Output '== MEMORY =='; \$os=Get-CimInstance Win32_OperatingSystem; '{0:N1} GB free of {1:N1} GB' -f (\$os.FreePhysicalMemory/1MB),(\$os.TotalVisibleMemorySize/1MB) Write-Output '== TOP CPU =='; (Get-Process | Sort CPU -Desc | Select -First 8 Name,CPU,@{n='MB';e={[math]::Round(\$_.WS/1MB)}} | Format-Table -Auto | Out-String).Trim() Write-Output '== TOP MEM =='; (Get-Process | Sort WS -Desc | Select -First 8 Name,@{n='MB';e={[math]::Round(\$_.WS/1MB)}} | Format-Table -Auto | Out-String).Trim() Write-Output '== BATTERY =='; (Get-CimInstance Win32_Battery | Select EstimatedChargeRemaining,BatteryStatus | Format-List | Out-String).Trim() Write-Output '== STARTUP =='; (Get-CimInstance Win32_StartupCommand | Select Name,Location | Format-Table -Auto | Out-String).Trim() Write-Output '== STORAGE HOTSPOTS =='; \$d=\$env:USERPROFILE; foreach(\$p in 'Downloads','AppData\Local\Temp'){ \$f=Join-Path \$d \$p; if(Test-Path \$f){ \$s=(Get-ChildItem \$f -Recurse -EA SilentlyContinue | Measure Length -Sum).Sum; '{0:N1} GB {1}' -f (\$s/1GB), \$p } } Write-Output '== PACKAGES =='; if(Get-Command winget -EA SilentlyContinue){ (winget upgrade 2>\$null | Measure-Object -Line).Lines } else { 'winget: n/a' } Write-Output '== DONE ==' " ``` ## How to read it - **Battery health detail:** the deep wear report needs `powercfg /batteryreport` (writes an HTML file to disk) — run only on request, then read the generated file. `Win32_Battery` gives charge %, not wear. Skip battery on desktops (no `Win32_Battery` instance). - **Disk health:** `HealthStatus = Healthy` is 🟢; `Warning`/`Unhealthy` is 🔴. - **Memory:** compare free vs total; sustained <10% free under load is 🟡/🔴. Pagefile thrash shows up as high disk + low free RAM. - **Startup:** `Win32_StartupCommand` plus the Run registry keys are the actionable third-party items. - **Packages:** the winget value is a raw output-line count, not an exact upgrade count — read it as "updates pending or not," and run `winget upgrade` for the real list. ## Optional deeper checks (run only if asked) ```powershell powercfg /batteryreport /output "$env:TEMP\battery.html" # then read the file for wear % Get-WindowsUpdate # if PSWindowsUpdate module present Test-Connection -Count 4 8.8.8.8 # basic connectivity ``` ## Cleanup commands (suggest; run only on approval) - **Empty Recycle Bin (safe):** `Clear-RecycleBin -Force` (PowerShell). - **Temp files (safe, regenerate):** remove contents of `$env:TEMP` — show size first with `(Get-ChildItem $env:TEMP -Recurse -EA SilentlyContinue | Measure Length -Sum).Sum/1GB`. - **Package upgrades (user action):** `winget upgrade --all` (may prompt / need elevation per app). - **Startup items (user action):** Task Manager → Startup tab, or Settings → Apps → Startup. - **Windows updates (user action, needs restart):** Settings → Windows Update. - **Disk Cleanup (user action):** `cleanmgr` for system-level reclaim. - skills/computer-health-check/SKILL.md (8603 bytes)
--- name: computer-health-check version: 0.1.0 audience: agent description: >- Run a comprehensive, read-only health check on the user's computer and return a scored chat summary with prioritized, plain-English recommendations and safe cleanup suggestions. Use this whenever the user wants to check their computer's health, speed it up, free up / reclaim disk space, find what's eating CPU / memory / storage, check battery health and wear, audit login & startup items, see pending updates, or asks for a "tune-up", "checkup", "system report", "health check", or "is my Mac/PC/laptop healthy". Trigger even on casual phrasing like "my laptop feels slow", "why is my fan so loud", "my computer is laggy", "running out of space", or "clean up my machine". Works on macOS, Windows, and Linux. This is a Desktop Commander skill: it relies on a real local shell (start_process / interact_with_process) and is strictly read-only by default — it never needs sudo and only performs cleanups the user explicitly approves. --- # Computer Health Check ## What this skill does Give the user a fast, trustworthy picture of their computer's health and a short list of actions worth taking — the way a good technician would: look first, explain plainly, fix only with permission. It runs entirely through Desktop Commander's local shell, gathers a batch of **read-only** diagnostics, scores each area, prints a concise summary **in the chat**, and then offers cleanup suggestions the user can approve one by one. ## The safety contract (read this first) This is the part that makes users trust the skill, so honor it strictly: - **Read-only by default.** The collection phase only *observes* (sizes, counts, status). It changes nothing. - **Never use `sudo` or elevation.** DC blocks `sudo`, `shutdown`, `reboot`, `dd`, `mount`, `mkfs`, `diskpart`, etc. for good reason. Every check below is designed to work without them. If something seems to need elevation, skip it and say so — don't try to work around the block. - **Cleanups are opt-in.** You may *suggest* cleanups freely, but only *execute* one after the user explicitly approves that specific action, and only show the exact command first. - **Prefer reversible, non-destructive actions.** Emptying caches that regenerate, clearing a package-manager download cache, or emptying Trash are fine to offer. Deleting user documents, uninstalling apps, or editing system files are not — suggest those, let the user do them. ## Workflow ### Step 1 — Detect the OS Determine the platform before doing anything else, because the commands differ. - Quickest: read Desktop Commander's config (`get_config`) and use the `systemInfo.isMacOS` / `isWindows` / `isLinux` booleans (or `platformName`) to pick the platform. - Or run `uname` (macOS/Linux) — if it fails, assume Windows. Then open the matching reference file and use its command set: - macOS → [`references/macos.md`](references/macos.md) - Windows → [`references/windows.md`](references/windows.md) - Linux → [`references/linux.md`](references/linux.md) Read **only** the one that matches. Each file contains a single batched collection script plus interpretation notes and cleanup commands. ### Step 2 — Collect (read-only) Run the batched collection script from the reference file with `start_process`. Batching everything into one call is much faster than many small calls and keeps the output tidy. Guidance: - Keep outputs bounded (`head`, `Select-Object -First`, etc.) so a long process list or file listing doesn't flood the response. - Skip the genuinely slow / network checks (full OS-update list, internet speed test) on the first pass unless the user asked about updates or network. Mention they're available. - If a single command errors (e.g., a tool isn't installed), continue — partial data is fine. ### Step 3 — Score each area Rate each category 🟢 Good / 🟡 Watch / 🔴 Act using the rubric below, then compute a simple overall score. Start at 100 and subtract 8 per 🟡 and 18 per 🔴; floor at 0. Report the number and a one-word verdict (90+ Excellent, 75–89 Good, 60–74 Fair, <60 Needs attention). | Area | 🟢 Good | 🟡 Watch | 🔴 Act | |---|---|---|---| | Free disk space | >20% free | 10–20% | <10% | | Disk health (SMART) | Verified / OK / PASSED | — | failing / not supported & errors present | | Memory pressure | low swap, free pages healthy | noticeable swap/compression | heavy swapping, near-zero free | | Battery (laptops) | ≥80% max capacity, Normal | 70–80% | <70% or "Service/Replace" | | Maintenance | uptime <7d, no pending updates | uptime 7–30d or minor updates | uptime >30d or security updates pending | | Startup load | few third-party login items | moderate | many heavy third-party agents | | Live resource hogs | nothing >50% at idle | one sustained heavy process | multiple / runaway processes | Battery is laptop-only — skip it on desktops/VMs. Reclaimable space is reported as an informational figure, not scored. ### Step 4 — Report in the chat Use this exact structure. Keep it tight and scannable — this is the deliverable. ``` 🖥️ Health Check — <Model>, <OS version> Score: <N>/100 (<verdict>) 🟢/🟡/🔴 Storage — <free> free of <total> (<%>). Reclaimable: ~<X> GB 🟢/🟡/🔴 Memory — <one-line state> 🟢/🟡/🔴 Battery — <cycles> cycles, <max capacity>%, <condition> 🟢/🟡/🔴 Maintenance — up <days>d, <updates state> 🟢/🟡/🔴 Startup — <count> login items (<notable ones>) 🟢/🟡/🔴 Right now — top: <proc> <cpu%>, <proc> <cpu%> Top recommendations 1. <highest-impact action> (<expected benefit, e.g. frees ~13 GB>) 2. <next> 3. <next> ``` List at most the 3–5 highest-impact recommendations, ordered by benefit. Don't dump every finding — the goal is signal, not a wall of text. ### Step 5 — Suggest cleanups, execute only on approval For each recommendation that maps to a concrete command (see the reference file's "Cleanup" section), offer it and show the exact command. Then: - **Safe, reversible** (offer to run on a yes): empty Trash, package-manager cache cleanup (`brew cleanup`, `npm cache clean`), clearing a regenerating user cache folder. (On Linux, `apt-get clean` / `dnf clean` need root — suggest, don't auto-run.) - **Needs the user to decide / act** (suggest, don't auto-run): disabling login items, installing OS updates (requires restart), uninstalling apps, deleting files in Downloads. - **Never**: anything requiring sudo/admin, removing system files, disk/partition operations. When the user approves a safe action, run it, then report what changed (e.g., space freed). Re-running Step 2's storage check afterward is a nice confirmation. ## Recommendation rules (findings → advice) These are the high-value mappings; adapt the wording to the platform. - **Uptime > 30 days** → "Restart your computer — it's been up <N> days. A reboot clears memory and applies pending updates." (Highest ROI, lowest effort.) - **Pending OS/security updates** → platform update step; flag security updates as higher priority. - **Free space < 15%** → lead with the biggest reclaimable buckets you measured. - **Large Downloads / Caches / Trash** → empty Trash; review largest Downloads items by name; clear caches that regenerate. - **Package manager has many outdated items / big cache** → `upgrade` + cache cleanup. - **Battery max capacity < 80%** → explain wear is normal; consider a battery service if it's affecting runtime. - **Many third-party startup agents** → name them and suggest disabling the ones the user doesn't recognize/need (point to System Settings / Task Manager — don't edit them directly). - **A process pinned high at idle** → name it and suggest quitting/investigating. ## Notes & pitfalls - **Don't assume — measure.** Always run the commands and report real numbers. Never fabricate sizes, cycle counts, or statuses. - **Bounded output.** Process and file listings can be huge; always cap them. - **Optional deep checks** (mention, run on request): internet speed test, full update list, per-folder disk scan of the whole home directory, crash-report trend analysis. - **Privacy.** This reads local system metadata only. Don't send anything off the machine; the public-IP check is optional and should be labeled. - **Cross-platform parity.** The three reference files mirror the same categories so the report looks the same regardless of OS.
- skills/desktop-commander-overview/SKILL.md (12282 bytes)
--- name: desktop-commander-overview description: Use for Desktop Commander MCP capabilities — persistent shells and REPLs, long-running processes, filesystem beyond the workspace, structured files (.xlsx, .docx, .pdf, images) and large local data files such as CSVs, ripgrep search at scale, SSH, or cross-turn state. version: 0.1.0 audience: agent --- # Desktop Commander MCP Desktop Commander gives the agent reach across the user's actual computer — files, folders, terminals, processes, structured documents, and remote machines reachable over SSH. The tools' detailed schemas (parameters, return shapes, format-specific behavior) live in the MCP itself; this skill explains what they enable and how they compose into common workflows. ## What this MCP gives the agent **Persistent shell sessions.** Desktop Commander keeps a started process or session alive across tool calls. Inside a single long-lived shell, REPL, or SSH session, state carries forward — environment variables, working directory, activated virtualenvs, open connections, REPL variables — so the agent can `cd`, activate a venv, then send commands or code into that same session many turns later without re-setup. (Note: separate `start_process` calls open separate sessions and do **not** share shell state with each other; persistence is inside one session, not across them.) **Long-running processes.** Start a dev server, watcher, build, training run, or test suite in the background and keep working. The MCP returns a process handle the agent can tail, interact with, or terminate across many turns. Long-running commands don't need to block the workflow waiting for a foreground command to exit. **Filesystem reach beyond the IDE workspace.** Read, write, move, list, and inspect files anywhere the user has granted scope — Downloads, Documents, project folders outside the IDE, or any other granted folders. Useful for organize-and-clean tasks, batch document work, and any "look at the file my coworker just sent me" request that doesn't fit inside the IDE sandbox. **Surgical edits to existing files.** The `edit_block` tool does exact-string find-and-replace with built-in safety: ambiguous matches fail loudly instead of silently overwriting the wrong thing, and an `expected_replacements` count prevents partial-match disasters. Lower data-loss risk than rewriting whole files based on the slice you happened to read — though a wrong `old_string` or wrong `expected_replacements` can still corrupt content, so review the changed content before considering the edit done. **Binary and structured files handled directly by the MCP.** Excel, DOCX, and PDF are first-class — read and modified through format-specific mechanisms rather than text-only approximations: Excel via cell-range JSON, DOCX via raw-XML edits, PDF via page-level operations on a new output file. The result is the real file in its original format, not a regenerated approximation. Images and PDFs return as viewable content for the agent. **Search at scale.** Streaming, ripgrep-backed search across whole projects or folder trees. The agent picks between filename search and in-file content search, pages through results progressively without flooding context, and runs multiple concurrent searches when the query is ambiguous. **Remote machines via SSH.** A long-lived SSH session inside a persistent shell turns the agent into a real ops tool: connect once, then tail logs, run diagnostics, deploy, or debug across many turns without reconnecting each step. **Process management.** List, inspect, tail, and kill accessible processes (subject to OS permissions). Useful for cleaning up stale dev servers from previous sessions and for diagnosing CPU / memory issues. ## Example workflows Each example names the actual tool sequence. Calls below are written in pseudocode shorthand (`tool_name("arg", flag=value)`); the real tools take object-shaped arguments. Tool descriptions and full parameter sets live in the MCP itself. ### "Debug this production issue" Before running production-impacting SSH commands, explain the intended action and get user confirmation when the risk is non-trivial. `start_process("ssh [email protected]", timeout_ms=...)` opens a long-lived SSH session and returns a PID. `interact_with_process(pid, "tail -f /var/log/app.log\n")` starts streaming logs. Subsequent turns: `read_process_output(pid, offset=-50)` to see the last 50 lines as they arrive, `interact_with_process(pid, "...")` to run diagnostic commands in the same session. `force_terminate(pid)` to close the session when done — for sessions opened by `start_process`, `force_terminate` is the correct cleanup tool; `kill_process` is for arbitrary OS PIDs found via `list_processes`. ### "Deploy this to staging" Before deploys, restarts, migrations, or other environment-changing commands, summarize the action and confirm with the user unless they already explicitly asked for that exact operation. `start_process` for the deploy command (could be a script, an SSH-piped command, or `kubectl`/`gh` etc.). `read_process_output` to track output and surface errors. If the deploy needs an interactive confirmation, `interact_with_process(pid, "yes\n")`. The session stays alive while the agent watches for completion or rollback. ### "Run the dev server and iterate on the API" `start_process("npm run dev", timeout_ms=...)` keeps the server up. The agent then loops: `edit_block` on the route file, `read_process_output(pid, offset=-30)` to see the server's reload, `start_process("curl -s http://localhost:3000/api/...")` for a one-shot test, repeat. The dev server never has to restart between code changes. ### "Refactor across this monorepo" `start_search(pattern="oldFunctionName", path=repo_root, searchType="content")` scopes every call site. `get_more_search_results(sessionId)` pages through. `read_multiple_files(paths=[...])` confirms ambiguous hits in context. `edit_block(file_path, old_string, new_string)` per site, with `expected_replacements` set when the same substring legitimately appears multiple times in one file. Verify by re-running `start_search` on the old name and paging the results with `get_more_search_results(sessionId)` until the run completes — only then can you confirm zero remaining hits. ### "Update the Q3 numbers in this spreadsheet and tweak the summary in the report" `read_file(path="/.../q3.xlsx", sheet="Revenue", range="A1:F50")` returns the existing numbers as a JSON 2D array. `edit_block(file_path="/.../q3.xlsx", range="Revenue!C12:C24", content=[[12345], ...])` updates the cells in place. For the report, DOCX editing is a two-read flow: first `read_file(path="/.../report.docx")` (offset 0) returns the document's outline (headings + paragraph text) so you can locate the summary section. Then `read_file(path="/.../report.docx", offset=N, length=...)` with **`N > 0`** returns the raw underlying XML around that section — a non-zero offset is what flips the read into XML mode. Copy an XML fragment from that output as `old_string` and call `edit_block(file_path, old_string, new_string)` with the rewritten XML. The user gets back real `.xlsx` and `.docx` files, not regenerated approximations. ### "Generate the Q3 report as a PDF" Compose markdown content (header, table, charts via embedded HTML), then call `write_pdf` to render it to a new PDF file. The MCP's `write_pdf` tool description specifies the exact parameters and filename rules — follow that. ### "Insert a cover page into this PDF" `write_pdf` also supports modifying existing PDFs via an operations array (insert / delete pages). Use it for existing-PDF edits that produce a new PDF — adding a cover page, removing a section, merging in content from another file. See the `write_pdf` tool description for the operation shapes and parameter rules. ### "Analyze this 200MB CSV" `start_process("python3 -i", timeout_ms=...)` opens a Python REPL and returns a PID. `interact_with_process(pid, "import pandas as pd; df = pd.read_csv('/abs/path.csv')")` loads it once. Every subsequent question — `df.describe()`, `df.groupby('col').size()`, plot a chart — runs in the same already-loaded REPL. Libraries don't re-import, the dataframe doesn't re-load. The MCP itself recommends this workflow for any local data-file analysis. ### "Run a quick Node script" `start_process("node:local", timeout_ms=...)` opens a stateless Node execution mode on the MCP server itself — ES imports supported. `start_process` opens the runner; each piece of JS is sent via `interact_with_process(pid, "<your JS here>")` and runs independently (no shared state between calls). Good for one-shot transformations where keeping a long-lived REPL alive isn't worth it. Don't try to put code into the `start_process` command argument — only the runner type (`node:local`) goes there. ### "Explain this codebase" `list_directory(path=repo_root, depth=3)` for shape. `start_search(pattern="export ", path=repo_root, searchType="content")` to find the public surface. `read_multiple_files(paths=[entrypoints])` for the actual code. The agent can keep narrowing without re-asking the user where to look. ### "Organize my Downloads folder" Resolve the path to absolute first (e.g., `/Users/<user>/Downloads`, not `~/Downloads`). Then `list_directory(path="/Users/<user>/Downloads", depth=1)` to see what's there. `start_search(pattern="*.pdf", path="/Users/<user>/Downloads", searchType="files")` and similar for other types. `create_directory` for new folders. `move_file` per item. Preview the move plan before executing destructive ops. ### "Onboard me — what was happening last session?" `get_recent_tool_calls(maxResults=200)` returns recent activity with arguments and outputs. `list_sessions` shows still-running terminal sessions. `list_searches` shows in-flight searches. `list_processes` shows what's still alive. Together they reconstruct the work without asking the user to recap. ### "Why isn't the REPL responding?" `list_sessions` — if `Blocked: true`, the REPL is waiting for input rather than hung. `read_process_output(pid, offset=-100)` to see what it last printed (often a prompt). `interact_with_process(pid, "<the input it's waiting for>\n")` unblocks it. ## Core tool inventory Grouped index of the tools an agent reaches for most often. Not exhaustive — the MCP exposes additional config / diagnostics / feedback tools beyond this list. Detailed parameters and return shapes for every tool are in the MCP's own tool descriptions. - **Process / shell:** `start_process`, `interact_with_process`, `read_process_output`, `list_processes`, `list_sessions`, `kill_process`, `force_terminate` - **Files (read/write):** `read_file`, `read_multiple_files`, `write_file`, `edit_block`, `write_pdf` - **Filesystem:** `list_directory`, `get_file_info`, `move_file`, `create_directory` - **Search:** `start_search`, `get_more_search_results`, `list_searches`, `stop_search` - **Diagnostics / config:** `get_recent_tool_calls`, `get_config` ## Conventions **Prefer absolute paths.** Relative paths may fail depending on the working directory, and tilde paths (`~/...`) may not expand in all contexts. Absolute paths are the most reliable; pass them whenever you can. **Allowed-directory scope.** File operations only work inside the user's configured `allowedDirectories`. Expect `[DENIED]` markers in `list_directory` output and rejections from `read_file` / `write_file` when the path is out of scope. Surface the rejected path to the user — don't retry. **When running on macOS:** default shell is zsh. Use `python3` not `python`. Some GNU tools have prefixed names (`gsed` for GNU sed). `brew` is the typical package manager. `open` opens files / apps from the terminal, `mdfind` is the fastest path to exact-filename search via Spotlight. Detect the host platform via `get_config` (or by inspecting `process.platform` / `uname` from a shell) before assuming any of the above — Windows and Linux hosts behave differently. **Pagination.** Long outputs (file reads, process output, search results) all support `offset` and `length`. Negative offsets read from the end (tail mode). Use these instead of dumping huge results into context. - skills/knowledge-base/SKILL.md (8791 bytes)
--- name: knowledge-base version: 0.1.0 audience: agent description: >- Create and maintain a Markdown knowledge base that any AI agent can read, search, and update. Use when the user wants to start a knowledge base, add or update notes, organize docs/notes for an agent or LLM to consume, build an index of notes, or run a cleanup/maintenance pass on an existing MD knowledge base. Triggers include "knowledge base", "KB", "notes for the agent", "index of notes", "second brain", "docs for AI context", "add a note", "update the KB". --- # Knowledge Base (Markdown, agent-readable) A knowledge base (KB) here is a folder of Markdown files designed so **any** AI agent can navigate it without a vector database: the agent reads one index file, picks the relevant notes by their descriptions, and opens only those. Keep the whole KB readable and the index lean — the index is what gets loaded into context, so it must be high-signal. Apply the rules below when creating a new KB, adding/editing notes, or doing a maintenance pass. When the user's request is ambiguous (new KB vs. add note vs. cleanup), ask which one before acting. ## Core principles (the "why") 1. **Index-first navigation.** The index is a map, not a container. An agent reads `INDEX.md`, selects notes by their one-line descriptions, then opens only those files. No note is "in" the KB unless it's registered in the index. 2. **Atomicity.** One topic per note. If a title needs an "and", it's probably two notes. Atomic notes are easier to find, link, and reuse. 3. **Stable IDs.** Every note has a permanent ID that never changes and is never reused, so links survive renames and moves. 4. **Linked with reason.** When two notes connect, state *why* (prerequisite, supports, contrasts, see-also). Connections carry as much value as the notes. 5. **Lean instructions.** Keep `INDEX.md` instructions short and high-signal — it competes for the agent's context budget. Bodies load on demand. 6. **Structured for retrieval.** Clear H1 title and H2/H3 sections so an agent can grab the relevant slice of a note, not the whole thing. ## Folder structure (nested by topic) ``` knowledge-base/ INDEX.md # entry point: instructions + full note registry topics/ <topic>/ _topic.md # topic map: what this topic covers + its notes <slug>.md # one atomic note assets/ # images / attachments referenced by notes ``` - Topic folders are short, lowercase nouns (`auth`, `billing`, `deploys`). - `_topic.md` is the topic-level map of content (MOC): a short intro plus links to every note in that topic. It is a convenience view; `INDEX.md` remains the source of truth. ## Naming rules - Lowercase **kebab-case**, predictable and greppable: `topics/auth/session-tokens.md`. - No spaces, no uppercase, no dates in filenames (dates live in frontmatter). - The filename slug should match the note's `id` slug portion. ## Required frontmatter (every note) ```yaml --- id: 20260618-session-tokens # ID scheme: YYYYMMDD-slug. Stable. Never reuse or change. title: Session tokens # human title, also the note's H1 tags: [auth, security] # only tags from the controlled list in INDEX.md created: 2026-06-18 updated: 2026-06-18 related: [20260618-auth-flow] # IDs of linked notes summary: One scannable sentence describing what this note covers. --- ``` - `id`: `YYYYMMDD-slug`. Sortable, readable, stable. Different-titled same-day notes differ by slug; if two same-day notes would collide on the same slug, append `-2`, `-3`, … (check the `INDEX.md` registry before assigning). Once assigned, the id is permanent. - `summary`: this exact sentence is what goes in the index registry — write it to help an agent decide whether to open the note. - `updated`: bump it whenever the body changes. ## Note body shape ```markdown # Session tokens > Summary: One sentence (mirrors frontmatter summary). ## Context Why this note exists / when it applies. ## Details The actual content, in short H2/H3 sections. ## Related - [Auth flow](auth-flow.md) — prerequisite: tokens are issued during the auth flow. - [Rate limiting](../api/rate-limiting.md) — see-also: tokens carry the rate-limit key. ``` - Use **relative links** between notes and annotate the relationship in a phrase. - Every link target should also appear in the note's `related` frontmatter. ## INDEX.md (the single source of truth) `INDEX.md` has two parts: operating instructions for agents, and the registry. ```markdown # Knowledge Base — Index ## How to use this KB (for agents) 1. Read this index first. Pick notes by their descriptions; open only those. 2. To answer a question, prefer opening 1–3 specific notes over scanning everything. 3. Cite the note `id` when you use information from it. ## How to update this KB (for agents) - New idea → create a new note (atomic). Same idea changed → edit the note in place and bump `updated`. - Any create / rename / delete MUST update this registry and the topic's `_topic.md` in the same change. - Use only tags from the controlled vocabulary below; add a new tag here before using it. ## Controlled tags `auth`, `security`, `billing`, `api`, `ops` <!-- extend deliberately --> ## Registry ### auth - `20260618-auth-flow` — **Authentication flow** — `topics/auth/auth-flow.md` — How a user session is established end to end. - `20260618-session-tokens` — **Session tokens** — `topics/auth/session-tokens.md` — Token format, lifetime, and rotation. ### billing - `20260618-invoicing` — **Invoicing** — `topics/billing/invoicing.md` — How invoices are generated and sent. ``` Registry line format: `` `id` — **Title** — `path` — one-line description.`` ## _topic.md (topic map) ```markdown # Auth Notes covering authentication, sessions, and access control. - [Authentication flow](auth-flow.md) — how a session is established. - [Session tokens](session-tokens.md) — token format, lifetime, rotation. ``` ## Workflows ### Create a new KB 1. `create_directory` for the folder structure above. 2. `write_file` `INDEX.md` with the instructions block, an empty controlled-tag list, and an empty registry. 3. Add the first topic folder + `_topic.md`, then the first note (each via `write_file`). 4. Register the note in `INDEX.md` and link it from `_topic.md` — `edit_block` both so you touch only the changed lines. ### Add a note 1. Pick or create the topic folder (`list_directory` to see what's there). 2. `write_file` the note (kebab-case slug) with full frontmatter and the body shape. 3. Add cross-links (and mirror them in `related`). 4. Register it in `INDEX.md` and link it in `_topic.md` with `edit_block` — same change. ### Update a note - Same idea, new information → `edit_block` the note in place, bump `updated`, and `edit_block` the registry line if the scope changed. - Genuinely new idea → `write_file` a new atomic note instead of expanding this one. ### Maintenance pass (run on demand) Use `start_search` (ripgrep) for text scans and `get_file_info` / `list_directory` for existence checks — together they make this tractable at scale: - **Orphans** (no *inbound* links — outbound doesn't matter): `start_search` the KB for the note's `id` and filename slug, then discount the self-matches that always exist — the note's own file, `INDEX.md`, and its `_topic.md`. Anything left is a genuine inbound reference; nothing left = orphan, so link it from a relevant note/MOC or archive it. - **Broken links / drift**: don't infer resolution from a text hit — a string existing doesn't mean the file does. Confirm each registry path and `related:` target exists with `get_file_info` (or `list_directory` per topic), and that every file on disk is registered. Use a text compare only for the titles/summaries-out-of-sync half. - **Non-atomic notes**: notes that grew to cover multiple topics → split them. - **Duplicates**: near-identical notes → merge, keep one `id`, redirect links. - **Tag sprawl**: read the controlled list from `INDEX.md`, then `start_search` the frontmatter `tags:` lines and flag any tag not on the list → reconcile. Pull candidates in bulk with `read_multiple_files`, apply fixes with `edit_block`, and report what changed. ## Checklist before finishing any KB edit - [ ] Every new/changed note has complete, valid frontmatter. - [ ] `id` is unique and unchanged; filename slug matches the id slug. - [ ] All links resolve and are mirrored in `related`. - [ ] `INDEX.md` registry and the topic `_topic.md` reflect the change. - [ ] Tags are from the controlled vocabulary. - [ ] `updated` bumped on every changed note. - skills/obsidian-vault/SKILL.md (8950 bytes)
--- name: obsidian-vault version: 0.1.0 audience: agent description: >- Organize Obsidian vaults with MOCs, wikilinks, frontmatter/properties, dashboards, orphan-note checks, and cleanup workflows. Use ONLY when the user explicitly refers to Obsidian — by naming "Obsidian", an Obsidian "vault", or an Obsidian-specific feature such as wikilinks ("[[ ]]"), the Dataview or Bases plugins, or Obsidian Properties. Within that Obsidian context it covers creating Maps of Content, adding/fixing wikilinks, finding orphan notes, normalizing YAML frontmatter, generating Dataview/Bases dashboards, organizing folders, deduplicating or renaming notes, and preparing the vault for AI use. Do NOT use this skill for generic note-taking, Markdown, or knowledge-base requests that don't mention Obsidian. --- # Obsidian Vault Assistant Help the user organize and maintain an Obsidian vault: build navigation with MOCs and wikilinks, normalize metadata, generate dashboards, find and fix orphans, organize folders, deduplicate/rename, and prepare the vault for AI use. Obsidian-specific facts that shape every rule here: - Links are **wikilinks** resolved by **filename**, not path: `[[Note title]]`. Renaming a note auto-updates links inside Obsidian, but moving files outside Obsidian breaks them — always rename via Obsidian when possible. - Metadata is **Properties** (YAML frontmatter) at the top of a note. - Dashboards come from **Dataview** (query language, read-only, flexible) or **Bases** (native, editable tables, fast on big vaults, properties-only). Before acting, confirm the vault's root folder and whether the user has the Dataview plugin installed (Bases is built in since Obsidian 1.9). When a request is ambiguous (organize vs. clean up vs. dashboard), ask which task. ## Wikilinks - Basic: `[[Three laws of motion]]` — resolves by filename, no extension/path. - Display text (pipe): `[[atomic-habits|James Clear — Atomic Habits]]`. - Heading link: `[[Note#Section]]`. Block link: `[[Note#^block-id]]`. - Embed/transclude: `![[Note]]`, `![[Note#Section]]`, `![[image.png]]`. - Aliases: add an `aliases` property so the note resolves under other names. - Avoid `# | ^ : %` and `[ ]` in filenames — they have special meaning in links. - Prefer wikilinks for internal navigation; use standard Markdown links only if the vault is also published to a tool that can't parse wikilinks. When adding links, also surface **unlinked mentions**: if a note's title appears as plain text in other notes, convert those to wikilinks. ## Maps of Content (MOCs) A MOC is a note that links the related notes on a topic — the vault's navigation layer (more flexible than folders or tags, and needs no institutional knowledge). Conventions: - Name MOCs clearly and tag them: `tags: [moc]` (or a `type: moc` property) so every MOC is itself discoverable. - Keep a top-level **Home / Index MOC** that links to all topic MOCs. - A MOC holds a short intro plus grouped wikilinks; it can be hand-curated or auto-generated with a Dataview/Bases query (see Dashboards). MOC template: ```markdown --- type: moc tags: [moc] updated: 2026-06-18 --- # Auth — Map of Content Notes on authentication, sessions, and access control. ## Core - [[auth-flow]] - [[session-tokens]] ## Related MOCs - [[security-moc]] ``` ## Frontmatter / Properties Add a consistent property block to every note. Recommended baseline: ```yaml --- title: Session tokens aliases: [tokens, session token] tags: [auth, security] type: note # note | moc | dashboard | template | person | project created: 2026-06-18 updated: 2026-06-18 status: evergreen # seedling | growing | evergreen related: ["[[auth-flow]]"] --- ``` Rules: - Use a **controlled tag vocabulary** — decide tags up front and reuse them; nested tags (`auth/tokens`) are fine. Don't let tags sprawl. - `tags` use no `#` in frontmatter. Dates in ISO `YYYY-MM-DD`. - Keep property **names and types consistent across the vault** — Bases and Dataview both depend on this. When normalizing, pick one name per concept (e.g. `created`, not `created`/`date`/`Created`) and migrate the rest. ## Dashboards Pick the engine based on the user's setup: **Bases** (native, editable, fast — best for operational boards): - Create a `.base` file or a `base` code block; it builds table/board views from properties. Each cell edits the underlying note's frontmatter. - Use for task lists, reading lists, project pipelines, anything point-and-click. **Dataview** (plugin, read-only, most flexible — best for reports/auto-MOCs): ```dataview TABLE status, updated, tags FROM #auth WHERE type = "note" SORT updated DESC ``` Auto-MOC of everything in a topic: ```dataview LIST FROM #auth WHERE type != "moc" SORT file.name ASC ``` Recently updated: ```dataview TABLE updated FROM "" WHERE updated >= date(today) - dur(7 days) SORT updated DESC ``` Note: large vaults can lag with heavy Dataview queries — prefer Bases there. ## Orphan notes & link hygiene An orphan is a note with no inbound or outbound links. To find and fix: 1. **From Desktop Commander** (no app needed, scales to big vaults): `start_search` the vault for `[[ ]]` links to each note's title — zero hits means no inbound links (an *unlinked* note); to confirm a true orphan (no inbound **and** no outbound), also scan the note's own body for `[[...]]`. The same searches surface **unlinked mentions** (the title as plain text, not wrapped in `[[ ]]`) and **broken links** (a `[[target]]` whose file is missing). 2. **Graph view** (Cmd/Ctrl+G): orphans float as isolated dots at the edges. 3. **Dataview** query for notes with no links: ```dataview LIST WHERE length(file.inlinks) = 0 AND length(file.outlinks) = 0 ``` 4. For each orphan: link it from a relevant MOC/note (`edit_block` to insert the wikilink), tag it `#needs-link` for a batch pass, or archive if obsolete. 5. Convert unlinked mentions into real wikilinks and fix broken links with `edit_block`; resolve the rest from Obsidian's right sidebar. ## Folder organization - Folders are for coarse buckets; **MOCs + tags do the real organizing**. Don't over-nest folders. - A workable layout: ``` 00-inbox/ # unsorted captures 10-notes/ # atomic notes 20-mocs/ # maps of content 30-projects/ 90-assets/ # images/attachments 99-archive/ templates/ ``` - Set the attachment folder in Settings so embeds land in `90-assets/`. - **Moves/renames must happen inside Obsidian** so wikilinks update automatically — do **not** use `move_file` for these, it breaks every `[[link]]`. From Desktop Commander, only edit *content* (`edit_block` / `write_file`); leave moving and renaming to the user in the app. ## Deduplicate & rename - **Duplicates**: `start_search` titles/aliases to find near-identical notes; merge into one, keep the most-linked filename, copy unique content with `edit_block`, then `start_search` for inbound `[[links]]` to the discarded note and repoint them before deleting it. - **Renames**: do them inside Obsidian (Rename note / `F2`) so backlinks update — not via `move_file`. Keep an `aliases` entry for the old name if it was widely referenced. - Standardize filenames: pick one convention (kebab-case or Title Case) and apply it consistently; avoid the special characters listed above. ## Prepare the vault for AI use - Ensure **consistent frontmatter** (same property names/types) so an agent can filter and reason over metadata. - Maintain a **Home/Index MOC** as the single entry point an agent reads first. - Write a one-line `summary`/`description` property per note for quick scanning. - Reduce orphans and broken links so the link graph is a reliable map. - Keep notes **atomic** (one idea each) — easier for an agent to retrieve and cite. - Consider exporting wikilinks to standard Markdown links if the AI tool can't parse `[[ ]]`. ## Workflows - **Build navigation**: `write_file` topic MOCs → `edit_block` notes to link them in → refresh the Home MOC → convert unlinked mentions. - **Normalize metadata**: `read_multiple_files` to audit properties → pick canonical names → `edit_block` each note → add missing baseline properties. - **Cleanup pass**: `start_search` for orphans, broken links, and unlinked mentions → dedupe → report what changed (renames stay in Obsidian). - **Dashboard**: confirm Dataview vs. Bases → `write_file` the view from properties/tags. ## Checklist before finishing - [ ] New/changed notes have consistent frontmatter (canonical property names). - [ ] Renames/moves done inside Obsidian; no links broken. - [ ] New notes linked from at least one MOC or note (no new orphans). - [ ] Tags drawn from the controlled vocabulary. - [ ] Dashboards reference properties/tags that actually exist. - [ ] `updated` bumped on changed notes. - skills/terminal/SKILL.md (10761 bytes)
--- name: terminal version: 0.1.0 audience: agent description: >- Use Desktop Commander for terminal and command-line work, especially anything that needs a shell whose state persists across turns: Python/Node REPLs, database shells, dev servers and other long-running processes, SSH into remote machines, and Windows PowerShell. Also handles everyday terminal tasks — navigating folders, choosing the right command for the user's shell (PowerShell, cmd, bash, zsh), running Docker/curl/cloud-CLI commands, inspecting processes and ports, and saving recurring workflows as scripts — even when the user doesn't say "Desktop Commander" or "terminal." Reach for it on pasted errors like "command not found", "permission denied", "EADDRINUSE", "address already in use", "npm ERR!", "ModuleNotFoundError", or "ENOENT", and on intents like "what's using port 3000", "kill that process", "ssh into my server", or "why won't my dev server start". Works on Windows, macOS, and Linux. Never run destructive commands without explicit confirmation. --- # Terminal Command Assistant Be a calm, safe, cross-platform terminal copilot. The user may be an expert or may be opening a terminal for the first time — read their cues and match them. Explain what a command does in plain language, run it through Desktop Commander, read the real output, and explain the result. The user's machine is the source of truth; never assume the OS, shell, or installed tools — detect them. ## 1. Detect the environment first (do this before suggesting commands) Different OSes and shells need different commands. Before recommending or running anything non-trivial, call **`get_config`** (Desktop Commander) and read `systemInfo`: - `platformName` / `isWindows` / `isMacOS` / `isLinux` — which OS. - `defaultShell` and `uiHints.availableShells` — which shell to target. - `pythonInfo`, `nodeInfo` — whether Python/Node exist and their versions. - `blockedCommands` — commands Desktop Commander refuses to run (see §7). - `allowedDirectories` — `[]` means full access; otherwise commands/paths are scoped to those directories. This one cheap call prevents the most common mistake: handing a macOS user a PowerShell command, or assuming `python3` exists when it doesn't. Cache what you learn for the rest of the session; re-check only if something seems off. ## 2. Choosing the right command for the shell Pick syntax by the detected shell, not by habit. Common equivalents: | Task | bash / zsh (macOS, Linux) | PowerShell (Windows) | cmd (Windows) | |---|---|---|---| | List files | `ls -la` | `Get-ChildItem` / `ls` | `dir` | | Current dir | `pwd` | `Get-Location` / `pwd` | `cd` | | Find file | `find . -name "*.log"` | `Get-ChildItem -Recurse -Filter *.log` | `dir /s *.log` | | Search text | `grep -r "TODO" .` | `Get-ChildItem -Recurse \| Select-String TODO` | `findstr /s TODO *` | | Env var | `echo $HOME` | `$env:USERPROFILE` | `echo %USERPROFILE%` | | Set env (session) | `export KEY=val` | `$env:KEY="val"` | `set KEY=val` | | Delete file | `rm file` | `Remove-Item file` | `del file` | | Copy | `cp a b` | `Copy-Item a b` | `copy a b` | | Path separator | `/` | `\` (or `/`) | `\` | Notes that bite people: Windows paths use `\` and often need quoting when they contain spaces; PowerShell and bash quote/escape differently; `~` expands in bash/zsh but not in cmd. When in doubt, prefer the cross-platform tool the user already has (e.g. `python`, `node`, `git`) over shell-specific syntax. ## 3. Running commands with Desktop Commander **Always use absolute paths.** Relative paths depend on a working directory that isn't carried between calls, so they fail unpredictably. - **One-shot commands** → `start_process` with the command and a timeout. It returns output and a PID. If output is truncated or the process is still running, call `read_process_output` with the PID for more. - **Long-running / interactive sessions** (REPLs, SSH, DB shells, `npm create`, anything that prompts) → `start_process` to launch, then `interact_with_process(pid, "...")` to send input and `read_process_output` to read responses. End with `force_terminate` if it won't exit on its own. - Navigation is just inspection: use `list_directory` and `get_file_info` rather than relying on a persistent `cd`. If you must `cd`, do it inside the same command (`cd /abs/path && some-command`). ### Interactive REPL pattern (the workhorse) This keeps state across calls and is the right way to drive Python, Node, a database shell, or SSH: ``` start_process("python3 -i") # or "node -i", "ssh user@host", "psql ..." interact_with_process(pid, "import pandas as pd") interact_with_process(pid, "df = pd.read_csv('/abs/path/data.csv')") interact_with_process(pid, "print(df.describe())") read_process_output(pid) # pull more output if needed ``` ## 4. Running specific CLIs - **Python**: prefer `python3 -i` as an interactive session for multi-step work; for a quick one-off use `python3 /abs/script.py`. Check `pythonInfo.command` from §1 (`python` vs `python3`). - **Node**: `node -i` for an interactive session, `node /abs/script.js` for a one-off. `npm`/`pnpm`/`yarn` installs can be slow — give a generous timeout and read remaining output rather than assuming failure. - **Docker**: `docker ps`, `docker logs <id>`, `docker compose up -d`. Long builds/runs: launch then poll with `read_process_output`. Treat `docker system prune`, `docker rm`, `docker volume rm` as destructive (§7). - **SSH**: launch with `start_process("ssh user@host")`, then drive it with `interact_with_process`. Remote destructive commands deserve the same confirmation rules as local ones. - **curl / HTTP**: fine for inspection (`curl -i https://...`). Be careful with anything that pipes a downloaded script straight into a shell (`curl ... | sh`) — that's untrusted code execution; show it and confirm first. - **Cloud CLIs** (`aws`, `gcloud`, `az`): read-only commands (`describe`, `list`, `get`) are safe to run; anything that creates, deletes, scales, or changes IAM is high-impact — preview the exact command and confirm. Never echo secrets or credentials into the terminal output. ## 5. Inspecting processes and ports - **Processes**: `list_processes` (Desktop Commander) for a structured view, or `ps aux` (Unix) / `Get-Process` (PowerShell). Stop one with `kill_process` by PID (`force_terminate` ends a session you started). - **What's using a port**: - macOS/Linux: `lsof -i :3000` or `lsof -nP -iTCP -sTCP:LISTEN` - Linux: `ss -ltnp` - Windows PowerShell: `Get-NetTCPConnection -LocalPort 3000` - Windows cmd: `netstat -ano | findstr :3000` (then map the PID) - When killing a process, confirm the PID belongs to what the user thinks it does — show the process line before terminating it. ## 6. Explaining errors in plain English When a command fails, don't just retry blindly: 1. Read the **actual** error text from the process output — the real cause is usually in the last few lines, not the first. 2. Name the cause in one plain sentence (e.g. "the port's already taken", "that package isn't installed", "permission denied because the file's owned by root"). 3. Give the concrete fix command for *their* shell, and explain what it does. 4. If the fix is risky or guesswork, say so and offer the safe diagnostic first. Common ones worth recognizing fast: `command not found` / `not recognized` (not installed or not on PATH), `EADDRINUSE` (port in use — see §5), `permission denied` / `EACCES` (ownership/permissions, not always fixable with elevation), `ENOENT` (path doesn't exist — check absolute path), `npm ERR!` blocks (read the resolved error line), non-zero exit codes (report the code). ## 7. Safety: destructive commands and chaining Desktop Commander already refuses a built-in `blockedCommands` list (things like `sudo`, `mkfs`, `format`, `dd`, `fdisk`, `shutdown`, `reboot`, `diskpart`, `reg`, `net`). Read the live list from `get_config`; don't assume it. Beyond that list, treat these as **destructive — never run without the user's explicit confirmation**, even if they'd technically succeed: - Recursive/forced deletes: `rm -rf`, `Remove-Item -Recurse -Force`, `del /s`, `rd /s`. - Overwriting or moving over existing files; wildcard deletes. - Disk/format/partition operations. - `git reset --hard`, `git clean -fd`, `git push --force` (history/data loss). - Database drops/truncates: `DROP`, `TRUNCATE`, `DELETE` without a `WHERE`. - `chmod -R` / `chown -R` on broad paths, `killall`, mass process kills. - Cloud deletes/scaling/IAM changes; `docker ... prune`/`rm`/volume removal. - Anything piping remote content into a shell (`curl ... | sh`). For these: show the exact command, explain in one line what it will irreversibly do, and wait for a clear "yes". Prefer a dry run or a read-only check first (e.g. `ls` the glob before `rm` it, `--dry-run` where the tool supports it). **Chaining safely**: `&&` runs the next only if the previous succeeded; `;` runs regardless; `||` runs only on failure. PowerShell historically uses `;` to sequence (it supports `&&`/`||` in v7+, but not all hosts). Keep chains short. If any step in a chain is destructive, don't chain it — run the safe steps, confirm, then run the risky one alone so a failure can't cascade. ## 8. Turning repeated workflows into scripts When the user runs the same sequence repeatedly (or asks to "save this"), offer to capture it as a script instead of retyping: - Unix → a `.sh` file with `#!/usr/bin/env bash` (or `zsh`), `set -euo pipefail` for safety, comments explaining each step; make it executable (`chmod +x`). - Windows → a `.ps1` (PowerShell) script with comment-based help at the top. - Write the file with `write_file` to an absolute path the user chooses, echo it back, and explain how to run it. Parameterize the bits that change (paths, names) rather than hard-coding. - If the workflow needs to run on both Windows and Unix, either keep the logic in a cross-platform tool (a small Python/Node script) or provide both a `.sh` and a `.ps1`. Don't pretend one shell script runs everywhere. Keep scripts small and readable — the goal is something the user can open, trust, and edit later, not a black box. ## Operating etiquette - Preview risky commands before running; run read-only inspection first. - Use absolute paths; respect `allowedDirectories`. - Never print secrets, tokens, or passwords into output; redact if they appear. - Match the user's level: explain jargon when they seem new, stay terse when they're fluent. - After a failed command, diagnose from the real output before retrying. - smithery.yaml (435 bytes)
# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml startCommand: type: stdio configSchema: # JSON Schema defining the configuration options for the MCP. type: object properties: {} commandFunction: # A JS function that produces the CLI command based on the given config to start the MCP on stdio. |- (config) => ({ command: 'node', args: ['dist/index.js'] }) exampleConfig: {} - test-listener-bug.js (6400 bytes)
#!/usr/bin/env node /** * Test to verify that read_process_output doesn't break future calls * by removing TerminalManager's listeners with removeAllListeners * * Expected behavior: * 1. Start Node.js REPL * 2. Send command with interact_with_process * 3. Call read_process_output - should work * 4. Send another command with interact_with_process * 5. Call read_process_output again - should STILL work (this would fail with removeAllListeners bug) */ import { spawn } from 'child_process'; import path from 'path'; import { fileURLToPath } from 'url'; const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); async function runTest() { console.log('🧪 Testing listener cleanup bug...\n'); // Start the MCP server const serverPath = path.join(__dirname, 'dist', 'index.js'); const server = spawn('node', [serverPath, '--no-onboarding'], { stdio: ['pipe', 'pipe', 'pipe'] }); let responseBuffer = ''; let requestId = 1; server.stdout.on('data', (data) => { responseBuffer += data.toString(); }); server.stderr.on('data', (data) => { console.error('Server stderr:', data.toString()); }); function sendRequest(method, params) { const request = { jsonrpc: '2.0', id: requestId++, method, params }; server.stdin.write(JSON.stringify(request) + '\n'); } function waitForResponse(expectedId, timeout = 5000) { return new Promise((resolve, reject) => { const startTime = Date.now(); const checkInterval = setInterval(() => { const lines = responseBuffer.split('\n'); for (const line of lines) { if (!line.trim()) continue; try { const response = JSON.parse(line); if (response.id === expectedId) { clearInterval(checkInterval); responseBuffer = responseBuffer.replace(line, ''); resolve(response); return; } } catch (e) { // Not valid JSON yet, keep waiting } } if (Date.now() - startTime > timeout) { clearInterval(checkInterval); reject(new Error(`Timeout waiting for response ${expectedId}`)); } }, 50); }); } async function callTool(name, args) { const id = requestId; sendRequest('tools/call', { name, arguments: args }); const response = await waitForResponse(id); if (response.error) { throw new Error(`Tool error: ${JSON.stringify(response.error)}`); } return response.result; } try { // Initialize sendRequest('initialize', { protocolVersion: '2024-11-05', capabilities: {} }); await waitForResponse(requestId - 1); console.log('✅ Server initialized\n'); // Step 1: Start Node.js REPL console.log('📝 Step 1: Starting Node.js REPL...'); const startResult = await callTool('start_process', { command: 'node -i', timeout_ms: 5000 }); const pidMatch = startResult.content[0].text.match(/PID (\d+)/); const pid = parseInt(pidMatch[1]); console.log(`✅ Started process with PID: ${pid}\n`); // Step 2: Send first command console.log('📝 Step 2: Sending first command (1 + 1)...'); const interact1 = await callTool('interact_with_process', { pid, input: '1 + 1', timeout_ms: 3000 }); console.log('✅ First interact succeeded'); console.log(` Output snippet: ${interact1.content[0].text.substring(0, 50)}...\n`); // Step 3: First read_process_output (this might break listeners with removeAllListeners) console.log('📝 Step 3: First read_process_output...'); const read1 = await callTool('read_process_output', { pid, timeout_ms: 1000 }); console.log('✅ First read_process_output succeeded'); console.log(` Output: ${read1.content[0].text.substring(0, 50)}...\n`); // Step 4: Send second command WITHOUT waiting (so output stays in buffer) console.log('📝 Step 4: Sending second command (2 + 2) WITHOUT waiting...'); const interact2 = await callTool('interact_with_process', { pid, input: '2 + 2', timeout_ms: 3000, wait_for_prompt: false // Don't wait, let read_process_output get it }); console.log('✅ Second interact sent (not waiting for output)\n'); // Wait a bit for output to arrive await new Promise(resolve => setTimeout(resolve, 500)); // Step 5: Second read_process_output (THIS WILL FAIL if listeners were removed) console.log('📝 Step 5: Second read_process_output (critical test)...'); const read2 = await callTool('read_process_output', { pid, timeout_ms: 2000 }); const outputText = read2.content[0].text; const hasOutput = !outputText.includes('No new output') && !outputText.includes('Timeout reached'); if (!hasOutput) { console.error('❌ BUG DETECTED: Second read_process_output returned no output!'); console.error(' This means TerminalManager listeners were removed by removeAllListeners'); console.error(` Full output: ${outputText}`); process.exit(1); } // Validate output contains expected result from "2 + 2" if (!outputText.includes('4')) { console.error('❌ BUG DETECTED: Second read_process_output has corrupt output!'); console.error(` Expected result "4" from "2 + 2" but got: ${outputText}`); process.exit(1); } // Validate output contains REPL prompt (proves detection is working) if (!outputText.includes('>')) { console.error('❌ BUG DETECTED: Second read_process_output missing REPL prompt!'); console.error(` Expected ">" prompt but got: ${outputText}`); process.exit(1); } console.log('✅ Second read_process_output succeeded!'); console.log(` ✓ Contains expected result: "4"`); console.log(` ✓ Contains REPL prompt: ">"`); console.log(` Full output: ${outputText.substring(0, 100)}...\n`); // Cleanup await callTool('force_terminate', { pid }); console.log('✅ Process terminated\n'); console.log('🎉 All tests passed! Listener cleanup is working correctly.'); process.exit(0); } catch (error) { console.error('❌ Test failed:', error.message); process.exit(1); } finally { server.kill(); } } runTest(); - track-installation.js (12560 bytes)
#!/usr/bin/env node /** * Installation Source Tracking Script * Runs during npm install to detect how Desktop Commander was installed * * Debug logging can be enabled with: * - DEBUG=desktop-commander npm install * - DEBUG=* npm install * - NODE_ENV=development npm install * - DC_DEBUG=true npm install */ import { randomUUID } from 'crypto'; import * as https from 'https'; import { platform } from 'os'; import path from 'path'; import { fileURLToPath } from 'url'; // Get current file directory const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); // Debug logging utility - configurable via environment variables const DEBUG_ENABLED = process.env.DEBUG === 'desktop-commander' || process.env.DEBUG === '*' || process.env.NODE_ENV === 'development' || process.env.DC_DEBUG === 'true'; const debug = (...args) => { if (DEBUG_ENABLED) { console.log('[Desktop Commander Debug]', ...args); } }; const log = (...args) => { // Always show important messages, but prefix differently for debug vs production if (DEBUG_ENABLED) { console.log('[Desktop Commander]', ...args); } }; /** * Get the client ID from the Desktop Commander config file, or generate a new one */ async function getClientId() { try { const { homedir } = await import('os'); const { join } = await import('path'); const fs = await import('fs'); const USER_HOME = homedir(); const CONFIG_DIR = join(USER_HOME, '.claude-server-commander'); const CONFIG_FILE = join(CONFIG_DIR, 'config.json'); // Try to read existing config if (fs.existsSync(CONFIG_FILE)) { const configData = fs.readFileSync(CONFIG_FILE, 'utf8'); const config = JSON.parse(configData); if (config.clientId) { debug(`Using existing clientId from config: ${config.clientId.substring(0, 8)}...`); return config.clientId; } } debug('No existing clientId found, generating new one'); // Fallback to random UUID if config doesn't exist or lacks clientId return randomUUID(); } catch (error) { debug(`Error reading config file: ${error.message}, using random UUID`); // If anything goes wrong, fall back to random UUID return randomUUID(); } } // Telemetry proxy configuration (same as setup script) const TELEMETRY_PROXY_URL = 'https://telemetry.desktopcommander.app/mp/collect'; const TELEMETRY_PROXY_FALLBACK_URL = 'https://dc-telemetry-proxy-83847352264.europe-west1.run.app/mp/collect'; /** * Detect installation source from environment and process context */ async function detectInstallationSource() { // Check npm environment variables for clues const npmConfigUserAgent = process.env.npm_config_user_agent || ''; const npmExecpath = process.env.npm_execpath || ''; const npmCommand = process.env.npm_command || ''; const npmLifecycleEvent = process.env.npm_lifecycle_event || ''; // Check process arguments and parent commands const processArgs = process.argv.join(' '); const processTitle = process.title || ''; debug('Installation source detection...'); debug(`npm_config_user_agent: ${npmConfigUserAgent}`); debug(`npm_execpath: ${npmExecpath}`); debug(`npm_command: ${npmCommand}`); debug(`npm_lifecycle_event: ${npmLifecycleEvent}`); debug(`process.argv: ${processArgs}`); debug(`process.title: ${processTitle}`); // Try to get parent process information let parentProcessInfo = null; try { const { execSync } = await import('child_process'); const ppid = process.ppid; if (ppid && process.platform !== 'win32') { // Get parent process command line on Unix systems const parentCmd = execSync(`ps -p ${ppid} -o command=`, { encoding: 'utf8' }).trim(); parentProcessInfo = parentCmd; debug(`parent process: ${parentCmd}`); } } catch (error) { debug(`Could not get parent process info: ${error.message}`); } // Smithery detection - look for smithery in the process chain const smitheryIndicators = [ npmConfigUserAgent.includes('smithery'), npmExecpath.includes('smithery'), processArgs.includes('smithery'), processArgs.includes('@smithery/cli'), processTitle.includes('smithery'), parentProcessInfo && parentProcessInfo.includes('smithery'), parentProcessInfo && parentProcessInfo.includes('@smithery/cli') ]; if (smitheryIndicators.some(indicator => indicator)) { return { source: 'smithery', details: { detection_method: 'process_chain', user_agent: npmConfigUserAgent, exec_path: npmExecpath, command: npmCommand, parent_process: parentProcessInfo || 'unknown', process_args: processArgs } }; } // Direct NPX usage if (npmCommand === 'exec' || processArgs.includes('npx')) { return { source: 'npx-direct', details: { user_agent: npmConfigUserAgent, command: npmCommand, lifecycle_event: npmLifecycleEvent } }; } // Regular npm install if (npmCommand === 'install' || npmLifecycleEvent === 'postinstall') { return { source: 'npm-install', details: { user_agent: npmConfigUserAgent, command: npmCommand, lifecycle_event: npmLifecycleEvent } }; } // GitHub Codespaces if (process.env.CODESPACES) { return { source: 'github-codespaces', details: { codespace: process.env.CODESPACE_NAME || 'unknown' } }; } // VS Code if (process.env.VSCODE_PID || process.env.TERM_PROGRAM === 'vscode') { return { source: 'vscode', details: { term_program: process.env.TERM_PROGRAM, vscode_pid: process.env.VSCODE_PID } }; } // GitPod if (process.env.GITPOD_WORKSPACE_ID) { return { source: 'gitpod', details: { workspace_id: process.env.GITPOD_WORKSPACE_ID.substring(0, 8) + '...' // Truncate for privacy } }; } // CI/CD environments if (process.env.CI) { if (process.env.GITHUB_ACTIONS) { return { source: 'github-actions', details: { repository: process.env.GITHUB_REPOSITORY, workflow: process.env.GITHUB_WORKFLOW } }; } if (process.env.GITLAB_CI) { return { source: 'gitlab-ci', details: { project: process.env.CI_PROJECT_NAME } }; } if (process.env.JENKINS_URL) { return { source: 'jenkins', details: { job: process.env.JOB_NAME } }; } return { source: 'ci-cd-other', details: { ci_env: 'unknown' } }; } // Docker detection if (process.env.DOCKER_CONTAINER) { return { source: 'docker', details: { container_id: process.env.HOSTNAME ? process.env.HOSTNAME.substring(0, 8) + '...' : 'unknown' } }; } // Check for .dockerenv file (need to use fs import) try { const fs = await import('fs'); if (fs.existsSync('/.dockerenv')) { return { source: 'docker', details: { container_id: process.env.HOSTNAME ? process.env.HOSTNAME.substring(0, 8) + '...' : 'unknown' } }; } } catch (error) { // Ignore fs errors } // Default fallback return { source: 'unknown', details: { user_agent: npmConfigUserAgent || 'none', command: npmCommand || 'none', lifecycle: npmLifecycleEvent || 'none' } }; } /** * Send installation tracking to telemetry proxy */ async function trackInstallation(installationData) { try { const uniqueUserId = await getClientId(); log("user id", uniqueUserId) // Prepare telemetry payload const payload = { client_id: uniqueUserId, non_personalized_ads: false, timestamp_micros: Date.now() * 1000, events: [{ name: 'package_installed', params: { timestamp: new Date().toISOString(), platform: platform(), installation_source: installationData.source, installation_details: JSON.stringify(installationData.details), package_name: '@wonderwhy-er/desktop-commander', install_method: 'npm-lifecycle', node_version: process.version, npm_version: process.env.npm_version || 'unknown' } }] }; const postData = JSON.stringify(payload); const options = { method: 'POST', headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(postData) } }; const sent = await postTelemetryPayload(TELEMETRY_PROXY_URL, postData, options); if (!sent) { await postTelemetryPayload(TELEMETRY_PROXY_FALLBACK_URL, postData, options); } log(`Installation tracked: ${installationData.source}`); } catch (error) { debug(`Failed to track installation: ${error.message}`); // Don't fail the installation process } } // TODO(dedup): postTelemetryPayload is copy-pasted across setup/uninstall/track // scripts + a variant in src/utils/capture.ts. Consolidate into one shared module. // TODO(timeout): per-endpoint timeout here is 5s, but ensureTrackingCompleted caps // the whole flow at 6s — so if the primary times out, the fallback gets ~1s and // almost never completes. Lower per-endpoint timeout (capture.ts uses 3s) or raise // the overall budget so the fallback is actually usable. async function postTelemetryPayload(endpoint, postData, options) { return await new Promise((resolve) => { let settled = false; let timeoutId; const finish = (result) => { if (settled) return; settled = true; clearTimeout(timeoutId); resolve(result); }; const req = https.request(endpoint, options); timeoutId = setTimeout(() => { req.destroy(); finish(false); }, 5000); req.on('error', (error) => { debug(`Telemetry error: ${error.message}`); finish(false); }); req.on('response', (res) => { res.on('data', () => {}); res.on('error', (error) => { debug(`Telemetry response error: ${error.message}`); finish(false); }); res.on('end', () => { finish(res.statusCode >= 200 && res.statusCode < 300); }); res.on('close', () => { finish(false); }); }); req.write(postData); req.end(); }); } /** * Main execution */ async function main() { try { log('Package installation detected'); const installationData = await detectInstallationSource(); log(`Installation source: ${installationData.source}`); await trackInstallation(installationData); } catch (error) { debug(`Installation tracking error: ${error.message}`); // Don't fail the installation } } // Only run if this script is executed directly (not imported) if (import.meta.url === `file://${process.argv[1]}`) { main(); } export { detectInstallationSource, trackInstallation }; - tsconfig.coverage.json (91 bytes)
{ "extends": "./tsconfig.json", "compilerOptions": { "inlineSourceMap": true } } - tsconfig.json (481 bytes)
{ "compilerOptions": { "target": "ES2020", "module": "Node16", "moduleResolution": "node16", "esModuleInterop": true, "strict": true, "outDir": "./dist", "rootDir": "./src", "declaration": true, "skipLibCheck": true, "diagnostics": true, "extendedDiagnostics": true, "listEmittedFiles": true, "types": ["node"] }, "include": [ "src/**/*.ts", "src/**/*.d.ts" ], "exclude": [ "node_modules", "dist" ] } - uninstall-claude-server.js (27393 bytes)
import { homedir, platform } from 'os'; import fs from 'fs/promises'; import path from 'path'; import { join } from 'path'; import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } from 'fs'; import { fileURLToPath } from 'url'; import { dirname } from 'path'; import { exec } from "node:child_process"; import { version as nodeVersion } from 'process'; import * as https from 'https'; import { randomUUID } from 'crypto'; // Telemetry proxy configuration const TELEMETRY_PROXY_URL = 'https://telemetry.desktopcommander.app/mp/collect'; const TELEMETRY_PROXY_FALLBACK_URL = 'https://dc-telemetry-proxy-83847352264.europe-west1.run.app/mp/collect'; // Read clientId and telemetry settings from existing config let uniqueUserId = 'unknown'; let telemetryEnabled = false; // Default to disabled for privacy async function getConfigSettings() { try { const USER_HOME = homedir(); const CONFIG_DIR = path.join(USER_HOME, '.claude-server-commander'); const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json'); if (existsSync(CONFIG_FILE)) { const configData = readFileSync(CONFIG_FILE, 'utf8'); const config = JSON.parse(configData); return { clientId: config.clientId || randomUUID(), telemetryEnabled: config.telemetryEnabled === true // Explicit check for true }; } // Fallback: generate new ID and default telemetry to false if config doesn't exist return { clientId: `unknown-${Date.now()}-${Math.random().toString(36).substring(2, 15)}`, telemetryEnabled: false }; } catch (error) { // Final fallback return { clientId: `random-${Date.now()}-${Math.random().toString(36).substring(2, 15)}`, telemetryEnabled: false }; } } // Uninstall tracking let uninstallSteps = []; let uninstallStartTime = Date.now(); // Fix for Windows ESM path resolution const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename); // Setup logging const LOG_FILE = join(__dirname, 'setup.log'); function logToFile(message, isError = false) { const timestamp = new Date().toISOString(); const logMessage = `${timestamp} - ${isError ? 'ERROR: ' : ''}${message}\n`; try { appendFileSync(LOG_FILE, logMessage); const jsonOutput = { type: isError ? 'error' : 'info', timestamp, message }; process.stdout.write(`${message}\n`); } catch (err) { process.stderr.write(`${JSON.stringify({ type: 'error', timestamp: new Date().toISOString(), message: `Failed to write to log file: ${err.message}` })}\n`); } } // Function to get npm version async function getNpmVersion() { try { return new Promise((resolve, reject) => { exec('npm --version', (error, stdout, stderr) => { if (error) { resolve('unknown'); return; } resolve(stdout.trim()); }); }); } catch (error) { return 'unknown'; } } // Get Desktop Commander version const getVersion = async () => { try { if (process.env.npm_package_version) { return process.env.npm_package_version; } const versionPath = join(__dirname, 'version.js'); if (existsSync(versionPath)) { const { VERSION } = await import(versionPath); return VERSION; } const packageJsonPath = join(__dirname, 'package.json'); if (existsSync(packageJsonPath)) { const packageJsonContent = readFileSync(packageJsonPath, 'utf8'); const packageJson = JSON.parse(packageJsonContent); if (packageJson.version) { return packageJson.version; } } return 'unknown'; } catch (error) { return 'unknown'; } }; // Function to detect shell environment function detectShell() { if (process.platform === 'win32') { if (process.env.TERM_PROGRAM === 'vscode') return 'vscode-terminal'; if (process.env.WT_SESSION) return 'windows-terminal'; if (process.env.SHELL?.includes('bash')) return 'git-bash'; if (process.env.TERM?.includes('xterm')) return 'xterm-on-windows'; if (process.env.ComSpec?.toLowerCase().includes('powershell')) return 'powershell'; if (process.env.PROMPT) return 'cmd'; if (process.env.WSL_DISTRO_NAME || process.env.WSLENV) { return `wsl-${process.env.WSL_DISTRO_NAME || 'unknown'}`; } return 'windows-unknown'; } if (process.env.SHELL) { const shellPath = process.env.SHELL.toLowerCase(); if (shellPath.includes('bash')) return 'bash'; if (shellPath.includes('zsh')) return 'zsh'; if (shellPath.includes('fish')) return 'fish'; if (shellPath.includes('ksh')) return 'ksh'; if (shellPath.includes('csh')) return 'csh'; if (shellPath.includes('dash')) return 'dash'; return `other-unix-${shellPath.split('/').pop()}`; } if (process.env.TERM_PROGRAM) { return process.env.TERM_PROGRAM.toLowerCase(); } return 'unknown-shell'; } // Function to determine execution context function getExecutionContext() { const isNpx = process.env.npm_lifecycle_event === 'npx' || process.env.npm_execpath?.includes('npx') || process.env._?.includes('npx') || import.meta.url.includes('node_modules'); const isGlobal = process.env.npm_config_global === 'true' || process.argv[1]?.includes('node_modules/.bin'); const isNpmScript = !!process.env.npm_lifecycle_script; return { runMethod: isNpx ? 'npx' : (isGlobal ? 'global' : (isNpmScript ? 'npm_script' : 'direct')), isCI: !!process.env.CI || !!process.env.GITHUB_ACTIONS || !!process.env.TRAVIS || !!process.env.CIRCLECI, shell: detectShell() }; } // Enhanced tracking properties let npmVersionCache = null; async function getTrackingProperties(additionalProps = {}) { const propertiesStep = addUninstallStep('get_tracking_properties'); try { if (npmVersionCache === null) { npmVersionCache = await getNpmVersion(); } const context = getExecutionContext(); const version = await getVersion(); updateUninstallStep(propertiesStep, 'completed'); return { platform: platform(), node_version: nodeVersion, npm_version: npmVersionCache, execution_context: context.runMethod, is_ci: context.isCI, shell: context.shell, app_version: version, engagement_time_msec: "100", ...additionalProps }; } catch (error) { updateUninstallStep(propertiesStep, 'failed', error); return { platform: platform(), node_version: nodeVersion, error: error.message, ...additionalProps }; } } // Enhanced tracking function with retries async function trackEvent(eventName, additionalProps = {}) { const trackingStep = addUninstallStep(`track_event_${eventName}`); // Check if telemetry is disabled if (!telemetryEnabled) { updateUninstallStep(trackingStep, 'skipped_telemetry_disabled'); return true; // Return success since this is expected behavior } const maxRetries = 2; let attempt = 0; let lastError = null; while (attempt <= maxRetries) { try { attempt++; const eventProperties = await getTrackingProperties(additionalProps); const payload = { client_id: uniqueUserId, non_personalized_ads: false, timestamp_micros: Date.now() * 1000, events: [{ name: eventName, params: eventProperties }] }; const postData = JSON.stringify(payload); const options = { method: 'POST', headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(postData) } }; const result = await postTelemetryPayload(postData, options); if (!result.success) throw new Error('Telemetry proxy request failed'); updateUninstallStep(trackingStep, 'completed'); return result; } catch (error) { lastError = error; if (attempt <= maxRetries) { await new Promise(resolve => setTimeout(resolve, 1000 * attempt)); } } } updateUninstallStep(trackingStep, 'failed', lastError); return false; } async function postTelemetryPayload(postData, options) { for (const endpoint of [TELEMETRY_PROXY_URL, TELEMETRY_PROXY_FALLBACK_URL]) { const result = await new Promise((resolve) => { let settled = false; let timeoutId; const finish = (result) => { if (settled) return; settled = true; clearTimeout(timeoutId); resolve(result); }; const req = https.request(endpoint, options); timeoutId = setTimeout(() => { req.destroy(); finish({ success: false, data: '' }); }, 5000); req.on('error', () => { finish({ success: false, data: '' }); }); req.on('response', (res) => { let data = ''; res.on('data', (chunk) => { data += chunk; }); res.on('error', () => { finish({ success: false, data: '' }); }); res.on('end', () => { finish({ success: res.statusCode >= 200 && res.statusCode < 300, data }); }); res.on('close', () => { finish({ success: false, data: '' }); }); }); req.write(postData); req.end(); }); if (result.success) return result; } return { success: false, data: '' }; } // Ensure tracking completes before process exits async function ensureTrackingCompleted(eventName, additionalProps = {}, timeoutMs = 6000) { return new Promise(async (resolve) => { const timeoutId = setTimeout(() => { resolve(false); }, timeoutMs); try { await trackEvent(eventName, additionalProps); clearTimeout(timeoutId); resolve(true); } catch (error) { clearTimeout(timeoutId); resolve(false); } }); } // Setup global error handlers (will be initialized after config is loaded) let errorHandlersInitialized = false; function initializeErrorHandlers() { if (errorHandlersInitialized) return; process.on('uncaughtException', async (error) => { if (telemetryEnabled) { await trackEvent('uninstall_uncaught_exception', { error: error.message }); } setTimeout(() => { process.exit(1); }, 1000); }); process.on('unhandledRejection', async (reason, promise) => { if (telemetryEnabled) { await trackEvent('uninstall_unhandled_rejection', { error: String(reason) }); } setTimeout(() => { process.exit(1); }, 1000); }); errorHandlersInitialized = true; } // Track when the process is about to exit let isExiting = false; process.on('exit', () => { if (!isExiting) { isExiting = true; } }); // Determine OS and set appropriate config path const os = platform(); const isWindows = os === 'win32'; let claudeConfigPath; switch (os) { case 'win32': claudeConfigPath = join(process.env.APPDATA, 'Claude', 'claude_desktop_config.json'); break; case 'darwin': claudeConfigPath = join(homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'); break; case 'linux': claudeConfigPath = join(homedir(), '.config', 'Claude', 'claude_desktop_config.json'); break; default: claudeConfigPath = join(homedir(), '.claude_desktop_config.json'); } // Step tracking functions function addUninstallStep(step, status = 'started', error = null) { const timestamp = Date.now(); uninstallSteps.push({ step, status, timestamp, timeFromStart: timestamp - uninstallStartTime, error: error ? error.message || String(error) : null }); return uninstallSteps.length - 1; } function updateUninstallStep(index, status, error = null) { if (uninstallSteps[index]) { const timestamp = Date.now(); uninstallSteps[index].status = status; uninstallSteps[index].completionTime = timestamp; uninstallSteps[index].timeFromStart = timestamp - uninstallStartTime; if (error) { uninstallSteps[index].error = error.message || String(error); } } } async function execAsync(command) { const execStep = addUninstallStep(`exec_${command.substring(0, 20)}...`); return new Promise((resolve, reject) => { const actualCommand = isWindows ? `cmd.exe /c ${command}` : command; exec(actualCommand, { timeout: 10000 }, (error, stdout, stderr) => { if (error) { updateUninstallStep(execStep, 'failed', error); reject(error); return; } updateUninstallStep(execStep, 'completed'); resolve({ stdout, stderr }); }); }); } // Backup configuration before removal async function createConfigBackup(configPath) { const backupStep = addUninstallStep('create_config_backup'); try { const timestamp = new Date().toISOString().replace(/[:.]/g, '-'); const backupPath = `${configPath}.backup.${timestamp}`; if (existsSync(configPath)) { const configData = readFileSync(configPath, 'utf8'); writeFileSync(backupPath, configData, 'utf8'); updateUninstallStep(backupStep, 'completed'); logToFile(`Configuration backup created: ${backupPath}`); await trackEvent('uninstall_backup_created'); return backupPath; } else { updateUninstallStep(backupStep, 'no_config_file'); return null; } } catch (error) { updateUninstallStep(backupStep, 'failed', error); await track