yvgude--lean-ctx/docs/integrations/windows10-opencode-wsl-setup.md

Installing Lean-CTX on Windows 10 for OpenCode

A Guide for Bridging WSL Ubuntu and OpenCode

This guide outlines the process of installing Lean-CTX within a Windows Subsystem for Linux (WSL) environment and integrating it as an MCP server for OpenCode on Windows.

---

Phase 1: WSL Environment Setup

Because native Windows installation can be complex, we utilize WSL Ubuntu as the host environment for the Lean-ctx binary.

1. Install WSL Ubuntu via the Microsoft Store or PowerShell: wsl --install -d Ubuntu.
2. Install Lean-ctx by running the following command in your Ubuntu terminal:

   curl -fsSL https://leanctx.com/install.sh | sh
   

3. Configure the PATH to ensure the binary is globally accessible:

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   

4. Verify Installation:

   lean-ctx --version
   # Expected output: lean-ctx 3.4.7 (official, https://github.com)
   

---

Phase 2: Lean-ctx Configuration

Initialize the setup by running:

lean-ctx setup

Follow the interactive prompts to configure your environment. Note that while the tool sits in Ubuntu, it will effectively manage your Windows-based OpenCode context.

Recommended Settings

Feature	Setting	Description
Agent Output Optimization	lite or full	Reduces "fluff" and increases token density.
Tool Result Archive	Enabled	Archives large outputs to a "filing cabinet" to save context space.
Output Density	Terse	Removes terminal noise and redundant headers.

---

Phase 3: Diagnostics and Dashboard

1. Verify Health:

   lean-ctx doctor
   # Ensure output ends with: Summary: 11/11 checks passed
   

2. Initialize Agent Profile:

   lean-ctx init --agent opencode
   

3. Launch Dashboard: Keep your Ubuntu terminal open and run:

   lean-ctx dashboard
   

   You can now access the visual performance monitor at: http://127.0.0.1:3333

---

Phase 4: OpenCode MCP Integration (Windows)

Now, return to your Windows Command Prompt to bridge OpenCode to your WSL environment.

1. Add the MCP Server:

   opencode-cli mcp add
   

   Interactive Input:

   • Name: lean-ctx
   • Type: local
   • Command: wsl.exe (This acts as a placeholder for the next step).

2. Gather Environment Metadata: Run these commands to get the required values for your config:

   • Distro Name: wsl -l -v (Usually Ubuntu)
   • WSL Username: wsl whoami (Note: This is your Linux username, usually lowercase).

3. Edit opencode.json: Navigate to %USERPROFILE%\.config\opencode\opencode.json and locate the lean-ctx entry. Replace the "command": "wsl.exe" string with a structured array:

   "mcp": {
     "lean-ctx": {
       "type": "local",
       "command": [
         "wsl.exe", 
         "-d", "Ubuntu", 
         "-e", "/home/<Your_WSL_Username>/.local/bin/lean-ctx"
       ],
       "enabled": true
     }
   }
   

---

Phase 5: Verification

1. Launch OpenCode: The GUI should indicate that the MCP server is connected and enabled.
2. Test Tool Usage: Give your agent a high-load command to force an archive trigger:

   "Aggressively use ctx_archive for any file read exceeding 300 lines to maintain maximum context overhead."

3. Monitor Performance: Check the dashboard at http://127.0.0.1:3333 to see real-time tool calls and compression ratios.

---

Special thanks to Yves Gugger for developing Lean-CTX.