Release Notes — v0.2.41

🔒 Security: directory traversal via symlink bypass — fixed

A symlink inside an allowed directory pointing to a restricted location could bypass isPathAllowed() when the target file didn't yet exist — fs.realpath() failed with ENOENT and the allowlist check fell back to the unresolved path. validatePath() now resolves the deepest existing ancestor and reconstructs the real path before checking the allowlist, so a symlink at /projects/evil → /etc/ can no longer trick a write of /projects/evil/crontab into landing at /etc/crontab.

Reported and patched by @sorlen008 — thank you. Fixed in #398 — closes #219 (open ~7 months).

🛟 Excel: read_file now accepts SheetName!A1:B2 range syntax

edit_block accepted range: "Sheet1!E5" but read_file rejected it as Invalid cell range — and the post-success help line in every read_file output literally showed {range: "Sheet1!E5"} as the example. Agents copying that example hit unrecoverable retry loops. The two parsers are now unified; quoted Excel-native forms ('My Sheet'!A1:B2), full-column ranges (A:B), and combined Sheet!Cells all work for both tools.

Fixed in #469. Thanks @dasein108.

🩹 File preview survives page refresh

The "Preview unavailable after page refresh" placeholder is gone for cases where preview content was actually available — read_file now embeds returned content in structuredContent so the widget can rehydrate, and unsupported file types fall back to raw escaped content instead of an error card. #472

⏱️ Startup hang on Windows / high-latency networks — fixed

On Windows + Node 24 / undici 7.x, AbortController.abort() doesn't always interrupt an in-progress TCP connect, so the feature flags fetch could hang for ~30s on every cold start (OS-level TCP timeout). Wrapped the fetch in Promise.race with a hard 3s timeout, added a 5s safety bound to waitForFreshFlags(), and added 6 regression tests including a broken-AbortController simulation.

Fixed in #467 — closes #465.

📁 list_directory: [NOT_FOUND] vs [DENIED]

Listing a nonexistent path used to report [DENIED], implying a permission problem. ENOENT now produces [NOT_FOUND] with a clear message and a ❓ icon in the directory preview UI. EPERM/EACCES/ETIMEDOUT still surface as [DENIED]. #468

✨ Gemini CLI extension skills

Extends the Gemini CLI extension support shipped in v0.2.40 with a proper skill page — guidance for agents on when to reach for Desktop Commander (persistent shells, long-running jobs, large local files, structured documents, SSH sessions, process management) with worked example workflows. #466

🧩 Claude Code plugin

Desktop Commander is now submittable as a Claude Code plugin — plugin metadata, README, and a skill guide so Claude knows when to use it for terminal work, file access, document handling, process management, and SSH. #457

🖱️ Cursor plugin metadata + one-click install

Cursor marketplace metadata, a branded install button, and a deeplink that opens Cursor with the MCP server config prefilled. #456, #462, #464

Contributors

@sorlen008, @dasein108, @edgarsskore, @wonderwhy-er — and thanks to the user in Australia who filed #465 with detailed logs that made the Windows timeout fix straightforward.

Release Notes - v0.2.40

🛟 Hotfix: Markdown auto-save no longer corrupts your files

If you've been on v0.2.39, please upgrade. The markdown preview pane was silently rewriting .md files on disk through a Tiptap round-trip — collapsing GFM tables, rewriting Obsidian wikilinks ([[Note]] → [Note](http://Note)), corrupting YAML frontmatter, and adding spurious \[, \], \~, \_ escapes. Fixed in #445 — closes #437 and #440.

✨ Gemini CLI extension support

Desktop Commander can now be installed as a Gemini CLI extension.

🧹 Tool history log: better truncation (#441)

The tool history file could grow unbounded and occasionally crash the server. Now hard-capped at 5 MiB with a rolling trim down to 4 MiB keeping the most recent entries.

Contributors

@serg33v, @edgarsskore, @wonderwhy-er — and thanks to @dvdakile and @55nchz for the detailed reproductions on #437 / #440.

Release Notes - v0.2.39

📝 Markdown Editor (New!)

WYSIWYG markdown editing right in the preview pane — what you see is what you get. Edit your .md files, then copy-paste the formatted output straight into Slack, Medium, Notion, email, or anywhere else that accepts rich text. No more "does this work here or do I need to retype it as bold?"

• Live edit/preview with raw and rendered views, plus fullscreen mode
• Table of contents navigation, link search/insert, autosave, undo/revert
• Conflict handling — when a file changes on disk (e.g. another agent edits it mid-session), get a clear choice between the disk version and your edits, or a partial-success merge when only some of your edits collide
• Copy paste styled results to other rich text editors, Slack, Medium, Notion

📂 Directory Browser (New!) (#392)

read_file on a directory path now opens a browsable tree view in the preview pane instead of throwing EISDIR:

• Expand/collapse folders, drill into subdirectories, go back up to parent
• Open files directly from the tree, or open the whole folder in your system file browser
• Agents also get an immediate directory listing + hint to use list_directory next time, so no wasted round-trip

⚙️ Configuration Improvements

• Boolean config values accept string inputs ("true"/"false") and are normalized correctly — telemetry opt-out works reliably even when stored as a string
• Sanitized error messages (#367)

🔒 Security Improvements

• ReDoS protection for Excel and DOCX search — searchExcelFiles and searchDocxFiles now detect catastrophic-backtracking regexes (e.g. (a+)+$) and fall back to literal string matching instead of hanging the event loop (#400)

🔧 Other Changes

• Better error messages for cloud storage permission failures (EPERM / EACCES / ETIMEDOUT) (#408)
• Added windowsHide to prevent console window flashing on Windows (#401)
• Improved test coverage for conditional-tools, including stale client name fix (#434)

Contributors
@edgarsskore, @wonderwhy-er, @phuryn, @sorlen008

Release Notes - v0.2.38

🖥️ Settings Panel (New!)
A visual config editor right inside Claude Desktop — no more editing JSON files or remembering tool call syntax.

View and edit all Desktop Commander settings through a clean UI
Toggle telemetry, adjust file limits, manage blocked commands and allowed directories
Dark mode support with host-agnostic theming
Works across different MCP hosts

🔒 Security Improvements

Config key allowlist — set_config_value now only accepts known configuration keys, preventing prompt injection from tampering with internal state like clientId or A/B test flags (#353)
Fail-closed command validation — if blocklist validation errors (corrupt config, read failure), commands are now denied instead of silently allowed (#352)
Sandbox hardening — removed allow-same-origin from preview iframe sandbox to prevent embedded content from escaping (#355)

🔧 Other Changes

Added token counter script for measuring tool definition token usage — 41 tools, 13,735 tokens, 6.9% of 200K context (#358)
Fixed "Inialization" typo in remote-channel.ts (#351)

Contributors
@edgarsskore, @pmcdade

v0.2.37

📄 DOCX Support (New!)

Full Microsoft Word document support through the existing read_file, write_file, edit_block, and start_search tools — no new tools needed.

• Read DOCX — default mode shows a text-bearing outline (paragraphs, tables, images, headers/footers) with body indices for navigation. Set offset=1 to get raw pretty-printed XML for precise editing.
• Edit DOCX — surgical find/replace on the underlying XML via edit_block, with automatic header/footer search fallback. For bulk operations (e.g. translation), use Python with the zipfile module.
• Create DOCX — write_file with a .docx extension converts markdown headings to proper Word heading styles with Calibri defaults and standard page margins.
• Search DOCX — content search extracts text from document.xml, headers, and footers, running in parallel alongside ripgrep.

🔧 Fixes & Improvements

• Onboarding config override — local onboarding_injection config setting is now respected, so users can disable it with set_config_value (#348, fixes #303)
• Remote error handling — enhanced error handling and logging across remote channel operations; removed unused subscribe method (#332)
• Options parsing fix — resolved false positive in options parsing (#345, fixes #343)
• Agent discovery — added plugin.yaml for agent registry and plugin discovery (#346)
• AgentAudit badge — added verified badge to docs (#340)

Contributors

@edgarsskore, @lucamorettibuilds, @mattalxndr, @dasein108, @chorghemaruti64-creator, @ecap0-ai

v0.2.36

🖼️ File Preview UI (New!)

When Claude reads a file, you now get a visual preview widget right in Claude Desktop — no more staring at raw text dumps in the chat.

• Rendered markdown with clean, Medium-inspired typography
• Image preview — PNG, JPEG, GIF, WebP files render inline
• "Load more lines" — expand before/after to see more of the file without re-reading
• Breadcrumb path with an "Open in folder" button to jump straight to the file in Finder/Explorer
• Works on macOS and Windows (hardened Windows path handling to prevent injection)

🔧 Fixes & Improvements

• Build fix: blocking-offline-update.js now correctly copied to dist during build (#329)
• Tilde expansion: Restricted ~ expansion to current user only for security

Contributors

@edgarsskore

Screenshots

# Release Notes - v0.2.33

Security

• Fix command blocklist bypass via absolute paths and command substitution — thanks @dcpagotto
• validatePath now blocks symlink traversal to prevent arbitrary read/write — thanks @zjyhhhher
• Added symlink security tests for validatePath

Protocol

• Use SDK protocol version negotiation instead of a hardcoded version (found and suggested by @abcnow)

Features

• Add v2 feature flags with weighted A/B test variants
• Fix welcome page A/B test to include local-agent-mode clients

Release Tooling

• Release script now handles existing tags gracefully

Release Notes - v0.2.25 to v0.2.30

🚀 Major New Feature

Remote MCP - Use Desktop Commander from ChatGPT & Claude Web! (#311)

You can now use Desktop Commander directly from ChatGPT, Claude web, and other AI services - no Claude Desktop app required!

How it works:

1. Run the Remote Device on your computer: npx @wonderwhy-er/desktop-commander@latest remote
2. Authenticate in your browser (secure OAuth 2.0 flow with PKCE)
3. Connect your AI at mcp.desktopcommander.app
4. Your AI can now execute commands, edit files, and manage your system!

Security:

• You're always in control - stop anytime with Ctrl+C
• Secure OAuth 2.0 authentication with PKCE
• Commands run locally under your user permissions
• Device only active when you explicitly start it
• Encrypted communication

Features:

• Works with ChatGPT Connectors, Claude Connectors, and other LLM interfaces
• Session persistence option (--persist-session) for automatic reconnection
• macOS sleep prevention to keep connection alive
• Graceful shutdown with proper cleanup

Get Started: https://mcp.desktopcommander.app

---

🐛 Bug Fixes

PDF Generation Fixed (#306)

Desktop Commander now reliably creates PDFs for all users:

• Auto-detects system Chrome/Chromium on Windows, macOS, and Linux
• If no browser is found, automatically downloads Chrome on first PDF creation
• Pre-emptively checks/downloads Chrome on server start for faster first use
• Fixes ~250 errors/week for MCPB users who didn't have puppeteer cache

macOS Shell Environment Fix (#312)

• Defaults to zsh on macOS when SHELL environment variable is not set
• Fixes tools like gcloud, nvm, and brew-installed utilities that weren't loading properly when running inside Claude Desktop
• Ensures shell profiles (.zprofile) are properly sourced

Better Multi-Client Compatibility (#307)

• Fixed edit_block for clients that send empty strings for optional parameters
• Improves compatibility with ChatGPT/OpenAI and other clients that treat optional params as required

MCPB Bundle ESM Fix (#314)

• Added type: module to MCPB bundle package.json
• Fixes Node.js warnings about ESM module recompilation in bundled version

---

Compare: v0.2.24...v0.2.30

# Release Notes - v0.2.24

🚀 Major New Features

Full PDF Support (#283)

Desktop Commander now has comprehensive PDF capabilities - read, create, and modify PDF files directly.

Reading PDFs:

• Extract text content as markdown with page structure
• Extract embedded images from PDFs
• Page-based pagination (offset/length work as page numbers)
• Performance optimized for partial page reading

Creating PDFs:

• Convert markdown to PDF with write_pdf tool
• Supports headers, lists, code blocks, tables
• HTML/CSS styling and inline SVG supported
• Control page breaks with <div style="page-break-before: always;"></div>

Modifying PDFs:

• Delete specific pages by index
• Insert new pages from markdown or other PDFs
• Merge and split documents
• Editing existing page content is possible but results in loss of styling - not recommended at this stage

Safety: When modifying PDFs, Desktop Commander creates a new output file, leaving your original untouched in case you need to revert.

---

Full Excel/Spreadsheet Support (#282)

Complete Excel file handling with a new file handler architecture.

Reading Excel Files:

• Read .xlsx, .xls, .xlsm files - returns JSON 2D arrays
• Sheet selection by name or index
• Range queries (e.g., A1:D100)
• Offset/length pagination for large sheets
• get_file_info returns sheet metadata (names, row/column counts)

Creating Excel Files:

• Write spreadsheets from JSON 2D arrays
• Multi-sheet support with {SheetName: [[...]]}
• Automatic column width handling

Modifying Excel Files:

• Edit specific cell ranges with edit_block
• Update individual cells or ranges
• Preserve existing sheets while modifying

Searching Excel Files:

• Content search works inside Excel files
• Find data across sheets

Examples:

// Read specific sheet and range
read_file("data.xlsx", { sheet: "Sales", range: "A1:D100" })

// Edit cells
edit_block("data.xlsx", { range: "Sheet1!C1:C10", content: [["New"], ["Values"]] })

---

🔒 Privacy Policy Update (#287)

Based on user feedback, we've significantly updated our privacy policy to be more transparent and accurate.

Corrections Made:

• Fixed incorrect statements about UUIDs and personally identifiable information (PII)
• Clarified that client IDs are pseudonymous identifiers (cannot directly identify you, but allow usage pattern analysis)

New Transparency:

• Clear explanation of exactly what we collect and don't collect
• Explicit statement that we don't have access to IP addresses
• Added dedicated contact email: privacy@desktopcommander.app

Your Rights Section Added:

• How to exercise your privacy rights (disable telemetry)
• Why UUID-based data requests cannot be processed (privacy by design - we can't verify identity)
• Automatic 14-month data retention with auto-deletion
• If you uninstall and delete config, stored analytics cannot be linked back to you

Read the full policy: PRIVACY.md

---

🐛 Critical Bug Fixes

Fixed MCP Protocol Violation During Startup (#285)

The MCP protocol requires the client to send the first message. Desktop Commander was writing to stdout before the client's initialization request, breaking protocol handshake with clients like langchain-mcp-adapters.

What Was Broken:

• BrokenResourceError in langchain-mcp-adapters
• Server startup logs corrupting the MCP handshake
• Feature flag async operations logging after client started closing

What's Fixed:

• Transport created before config loading to capture all output
• Log messages buffered until client is initialized
• Feature flag operations no longer log during startup
• Clean process exit with .unref() on refresh intervals

---

Windows Build Compatibility (#286)

• Fixed ripgrep detection on Windows (uses where instead of which)
• Cross-platform postinstall script (no more || true)
• Setup script works in NODE_ENV=production environments

---

✨ Enhancements

Process Output Pagination (#290)

Terminal process outputs now support file-like pagination to prevent context overflow.

New Parameters:

• offset: Start line (0 for new output, positive for absolute, negative for tail)
• length: Max lines to read (respects fileReadLineLimit config)

Examples:

offset: 0, length: 100    → First 100 NEW lines since last read
offset: 500, length: 50   → Lines 500-549 (absolute position)
offset: -20               → Last 20 lines (tail)
offset: -50, length: 10   → 10 lines starting 50 from end

Also fixed bug where completed process output was missed when process finished between snapshot and poll.

---

Better Mount Detection (#289)

Improved detection of mounted filesystems for more reliable allowed directory validation.

---

📝 Other Changes

• Disabled Use Case Collection (#288) - Removed anonymous use case telemetry
• README Cleanup (#292) - Documentation improvements
• Updated MCPB Manifest - Extension metadata updates

---

Contributors

• @dasein (PDF support)
• @edgarsskore (Excel support)

Full Changelog: v0.2.23...v0.2.24

Release Notes - v0.2.22

🔥 Critical Windows Hotfix

Fixed Windows npx Installation Failures (#279) [CRITICAL]

This is a critical hotfix for Windows users experiencing installation and connection failures.

Desktop Commander now properly handles npx commands on Windows using the officially recommended cmd /c wrapper pattern. This resolves the widespread connection failures and crashes that occurred when Claude Desktop tried to start the server via npx on Windows.

What Was Broken:

• Windows users experienced "Cannot read properties of undefined (reading 'cmd')" errors
• Server failed to start when installed via npx on Windows
• Claude Desktop showed "Connection closed" or "Cannot connect to MCP server" errors

What's Fixed:

• Windows npx installations now use cmd /c npx wrapper instead of npx.cmd
• Debug mode inspector flag (--inspect-brk) moved to NODE_OPTIONS environment variable
• Follows Anthropic's official MCP server configuration guidelines for Windows

Impact: Windows users can now successfully install and run Desktop Commander via npx. If you experienced connection issues on Windows, please reinstall:

npx @wonderwhy-er/desktop-commander@latest setup

---

🐛 Additional Bug Fixes

Enhanced Ripgrep Stability (#275)

Improved search functionality reliability with better ripgrep binary management and crash prevention.

What Changed:

• Added verification script to validate ripgrep installation
• Implemented robust binary path resolution system
• Enhanced error handling and crash tracking for search operations
• Removed 283 lines of legacy code for better maintainability

---

✨ Enhancements

Streamlined Onboarding v2 (#278)

Simplified the new user onboarding experience from multiple steps to just 2 steps with 5 focused prompts, helping new users get started faster.

Release Process Improvements (#280)

Release script now tracks state and can resume from failed steps, making the release workflow more robust and recoverable.

---