Superpowers Lab

repository·main·Indexed 19 days ago

https://github.com/obra/superpowers-lab

A collection of experimental skills for Claude Code designed to extend its capabilities. It includes tools for semantic code duplication detection (finding-duplicate-functions), on-demand MCP tool invocation (mcp-cli), interactive terminal automation via tmux, and headless Windows 11 VM management using Docker.

Tokens
11K
Snippets
27
Records
37
Agent score
64%

What's inside superpowers-lab

  1. Overview of Superpowers Lab skills

    main

    Superpowers Lab provides experimental skills for Claude Code Superpowers. These skills extend Claude Code's capabilities through several specialized techniques:

    • finding-duplicate-functions: Detects semantic code duplication (functions with the same intent but different implementations) using a two-phase approach with LLM-powered intent clustering.
    • mcp-cli: Allows on-demand discovery and invocation of MCP (Model Context Protocol) tools, resources, and prompts via a CLI without permanent configuration.
    • using-tmux-for-interactive-commands: Enables Claude Code to automate interactive CLI tools (like vim, git rebase -i, or REPLs) by creating detached tmux sessions and programmatically sending keystrokes.
    • windows-vm: Manages headless Windows 11 VMs running in Docker (via dockur/windows) with KVM acceleration, providing SSH access for testing or running Claude Code in a Windows environment.
  2. Manage a headless Windows 11 VM via Docker

    main

    This skill allows you to create, manage, and connect to a headless Windows 11 VM running in Docker using the dockur/windows image with KVM acceleration. The VM is accessible exclusively via SSH (port 2222) or a web-based VNC console (port 8006). It is designed for automated environments where a GUI is not required.

    Key Configuration Details:

    • Container Name: windows11
    • SSH Port: localhost:2222 (bound to 127.0.0.1)
    • RDP Port: localhost:3389 (fallback, bound to 127.0.0.1)
    • Web Console: http://localhost:8006 (VNC in browser)
    • Default Credentials: user / password
    • Resource Allocation: 8GB RAM, 4 CPU cores, 64GB disk
  3. Use the finding-duplicate-functions skill to audit semantic duplication

    main

    The finding-duplicate-functions skill is used to identify functions that serve the same purpose but have different names or implementations (semantic duplication). This is particularly effective for LLM-generated codebases where new functions are often created instead of reusing existing ones. Unlike syntactic detectors (like jscpd), this process uses LLM-powered intent clustering to find 'same intent, different implementation' scenarios.

    When to Use

    • When a codebase has grown organically with multiple contributors (human or LLM).
    • When you suspect utility functions have been reimplemented multiple times.
    • Before major refactoring to identify consolidation opportunities.
    • After running jscpd to handle syntactic duplicates first.
  4. How to control interactive CLI tools using tmux

    main

    Standard bash execution fails for interactive tools (like vim, git rebase -i, or Python REPLs) because they require a real terminal to handle input/output.

    To automate these, use tmux to create a detached session. This allows you to programmatically control the session using send-keys to inject input and capture-pane to read the current screen state. This pattern effectively provides a virtual PTY (Pseudo-Terminal) that you can interact with without a manual terminal window.

    # The core pattern for interacting with an interactive tool
    tmux new-session -d -s my_session vim file.txt
    sleep 0.3
    tmux send-keys -t my_session 'i' 'Hello' Escape ':wq' Enter
    tmux capture-pane -t my_session -p
    tmux kill-session -t my_session
  5. Prerequisites for running the Windows VM

    main

    Before setting up the Windows VM, ensure your host machine meets these requirements:

    • Docker: Installed and running.
    • KVM Support: Hardware acceleration is required. Verify by checking if /dev/kvm exists: ls /dev/kvm.
    • sshpass: Required for automated SSH authentication. Install via sudo apt install sshpass.
    • imagemagick (Optional): Required if you want to use the screenshot action for debugging. Install via sudo apt install imagemagick.
  6. How to use the Duplicate Detection Prompt

    main

    The Duplicate Detection Prompt is designed to identify semantic duplicates within a specific category of functions. It is intended to be used with an opus subagent for deep semantic analysis.

    To use this effectively:

    1. Categorize first: You must have already run the categorization process (refer to categorize-prompt.md).
    2. Filter by category: Extract functions belonging to a single category into a separate JSON file.
    3. Run per category: Execute the prompt once for every category containing 3 or more functions.
    4. Iterate: Repeat the process for each category and combine the resulting JSON arrays into a final report.
    # 1. Filter categorized.json to get functions for one category
    # Replace "validation" with your target category name
    jq '[.[] | select(.category == "validation")]' categorized.json > validation-functions.json
    
    # 2. Replace {CATEGORY} in the prompt with "validation"
    # 3. Replace <INSERT_CATEGORY_FUNCTIONS_HERE> with the contents of validation-functions.json
    # 4. Dispatch opus subagent with the prompt
  7. Function Categorization Prompt Template

    main

    Use this exact template when instructing a haiku subagent to categorize functions. Replace <CATALOG_PATH> with the path to your generated catalog.json and <OUTPUT_PATH> with your desired destination (e.g., categorized.json).

    Read the function catalog at <CATALOG_PATH> and categorize each function.
    
    Assign each function to exactly ONE category based on its primary purpose.
    
    ## Categories
    
    - **file-ops**: Reading, writing, path manipulation, directory operations
    - **string-utils**: Formatting, parsing, sanitization, case conversion, truncation
    - **validation**: Input checking, schema validation, type guards, assertions
    - **error-handling**: Error creation, wrapping, formatting, logging helpers
    - **http-api**: Request building, response parsing, URL construction, headers
    - **date-time**: Date formatting, parsing, comparison, timezone handling
    - **data-transform**: Mapping, filtering, normalization, serialization
    - **database**: Query building, connection management, migrations
    - **logging**: Log formatting, debug helpers, telemetry
    - **config**: Configuration loading, environment variables, settings
    - **async-utils**: Promise helpers, retry logic, debounce, throttle
    - **testing**: Test utilities, mocks, fixtures, assertions
    - **ui-helpers**: DOM manipulation, event handling, component utilities
    - **crypto**: Hashing, encryption, token generation
    - **provider-impl**: AI provider interface implementations (createResponse, etc.)
    - **tool-impl**: Tool interface implementations (executeValidated, etc.)
    - **event-handling**: Event creation, emission, processing, subscription
    - **session-management**: Session/thread/conversation lifecycle
    - **compaction**: Message compaction, summarization, token management
    - **other**: Doesn't fit above categories (note subcategory in purpose)
    
    ## Output Format
    
    For each function, output:
    {"file": "...", "name": "...", "line": N, "category": "...", "purpose": "one sentence"}
    
    ## Guidelines
    
    1. Focus on WHAT the function does, not HOW it's implemented
    2. If a function could fit multiple categories, choose the primary purpose
    3. Constructors: categorize based on what the class does
    4. Interface implementations: use provider-impl or tool-impl as appropriate
    5. Keep purpose descriptions concise but specific
    
    ## IMPORTANT
    
    Use the Write tool to save the complete JSON array to <OUTPUT_PATH>.
    Do NOT truncate or summarize - write ALL entries.
  8. Discover MCP server capabilities

    main

    Before interacting with an MCP server, use the discovery commands to understand its available tools, resources, and prompts. This prevents context pollution and helps you understand the required parameter schemas.

    • Tools: Use mcp tools <server-command> to list available functions.
    • Resources: Use mcp resources <server-command> to list data sources (files, DB entries, etc.).
    • Prompts: Use mcp prompts <server-command> to list pre-defined prompt templates.
    • Detailed Schema: Use --format json or --format pretty to see full parameter types and requirements.
    # Discover tools for a filesystem server
    mcp tools npx -y @modelcontextprotocol/server-filesystem /path/to/allow
    
    # Discover resources
    mcp resources npx -y @modelcontextprotocol/server-filesystem /path/to/allow
    
    # Get detailed JSON schema for tools
    mcp tools --format json npx -y @modelcontextprotocol/server-filesystem /path/to/allow
  9. Install the mcp CLI

    main

    The mcp CLI tool must be installed at ~/.local/bin/mcp. If it is not present, you can clone and build it from the source using the following steps:

    1. Clone the repository to /tmp.
    2. Build the binary with CGO_ENABLED=0.
    3. Ensure ~/.local/bin is in your PATH.

    Note: This tool allows you to dynamically discover and invoke MCP (Model Context Protocol) server capabilities without permanent configuration.

    # Clone and build
    cd /tmp && git clone --depth 1 https://github.com/f/mcptools.git
    cd mcptools && CGO_ENABLED=0 go build -o ~/.local/bin/mcp ./cmd/mcptools
    
    # Ensure PATH includes the binary
    export PATH="$HOME/.local/bin:$PATH"
  10. Categorize functions using the Function Categorization Prompt

    main

    To categorize a function catalog, use the provided prompt template with a haiku subagent. This process identifies the primary purpose of each function and assigns it to a specific category for better organization.

    Workflow

    1. Extract functions: Generate a catalog of functions from your source code.
    2. Dispatch subagent: Provide the prompt template to a haiku subagent, ensuring you replace the placeholders <CATALOG_PATH> and <OUTPUT_PATH> with actual file paths.
    3. Save results: The subagent must use the Write tool to save the complete JSON array to the specified <OUTPUT_PATH>. Do not allow the agent to truncate or summarize the output.

    Extraction Command

    Run the following command to create your initial catalog:

    ./extract-functions.sh src/ -o catalog.json
  11. Execute the finding-duplicate-functions workflow

    main

    The process follows a six-phase pipeline involving shell scripts and LLM subagents (Haiku for categorization and Opus for detection):

    1. Extract: Run ./scripts/extract-functions.sh to create a catalog.json.
    2. Categorize: Use a haiku subagent with scripts/categorize-prompt.md to create categorized.json.
    3. Split: Run ./scripts/prepare-category-analysis.sh to create individual category files in ./categories/.
    4. Detect: Use an opus subagent with scripts/find-duplicates-prompt.md for each category file, saving results to ./duplicates/{category}.json.
    5. Report: Run ./scripts/generate-report.sh to create a markdown report.
    6. Review: Perform human review and consolidate code.
  12. Install the Superpowers Lab plugin

    main

    You can install the Superpowers Lab plugin for Claude Code using either the CLI command or by manually updating your claude.json configuration file.

    Option 1: Using the CLI

    Run the following command in your terminal:

    Option 2: Manual Configuration

    Add the repository URL to the plugins array in your claude.json file.

    # Install the plugin
    claude-code plugin install https://github.com/obra/superpowers-lab
    {
      "plugins": [
        "https://github.com/obra/superpowers-lab"
      ]
    }