Documentation

Shift Space gives AI coding assistants visual context through screen recording and AI-powered video analysis.

Works With

Claude Code Auto-detected
Cursor Auto-detected
Windsurf Auto-detected
Codex Auto-detected
Continue VS Code extension
Zed Auto-detected
Any MCP tool Manual config

Getting Started

Three steps to give your AI coding assistant eyes:

  1. Install — Download or install via Homebrew/Scoop
  2. Launch — Shift Space runs in your system tray. The MCP server is automatically registered with your AI tools (Claude Code, Cursor, etc.)
  3. Use — Press Ctrl/Cmd+Shift+Space to record, or let your AI agent call the MCP tools directly

That's it. No config files to edit, no servers to start.

How It Works

Shift Space works in two modes:

Mode 1: Manual (hotkey)

  1. Press Ctrl/Cmd+Shift+Space to start recording your screen
  2. Press it again to stop
  3. AI analyzes the video — what's on screen, what you said, what moved
  4. Structured diagnosis is copied to your clipboard
  5. Paste into Claude Code, Cursor, or any AI tool

Mode 2: Agent (MCP)

Your AI coding assistant calls Shift Space tools directly — no hotkey needed:

The MCP server is registered automatically when you launch the tray app. Your AI tool discovers the tools and can use them immediately.

Account & Pro

Free tier (no sign-in needed)

Pro ($12/month)

How to upgrade

  1. Click Sign in in the tray menu (opens browser → GitHub or Google login)
  2. Go to shiftspace.dev/checkout to upgrade
  3. After payment, your account is instantly upgraded
  4. The tray app and MCP tools automatically use your Pro quota on the next recording

How Pro works with MCP

The MCP server shares your tray app login. Once you sign in from the tray menu, both the hotkey and the MCP tools use the same Pro account. Your AI agent gets unlimited sessions automatically — no extra configuration.

MCP Server Install

The MCP server lets AI coding tools call Shift Space programmatically. Choose your preferred installation method:

Option 1: One-line install (recommended)

Automatically detects and configures all installed AI tools:

# macOS / Linux
python3 -c "$(curl -fsSL https://shiftspace.dev/install-mcp.py)"

# Windows (PowerShell)
iwr -useb https://shiftspace.dev/install-mcp.py | python

Option 2: npx

Run the MCP server directly via npx (requires Node.js and Python):

npx shiftspace-mcp

Or add to your MCP config:

{
  "mcpServers": {
    "shiftspace": {
      "command": "npx",
      "args": ["shiftspace-mcp"]
    }
  }
}

Option 3: Auto-registration from tray app

The Shift Space tray app automatically registers the MCP server with detected AI tools on first launch. No manual setup needed.

Option 4: Manual registration

Run the registration script directly:

python -m mcp_server.register

Or add manually to your AI tool's MCP config:

{
  "mcpServers": {
    "shiftspace": {
      "command": "python",
      "args": ["-m", "mcp_server"]
    }
  }
}

MCP Tools

Nine tools available for AI agents:

get_capabilities
Returns a description of all available Shift Space tools and when to use each one. Call this at the start of a session so you know what visual analysis is available.

Parameters: none

check_connection
Tests connectivity to the Shift Space backend and checks authentication status. Returns whether the backend is reachable, auth status, and remaining session quota. Call this to verify Shift Space is working before trying to use it.

Parameters: none

get_visual_context
Returns the most recent screen analysis. This is what gets used when you paste a diagnosis from the tray app.

Parameters: none

take_screenshot
Captures a full-screen screenshot and sends it for AI analysis. Returns a structured diagnosis instantly. No recording needed — great for static UI bugs.

Parameters: none

start_recording
Starts recording the screen in the background. Returns a recording ID. The AI agent can trigger this, wait for a user action, then stop and analyze.

Parameters: duration (optional, default 10s, max 60s)

stop_recording
Stops an active recording and sends it for analysis. Returns the full structured diagnosis including what was seen, heard, and diagnosed.

Parameters: recording_id (optional — stops most recent if omitted)

analyze_video_file
Analyzes an existing video file on disk. Useful for test recordings, user-submitted bug videos, or CI/CD visual regression testing.

Parameters: file_path (required, path to .mp4/.mov/.webm)

analyze_url
Captures a screenshot of any webpage and analyzes it. The AI agent can check a deployed site, staging environment, or localhost preview without the user doing anything.

Parameters: url (required), wait_seconds (optional, default 3)

Requires Playwright: pip install playwright && playwright install chromium

compare_before_after
Two-phase visual comparison. First call captures the "before" state. Second call captures the "after" state and returns a side-by-side comparison. Perfect for verifying that a code change fixed a visual bug.

Parameters: before_description (str), after_description (str), duration (optional, default 5s)

Example: AI Agent Workflow

Here's how an AI coding assistant might use Shift Space tools:

# Agent starts a session — discover available tools:

1. Agent calls get_capabilities()
   → Learns about screenshot, recording, URL analysis tools

2. Agent calls check_connection()
   → Backend reachable, authenticated, 47 sessions remaining

# Agent debugging a web app:

3. Agent calls take_screenshot()
   → "I see a login form with the submit button overlapping the footer"

4. Agent fixes the CSS

5. Agent calls compare_before_after("button overlaps footer", "after CSS fix")
   → First call: captures current state
   → Agent applies fix
   → Second call: "The button is now correctly positioned above the footer"

# Agent checking a deployed site:

6. Agent calls analyze_url("https://staging.myapp.com")
   → "The hero image is broken, showing a 404 placeholder"

# Agent recording a user flow:

7. Agent calls start_recording(duration=15)
   → "Recording started"
8. User performs the action
9. Agent calls stop_recording()
   → "The dropdown menu flickers when hovering between items 3 and 4"

API Keys

API keys let you authenticate to the Shift Space API from servers, scripts, and CI/CD pipelines without using a browser-based JWT. API keys require a Pro or Team account.

Generating a key

You can create API keys from the API Keys dashboard, or via the API:

curl -X POST https://api.shiftspace.dev/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production server"}'

The response includes the full API key. Save it immediately — it is only shown once.

Using an API key

Pass the API key as a Bearer token in the Authorization header. It works everywhere a JWT works — /analyze, /billing, /sessions, etc.

curl -X POST https://api.shiftspace.dev/analyze \
  -H "Authorization: Bearer sk_live_..." \
  -F "video=@recording.mp4"

Managing keys

Key format

API keys start with sk_live_ followed by a random token. The first 16 characters (the prefix) are shown in the dashboard for identification — for example, sk_live_a1b2c3d4.

Configuration

Environment Variables

Authentication

The MCP server uses your tray app login automatically. Sign in from the tray app and the MCP tools will use the same account.

Supported AI Tools

Troubleshooting

MCP server not responding

Run check_connection from your AI tool, or test manually:

python -m mcp_server

If you see JSON output, the server is working. If you see an import error, install dependencies:

pip install mcp httpx keyring

Tool not detected during registration

The installer looks for config directories. If your tool uses a non-standard location, use manual config (see above).