How to Install and Uninstall ModLens as a Skill Plugin

ModLens installs as a self-contained skill folder that you copy into your AI harness's skills directory, making the modlens vision command available immediately without system-wide package managers.

ModLens is distributed through the liustack/modlens repository as a portable skill plugin compatible with Claude Code, Codex, Pi/OpenCode, and DeepSeek Harness. Because it runs as a skill rather than a global binary, you can install and uninstall it by simply moving folders in and out of the harness-specific skill directories.

Installation Prerequisites

Before installing ModLens, confirm that your AI harness supports the skill plugin protocol. The repository provides launchers for Unix and Windows environments that automatically detect available runtimes (the modlens binary, npx, or bunx) and forward commands to the CLI entry point in src/main.ts.

You will need:

• Git installed to clone the repository
• A supported harness: Claude Code, Codex, Pi/OpenCode, or DeepSeek Harness (dsh)
• Node.js (if using npx fallback) or the native modlens binary

Installing on Claude Code, Codex, and OpenCode

For harnesses that load skills from filesystem directories, installation follows a three-step pattern: locate the directory, copy the skill folder, and verify the launcher works.

Locate the Skill Directory

Each harness reads skills from a fixed location in your home directory:

• Claude Code: ~/.claude/skills/
• Codex: ~/.codex/skills/
• Pi / OpenCode: ~/.agents/skills/

Check which directory exists on your system, then create the skills subdirectory if it is missing.

Copy the Skill Folder

Clone the repository and copy the skills/modlens folder into your harness directory. The skill folder contains SKILL.md (metadata for the harness), launcher scripts (scripts/run.sh and scripts/run.ps1), and the references/ package with configuration documentation.

# Clone the repository (shallow clone for speed)

git clone --depth 1 https://github.com/liustack/modlens.git /tmp/modlens-src

# Create the target directory (example for Claude Code)

mkdir -p ~/.claude/skills

# Copy the skill folder contents

cp -R /tmp/modlens-src/skills/modlens/. ~/.claude/skills/modlens/

Verify the Installation

Confirm that SKILL.md and the launcher scripts are present, then run the health check:

# Verify files landed correctly

ls ~/.claude/skills/modlens/SKILL.md
ls ~/.claude/skills/modlens/scripts/run.sh

# Run the doctor command via the launcher

bash ~/.claude/skills/modlens/scripts/run.sh doctor

If the doctor reports a vision provider is ready, your harness will expose the modlens command on its next start.

Installing on DeepSeek Harness (dsh)

DeepSeek Harness uses a native plugin system rather than skill folders. Install ModLens directly via npm:

npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.25.0

Restart dsh after installation. The model selector will now display "(modlens vision)" entries, indicating the skill is active.

Configuring Your Vision Provider

After installation, select a provider and set your API key. The configuration persists in ~/.modlens/config.json across all harnesses:

# Set the provider (example: Gemini API)

bash ~/.claude/skills/modlens/scripts/run.sh config set provider gemini-api

# Set your API key

bash ~/.claude/skills/modlens/scripts/run.sh config set gemini-api.apiKey YOUR_KEY_HERE

Available providers are implemented in src/providers/ and include Gemini, OpenAI-compatible endpoints, Antigravity, Claude, Kimi, and Anthropic.

Uninstalling ModLens

Uninstalling is the inverse of installation: remove the skill folder from the harness directory.

For Claude Code, Codex, or OpenCode:

rm -rf ~/.claude/skills/modlens

# Or: rm -rf ~/.codex/skills/modlens

# Or: rm -rf ~/.agents/skills/modlens

For DeepSeek Harness:

npx @deepseek-ai/dsh plugin --profile web remove @liustack/modlens

Cleaning Up Configuration Files

The skill is self-contained, so removing the folder restores the harness to its original state. However, user-specific state in ~/.modlens/config.json persists. To completely erase all traces:

rm -f ~/.modlens/config.json

Summary

• ModLens installs as a skill folder copied into harness-specific directories (~/.claude/skills/, ~/.codex/skills/, or ~/.agents/skills/), while DeepSeek Harness uses npx for native plugin installation.
• The skill relies on SKILL.md for metadata and scripts/run.sh (or run.ps1) to dispatch commands to the modlens CLI.
• Because the skill forwards arguments to the binary rather than embedding runtime code, uninstallation requires only deleting the skill folder.
• Configuration stored in ~/.modlens/config.json survives uninstallation and can be manually removed if desired.

Frequently Asked Questions

Where does ModLens store configuration files?

ModLens stores all user-specific settings in ~/.modlens/config.json. This file contains API keys, provider preferences, and guard lists, and it is shared across all harnesses regardless of where the skill folder resides.

Can I use ModLens with multiple AI harnesses simultaneously?

Yes. Because the configuration lives in ~/.modlens/config.json and is independent of the skill folder, you can copy the skills/modlens directory into multiple harness skill directories (e.g., both ~/.claude/skills/ and ~/.codex/skills/) and they will read from the same configuration file.

What happens if I delete the skill folder but keep the config?

Deleting the skill folder removes the modlens CLI from the harness immediately, but ~/.modlens/config.json remains on disk. If you reinstall ModLens later, your previous API keys and provider settings will still be active.

How do I switch vision providers after installation?

Run the config command through the launcher to update the provider without reinstalling:

bash ~/.claude/skills/modlens/scripts/run.sh config set provider <provider-name>

Valid provider names correspond to the implementations in src/providers/ (e.g., gemini-api, openai-compatible, claude).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}