ShadeCoder Clone

A Python desktop application that captures screenshots via a hotkey, sends them (with audio context) to a state-of-the-art LLM API, and renders the resulting solution on a stealth overlay that is invisible to screen sharing software (Zoom, Google Meet, CoderPad, and similar).

The product is the combination of a thin integration layer plus a stealth display layer. The heavy lifting (multi-language support, system design, follow-up suggestions, complexity analysis, edge case enumeration) is delegated to the LLM. ShadeCoder Clone focuses on capturing context, calling the LLM reliably, and rendering results in a way that cannot be detected by screen sharing or proctoring software.

Features

• Screenshot capture - A global hotkey triggers an instant screen grab of the current problem. Pillow handles image acquisition and normalization for the LLM payload.
• LLM integration - The screenshot plus optional audio context are sent to a state-of-the-art LLM API via httpx. The LLM returns a structured solution including code, complexity analysis, and edge case discussion.
• Stealth overlay - The solution renders on an overlay window that is invisible to screen sharing tools (Zoom, Meet, CoderPad, etc.). The process signature is hidden and hotkey events are not logged, so proctoring software cannot detect usage.
• Observability - Structured logging via structlog, error tracking via sentry-sdk, and distributed tracing via opentelemetry are wired in from the start.
• Feature flags - feature_flags module allows toggling behavior at runtime without redeploying.
• Metrics - metrics module exposes counters and histograms for capture latency, LLM round-trip time, and overlay render time.

Architecture Overview

ShadeCoder Clone is composed of three core components:

1. Screenshot Capture - Listens for a global hotkey, grabs the current screen with Pillow, and emits an image payload plus any captured audio context.
2. LLM API Client - Packages the screenshot and audio context, calls the configured LLM endpoint with httpx, parses the structured response, and surfaces errors via Sentry and OpenTelemetry.
3. Overlay Display - Renders the LLM response on a stealth overlay that screen sharing software cannot see. The overlay process signature is hidden and hotkey events are not logged.

Everything else (multi-language support, system design suggestions, follow-up questions, audio analysis) is the LLM doing what LLMs do. The product is the stealth layer plus the integration. See docs/architecture.mermaid for a visual diagram.

Prerequisites

• Python 3.11 or newer
• pip (bundled with Python 3.11+)
• A supported desktop operating system (macOS, Windows, or Linux with X11 or Wayland)
• An LLM API key (set via environment variable, see Environment Setup)

Installation

Install runtime and development dependencies:

pip install -r requirements.txt && pip install -r requirements-dev.txt

Single Command Setup

Install dependencies and launch the application in one command:

pip install -r requirements.txt && python -m shadecoder.main

Build Command

There is no separate build step for this Python application. Installing dependencies is the build:

pip install -r requirements.txt

Test Command

Run the full test suite:

pytest

Lint Command

Run the linter over the source tree:

ruff check src/

Format Command

Apply the code formatter to the source tree:

black src/

Type Check Command

Run static type checking:

mypy src/

Environment Setup

1. Copy the example environment file:

   cp .env.example .env

2. Open .env and fill in your API key and any other required values. See .env.example for the full list of supported variables.

3. Load the environment before running the application. Most shells will pick up .env automatically when using python-dotenv, or you can export the variables manually.

Usage

1. Start the application:

   python -m shadecoder.main

2. Press the configured hotkey to capture a screenshot of the current problem.

3. The screenshot (plus any available audio context) is sent to the LLM API.

4. The LLM response renders on the stealth overlay. The overlay is invisible to screen sharing software.

5. Press the hotkey again to capture another problem, or quit the application with the configured exit hotkey.

Project Structure

shadecoder-clone/
├── src/
│   └── shadecoder/
│       ├── __init__.py
│       ├── main.py            # Application entry point and hotkey loop
│       ├── logger.py          # structlog configuration and helpers
│       ├── screenshot.py      # Screenshot capture via Pillow
│       ├── llm_client.py      # LLM API client via httpx
│       ├── overlay.py         # Stealth overlay display
│       ├── feature_flags.py   # Runtime feature flag toggles
│       ├── tracing.py         # OpenTelemetry tracing setup
│       ├── metrics.py         # Application metrics (counters, histograms)
│       └── errors.py          # Custom exception hierarchy
├── tests/
│   ├── unit/                  # Unit tests (test_*.py pattern)
│   └── integration/           # Integration tests
├── docs/
│   ├── architecture.mermaid   # Architecture diagram
│   └── runbooks.md            # Incident response runbooks
├── .env.example               # Example environment variables
├── .pre-commit-config.yaml    # Pre-commit hook configuration
├── requirements.txt           # Runtime dependencies
├── requirements-dev.txt       # Development dependencies
├── README.md
├── AGENTS.md
└── CONTRIBUTING.md

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for development setup, code style, testing requirements, and the pull request process.

License

License placeholder. A license file (LICENSE) will be added before any public release.