CMD Lite VS Code Extension — Gap Analysis & Implementation Guide

Note

This repository houses the unofficial, community-driven VS Code extension for Command Code (cmd), branded as CMD Lite. Below is a comprehensive Gap Analysis comparing the Official Command Code Extension vs. This Unofficial Extension (CMD Lite) under the lens of Rich Hickey's Simplicity principles.

---

📊 Feature Matrix: Unofficial vs. Official Extension

The unofficial extension is built as a decoupled, feature-rich wrapper that acts as a functional superset of the official plugin, exposing rich UI interactions while keeping state management clean.

Capability	Official Extension	Unofficial Extension (This Repo)	Architectural Status
IPC Context Server (UDS Socket)	✅	✅	Unified: Shares real-time workspace state over Unix Domain Sockets.
Active Editor Selection Sharing	✅	✅	Optimized: Shares active selection, debounced to prevent IPC lag.
Diagnostics / Error Sharing	✅	✅	Unified: Relays IDE diagnostics (errors, warnings, hints) to the CLI.
Git Context Relay	❌	✅	Extended: Shares branch name, HEAD commit hash, and list of modified files.
UDS Socket Authentication	❌	✅	Secured: Implements UUID token handshakes and process-isolated socket permissions (0o600).
Chat Participant (@cmd)	❌	✅	Feature: Native chat UI routing queries to cmd -p with cancellation.
Language Model Tools (6 Tools)	❌	✅	Feature: Exposes IDE capabilities (runPrint, getTaste, etc.) to Copilot/Agents.
Parallel Agent Orchestration	❌	✅	Feature: Coordinates concurrent cmd --headless tasks (impl, tests, docs).
Inline Diff Previews	❌	✅	Feature: Intercepts code modifications and presents them via vscode.diff() using a custom virtual provider to preserve syntax highlighting and file editability.
Interactive Webview Diffs	❌	✅	Feature: In-chat diff blocks with native Accept/Reject resolution buttons.
Rich Tool Visualization	❌	✅	Feature: Streams tool outputs (e.g., base64 screenshots) as inline images.
Context Drag-and-Drop	❌	✅	Feature: Drop context files onto the chat to automatically bridge to the CLI File System.
Multi-Agent Dashboard	❌	✅	Feature: Sidebar panel visualizing concurrent background agents in real-time.
Taste Sidebar TreeView	❌	✅	Feature: Employs FileSystemWatcher for reactive reload of .commandcode/taste/.
Status Bar Controller	❌	✅	Feature: Quick settings selector for active model, permission modes, and status.
MCP Config Generator	❌	✅	Feature: Generates mcp.json to provision external OS capabilities dynamically.
Externalized Session State	❌	✅	Feature: Decouples UI from state by hydrating from unstorage-mcp filesystem JSON.
Event-Driven Wakeups	❌	✅	Feature: Replaces polling with standard MCP webhook triggers for background tasks.
Session History Log	❌	✅	Feature: Reads active sessions and metadata straight from ~/.commandcode/projects/.
Reactive Configuration	❌	✅	Robust: Instantly updates CLI path validation and status bars on setting changes.
Test Coverage	❌	✅	Quality: Extensive Vitest coverage across CLI resolution, IPC, webview regression, loop workflows, and packaging behavior.
CLI Resolution	✅	✅	Unified: Prefers a precompiled cmd/command-code binary on PATH or an explicit cmd-lite.cliPath; local update artifacts must contain a native binary.

---

🧠 Rich Hickey Analysis: Simplicity vs. Easiness

In analyzing editor integrations (such as comparing Command Code with competitors like Kilo Code), we apply Rich Hickey’s principles of decomplecting state and prioritizing simplicity (untangling concerns) over easiness (immediate convenience that complects systems).

1. Decomplecting Editor & Agent State

• Accidental Complexity (The Fork/Heavy Extension Path): Deeply hooking into the editor's token stream or webviews to manage agent sessions (e.g. Cursor forks or Kilo Code's heavy client logic). This complects the editor lifecycle with the AI inference state.
• Essential Simplicity (Our Extension Wrapper Path): Treating the editor purely as a "dumb UI frontend" and a read-only context provider. All agent state, decision loops, and taste-1 learning reside exclusively inside the cmd CLI. The UDS socket separates these domains cleanly.

2. Composable Registries (Agent Autonomy)

Instead of hardcoding complex OS capabilities (like File System access or Git execution) into the IDE extension, we use the Model Context Protocol (MCP).

• Accidental Complexity: Writing custom scripts or wrappers in the extension layer to expose the OS to the agent.
• Essential Simplicity: The extension strictly provides an mcp.json configuration file, composing standard Official Reference MCP Servers (like @modelcontextprotocol/server-filesystem). The headless CLI agent uses npx -y to dynamically provision these capabilities at runtime, requiring zero maintenance from the IDE layer.

3. Concurrency (Parallel Agent Orchestration)

Running multiple agents concurrently (e.g., implementing, testing, and documenting at once) is high-utility but traditionally complects state.

• Simple Implementation: We treat the project's instructions and "taste" preferences as immutable values. Our parallel agent module spawns concurrent cmd --headless subprocesses. Each process operates independently without mutating live code, outputting proposal events that are merged or reviewed sequentially.

4. Event-Driven Wakeups & State Decomplecting

• Accidental Complexity: Polling for background task completion or trapping agent preferences (like permission modes) inside proprietary IDE data stores (like globalState).
• Essential Simplicity: We rely on standard MCP Registries. Agent state is managed externally via unstorage-mcp writing pure JSON, and background tasks notify the UI dynamically via an mcp-webhook server. The extension acts purely as a "Thin Glass" read-only UI layer.

5. Complexity vs. Utility Matrix

Capability	Utility	Technical Complexity	Architectural Type	Verdict
IPC Context Server	High	Medium	Essential	Adopted. Essential for feeding editor state without CLI polling.
UDS Token Handshake	High	Low	Security	Adopted. Ensures only the authenticated VS Code editor can connect to the UDS socket.
Parallel Orchestration	High	Medium	Concurrency	Adopted. Spawns concurrent subprocesses and aggregates results without locking the editor.
Virtual Diff Provider	High	Low	Essential	Adopted. Employs a custom TextDocumentContentProvider to retain syntax highlighting and file editability.
Inline Autocomplete (LSP)	Medium	High	Accidental	Rejected. Bypasses the unified taste-1 CLI loop and complects the LSP with the editor.

---

🛠️ Installation & Quick Start

1. Prerequisites (CLI Installation)

Since we do not bundle the proprietary binary, install the precompiled command-code CLI so cmd or command-code is available on your PATH, or set cmd-lite.cliPath to the binary path.

command-code --version
# or
cmd --version

Tip

If multiple package managers installed cmd, check which cmd and configure cmd-lite.cliPath to the intended precompiled binary. CMD Lite intentionally ignores stale local Node entrypoints such as dist/index.mjs.

2. Install the Extension VSIX

You can download the packaged extension from our GitHub Releases page. Install it directly via your terminal:

code --install-extension cmd-lite-0.5.7.vsix

---

💻 Developer Guide

If you are contributing to this extension:

# Install dependencies
pnpm install

# Run build compilation
pnpm run build

# Run lint checks
pnpm run lint

# Run unit tests
pnpm test

# Build packaged .vsix extension
pnpm run package

🚀 Publishing to Marketplaces

We support dual-registry publishing to the Visual Studio Marketplace and the Open VSX Registry.

Option A: Automated CI/CD (Recommended)

1. Configure your registry tokens in your GitHub Repository Secrets:
   • VSCE_PAT: Personal Access Token with Marketplace (Publish) scope.
   • OVSX_PAT: Open VSX registry Access Token.
2. Push a release tag matching your version:

   git tag v0.5.7
   git push origin v0.5.7

3. GitHub Actions will automatically validate, compile, package, and deploy the single VSIX artifact to both registries.

Option B: Local Direct Publish

You can use the Babashka publisher script locally to validate and deploy:

# 1. Run validation checks in dry-run mode (runs linter, tests, and mock packaging)
pnpm run publish --dry-run

# 2. Run real publishing (requires VSCE_PAT and/or OVSX_PAT environment variables)
export VSCE_PAT=your_azure_devops_pat
export OVSX_PAT=your_open_vsx_token
pnpm run publish

Key Configurations (settings.json)

• cmd-lite.cliPath: Custom path to your cmd executable (defaults to cmd).
• cmd-lite.defaultModel: Default model override (e.g. claude-opus-4.8).
• cmd-lite.defaultPermissionMode: Default permission mode (standard, plan, auto-accept).
• cmd-lite.showStatusBar: Toggle the status bar session indicator.
• cmd-lite.context.maxSelectionLength: Caps the text selection context shared over IPC.
• cmd-lite.allowShellTool: Enables direct shell execution tools for trusted workspaces only.

Bounded Agent Loops

Use Command Code: Run Bounded Agent Loop to repeat one agent task with a verification check. Each iteration asks the CLI to make one bounded improvement, run or satisfy the verification, and finish with LOOP_DONE or LOOP_CONTINUE. The loop stops on completion, cancellation, repeated failures, or the configured iteration limit.

Supporting commands and UI:

• Command Code: Stop Active Loop
• Command Code: Open Last Loop Report
• Command Code: Browse Loop Reports
• /loops slash command in the webview
• LOOPS action-bar panel with timeline and status

Loop reports are written to ~/.commandcode/loops/ as JSON files.

Agent Modes

Use Command Code: Pick Agent Mode to switch the default behavior for prompts and chat runs:

• code - implement and edit code
• plan - design before editing
• ask - answer without modifying files
• debug - troubleshoot and verify
• review - inspect risks, regressions, and missing tests

The current agent mode is reflected in the footer alongside the permission mode.

MCP Status

Use the MCP panel in the webview to inspect the currently configured MCP servers from the workspace mcp.json. The panel refreshes after Command Code: Generate MCP Config.

---

⌨️ TUI Visual Parity & Keyboard Shortcuts

CMD Lite features full parity with the cmd CLI TUI interface. You can perform operations mouse-free inside the webview using the following terminal shortcuts:

Shortcut	Action Description	Webview Impact
Shift+Tab	Cycle Permission Mode	Switches permission mode sequentially: standard → auto-accept → plan → standard.
Ctrl+T	Toggle Continuous Learning	Enables/disables the TASTE profiling state and logs feedback.
Ctrl+O	Toggle Expanded Outputs	Expands/collapses all thought and tool accordion blocks.
Alt+P (Option+P)	Switch Model	Triggers the VS Code model quick pick switcher list.
Escape (single)	Interrupt Execution	Instantly cancels the active CLI child process.
Escape (double)	Rewind Session	Rewinds the active session to the last git checkpoint.

We also render a live Hypothesizing Status Line (o Hypothesizing... esc to interrupt • <duration> • ⬇ <tokens count>) above the chat input box to provide real-time execution duration feedback.

---

⚖️ License

MIT License for the extension frontend. The cmd CLI is proprietary (© Command Code, Inc.).