### Local Development Setup

Source: https://github.com/lyalindotcom/screenshotextension/blob/main/README.md

Steps to clone the repository, install dependencies, and link the extension for local development.

```bash
git clone https://github.com/LyalinDotCom/ScreenshotExtension.git
cd ScreenshotExtension
```

```bash
npm install
```

```bash
gemini extensions link .
```

--------------------------------

### Install Extension from GitHub

Source: https://github.com/lyalindotcom/screenshotextension/blob/main/README.md

Install the screenshot extension using the Gemini CLI with the provided GitHub URL.

```bash
gemini extensions install https://github.com/LyalinDotCom/ScreenshotExtension
```

--------------------------------

### Install and Link Screenshot Extension

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Commands for installing the Screenshot Extension via the Gemini CLI. Use `extensions install` for remote installation or `extensions link` for local development after cloning.

```bash
# Install from GitHub into Gemini CLI
gemini extensions install https://github.com/LyalinDotCom/ScreenshotExtension

# Local development install
git clone https://github.com/LyalinDotCom/ScreenshotExtension.git
cd ScreenshotExtension
npm install          # builds TypeScript via `prepare` → tsc
gemini extensions link .

# Manual build
npm run build        # tsc → dist/

# The MCP server is started automatically by gemini-extension.json:
```

--------------------------------

### Install Xcode Command Line Tools

Source: https://github.com/lyalindotcom/screenshotextension/blob/main/README.md

Required for window enumeration. Run this command in your terminal.

```bash
xcode-select --install
```

--------------------------------

### Manage Session Directories with SessionManager

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Creates and manages session directories for storing captured screenshots. Use `getInstance()` to get the singleton, `getFilePath()` to resolve save paths, and `listFiles()` to enumerate saved files.

```typescript
import { SessionManager } from './src/utils/session.js';

const session = SessionManager.getInstance();

// Session metadata
console.log(session.sessionId);   // "a1b2c3d4-e5f6-..."
console.log(session.sessionDir);  // "/path/to/extension/captures/session-a1b2c3d4-e5f6-..."

// Resolve a filename to an absolute path for saving
const fp = session.getFilePath("error_dialog-2024-01-15T10-30-00-000Z.jpg");
// "/path/to/extension/captures/session-a1b2c3d4/error_dialog-2024-01-15T10-30-00-000Z.jpg"

// List all captured files for this session (newest first)
const files = session.listFiles();
// ["error_dialog-2024-01-15T10-30-00.jpg", "screenshot-2024-01-15T10-25-00.jpg"]
```

--------------------------------

### WindowController.getInstance().getWindows()

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Enumerates all visible windows on the system.

```APIDOC
## WindowController.getWindows()

### Description
Enumerates all visible windows on the system by executing a Swift script.

### Method
```typescript
import { WindowController } from './src/controllers/WindowController.js';
const wc = WindowController.getInstance();
const windows = await wc.getWindows();
```

### Parameters
(no arguments)

### Response Example
```json
[
  { "id": 1234, "app": "Google Chrome", "title": "GitHub - main branch" },
  { "id": 5678, "app": "Code",          "title": "src/index.ts" },
  { "id": 9012, "app": "Ghostty",       "title": "Gemini - Project" }
]
```
```

--------------------------------

### list_windows

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Returns all currently visible on-screen application windows grouped by application name. It requires Xcode Command Line Tools and formats the output as a human-readable grouped list.

```APIDOC
## list_windows

### Description
Returns all currently visible on-screen application windows grouped by application name. It executes a temporary Swift script that uses CoreGraphics (`CGWindowListCopyWindowInfo`) to enumerate layer-0 windows, outputting each as `id||app||title` lines. The result is formatted as a human-readable grouped list. Requires Xcode Command Line Tools (`xcode-select --install`).

### Method Signature
`listWindows(): Promise<{ content: Array<{ type: 'text', text: string }>, isError?: boolean }>;`

### Parameters
This tool does not accept any arguments.

### Request Example
```typescript
const result = await listWindows();
```

### Response Example
#### Success Response (Windows Found)
```json
{
  "content": [{
    "type": "text",
    "text": "Found 5 visible windows:\n\nGoogle Chrome:\n  - ID: 1234 | \"GitHub - main branch\"\n  - ID: 1235 | \"New Tab\"\n\nCode:\n  - ID: 5678 | \"src/index.ts\"\n\nGhostty:\n  - ID: 9012 | \"Gemini - Project\""
  }]
}
```
#### Success Response (No Windows Found)
```json
{
  "content": [{ "type": "text", "text": "No visible application windows found." }]
}
```
#### Error Response (Tools Missing)
```json
{
  "content": [{ "type": "text", "text": "Failed to list windows: Failed to list windows using Swift. Please ensure Xcode Command Line Tools are installed..." }],
  "isError": true
}
```

### Gemini Slash-Command Equivalent
`/list`
```

--------------------------------

### List Open Windows

Source: https://github.com/lyalindotcom/screenshotextension/blob/main/GEMINI.md

Lists all currently open and visible application windows, providing their IDs, app names, and titles. This is useful for identifying windows to focus on.

```python
list_windows()

```

--------------------------------

### List Windows MCP Tool

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Returns a human-readable list of all visible application windows, grouped by application name. Requires Xcode Command Line Tools.

```typescript
const result = await listWindows();
// Returns:
// {
//   content: [{
//     type: "text",
//     text: "Found 5 visible windows:\n\nGoogle Chrome:\n  - ID: 1234 | \"GitHub - main branch\"\n  - ID: 1235 | \"New Tab\"\n\nCode:\n  - ID: 5678 | \"src/index.ts\"\n\nGhostty:\n  - ID: 9012 | \"Gemini - Project\""
//   }]
// }

// If no windows are found:
// { content: [{ type: "text", text: "No visible application windows found." }] }

// If Swift/Xcode tools are missing:
// { content: [{ type: "text", text: "Failed to list windows: Failed to list windows using Swift. Please ensure Xcode Command Line Tools are installed..." }], isError: true }

// Gemini slash-command equivalent:
// /list
```

--------------------------------

### Take Screenshot

Source: https://github.com/lyalindotcom/screenshotextension/blob/main/GEMINI.md

Captures the user's screen. Use `display_id` for specific monitors. Locked windows capture immediately, while full-screen captures have a 3-second countdown.

```python
take_screenshot({})

```

```python
take_screenshot({'display_id': 2})

```

--------------------------------

### SessionManager.getInstance().listFiles()

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Lists all captured files for the current session, sorted newest first.

```APIDOC
## SessionManager.listFiles()

### Description
Lists all captured files for the current session, sorted from newest to oldest.

### Method
```typescript
import { SessionManager } from './src/utils/session.js';
const session = SessionManager.getInstance();
const files = session.listFiles();
```

### Parameters
(no arguments)

### Response Example
```json
[
  "error_dialog-2024-01-15T10-30-00.jpg",
  "screenshot-2024-01-15T10-25-00.jpg"
]
```
```

--------------------------------

### Enumerate and Lock Windows with WindowController

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Manages window lock state and enumerates visible application windows. Use `getWindows()` to list windows and `fuzzyLock()` to target a specific window for screenshots.

```typescript
import { WindowController } from './src/controllers/WindowController.js';

const wc = WindowController.getInstance();

// Enumerate all visible windows
const windows = await wc.getWindows();
// [
//   { id: 1234, app: "Google Chrome", title: "GitHub - main branch" },
//   { id: 5678, app: "Code",          title: "src/index.ts" },
//   { id: 9012, app: "Ghostty",       title: "Gemini - Project" }
// ]

// Fuzzy-lock onto a window
const lock = await wc.fuzzyLock("VS Code");
// { success: true, message: "Locked onto window: 'src/index.ts' (App: Code, ID: 5678)" }

// Read back the current lock (used internally by takeScreenshot)
const locked = wc.getLockedWindow();
// { id: 5678, title: "src/index.ts" }

// Unlock
const msg = wc.unlock();
// "Window lock cleared. Next screenshot will capture the full screen."
```

--------------------------------

### MCP Configuration for Screenshot Tool

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

This JSON configuration defines how the screenshot tool is invoked using Node.js.

```json
{ "mcpServers": { "screenshot": { "command": "node", "args": ["scripts/start.js"] } } }
```

--------------------------------

### WindowController.getInstance().getLockedWindow()

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Reads back the currently locked window information.

```APIDOC
## WindowController.getLockedWindow()

### Description
Reads back the currently locked window information. This is used internally by `takeScreenshot` to determine the target window.

### Method
```typescript
import { WindowController } from './src/controllers/WindowController.js';
const wc = WindowController.getInstance();
const locked = wc.getLockedWindow();
```

### Parameters
(no arguments)

### Response Example
```json
{
  "id": 5678,
  "title": "src/index.ts"
}
```
```

--------------------------------

### WindowController.getInstance().unlock()

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Clears the current window lock.

```APIDOC
## WindowController.unlock()

### Description
Clears the current window lock, reverting to full-screen capture mode with a 3-second countdown for subsequent screenshots.

### Method
```typescript
import { WindowController } from './src/controllers/WindowController.js';
const wc = WindowController.getInstance();
const msg = wc.unlock();
```

### Parameters
(no arguments)

### Response Example
```json
"Window lock cleared. Next screenshot will capture the full screen."
```
```

--------------------------------

### WindowController.getInstance().fuzzyLock(appName)

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Fuzzy-locks onto a window based on the provided application name.

```APIDOC
## WindowController.fuzzyLock(appName)

### Description
Fuzzy-locks onto a window based on the provided application name. This is used internally to target specific windows for screenshots.

### Method
```typescript
import { WindowController } from './src/controllers/WindowController.js';
const wc = WindowController.getInstance();
const lock = await wc.fuzzyLock("VS Code");
```

### Parameters
#### Path Parameters
- **appName** (string) - Required - The name of the application to lock onto.

### Response Example
```json
{
  "success": true,
  "message": "Locked onto window: 'src/index.ts' (App: Code, ID: 5678)"
}
```
```

--------------------------------

### take_screenshot

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Captures the primary display or a specific monitor with an optional countdown. It can also capture a previously locked window instantly. The image is resized and compressed before being returned as a base64 encoded content block. Handles macOS Screen Recording permission errors.

```APIDOC
## take_screenshot

### Description
Captures the primary display (or a specific monitor) with a 3-second countdown, or captures a previously locked window instantly. The image is resized to 1280 px wide and compressed to 80 % JPEG quality before being returned to the model as a base64 `image/jpeg` content block. Permission errors from macOS Screen Recording restrictions are caught and returned as descriptive error text.

### Method Signature
`takeScreenshot(options?: { filename_prefix?: string; display_id?: number }): Promise<{ content: Array<{ type: 'image', data: string, mimeType: 'image/jpeg' } | { type: 'text', text: string }>, isError?: boolean }>;`

### Parameters
#### Options
- **filename_prefix** (string) - Optional - A prefix for the saved screenshot filename.
- **display_id** (number) - Optional - The ID of the display to capture. Defaults to the primary display (0).

### Request Example
```typescript
// Capture the primary display with a custom file prefix
const result = await takeScreenshot({ filename_prefix: "error_dialog", display_id: 0 });

// Capture secondary display
const result2 = await takeScreenshot({ display_id: 1 });
```

### Response Example
#### Success Response
```json
{
  "content": [
    { "type": "image", "data": "<base64-jpeg>", "mimeType": "image/jpeg" },
    { "type": "text", "text": "Screenshot of full screen captured and saved to: /path/captures/session-<uuid>/error_dialog-2024-01-15T10-30-00-000Z.jpg" }
  ]
}
```
#### Error Response (Permission Denied)
```json
{
  "content": [{ "type": "text", "text": "ERROR: Screen recording permission denied..." }],
  "isError": true
}
```

### Gemini Slash-Command Equivalent
`/shot`
```

--------------------------------

### Focus on Specific Window

Source: https://github.com/lyalindotcom/screenshotextension/blob/main/GEMINI.md

Locks screenshot capture to a specific window using fuzzy search. Always call `list_windows` first. The query matches against both app name and window title, with app name providing better accuracy for disambiguation.

```python
focus_window({ query: "Chrome" })

```

```python
focus_window({ query: "VS Code" })

```

```python
focus_window({ query: "Safari geminicli" })

```

--------------------------------

### SessionManager.getInstance().sessionDir

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Returns the absolute path to the current session's directory for storing captures.

```APIDOC
## SessionManager.sessionDir

### Description
Returns the absolute path to the current session's directory, where captured screenshots are stored. Falls back to `os.tmpdir()` if the local directory is not writable.

### Method
```typescript
import { SessionManager } from './src/utils/session.js';
const session = SessionManager.getInstance();
console.log(session.sessionDir);
```

### Parameters
(no arguments)

### Response Example
```json
"/path/to/extension/captures/session-a1b2c3d4-e5f6-..."
```
```

--------------------------------

### Take Screenshot MCP Tool

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Captures the primary or a specific display with a countdown, or a locked window instantly. Resizes and compresses the image. Handles macOS Screen Recording permission errors.

```typescript
const result = await takeScreenshot({ filename_prefix: "error_dialog", display_id: 0 });
// Returns:
// {
//   content: [
//     { type: "image", data: "<base64-jpeg>", mimeType: "image/jpeg" },
//     { type: "text", text: "Screenshot of full screen captured and saved to: /path/captures/session-<uuid>/error_dialog-2024-01-15T10-30-00-000Z.jpg" }
//   ]
// }

// Capture secondary display
const result2 = await takeScreenshot({ display_id: 1 });

// If Screen Recording permission is denied:
// { content: [{ type: "text", text: "ERROR: Screen recording permission denied..." }], isError: true }

// Gemini slash-command equivalent:
// /shot
```

--------------------------------

### focus_window

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Locks future `take_screenshot` calls to a specific application window using fuzzy matching on app name and title. Stores the matched window's CoreGraphics ID for subsequent screenshot calls.

```APIDOC
## focus_window

### Description
Locks future `take_screenshot` calls to a specific application window. Uses `fuse.js` (threshold 0.4) to perform fuzzy matching against both the `app` name and `title` fields of all visible windows. The matched window's CoreGraphics ID is stored in the singleton `WindowController` and used by subsequent screenshot calls via `screencapture -l <windowID>`.

### Method Signature
`focusWindow(options: { query: string }): Promise<{ content: Array<{ type: 'text', text: string }>, isError?: boolean }>;`

### Parameters
#### Options
- **query** (string) - Required - The query string to fuzzy match against application names and window titles.

### Request Example
```typescript
// Lock onto Google Chrome (matches by app name)
const result = await focusWindow({ query: "Chrome" });

// Lock onto VS Code
const result2 = await focusWindow({ query: "VS Code" });
```

### Response Example
#### Success Response (Match Found)
```json
{
  "content": [{ "type": "text", "text": "Locked onto window: 'GitHub - main branch' (App: Google Chrome, ID: 1234)" }]
}
```
#### Error Response (No Match Found)
```json
{
  "content": [{ "type": "text", "text": "No window found matching 'xyzNonExistent'." }],
  "isError": true
}
```

### Usage Notes
After successfully locking a window, subsequent calls to `takeScreenshot({})` will capture only that specific window without a countdown.

### Gemini Slash-Command Equivalent
`/lock <query>`
```

--------------------------------

### View Screenshot History

Source: https://github.com/lyalindotcom/screenshotextension/blob/main/GEMINI.md

Retrieves previously captured screenshots. Use 'list' operation to see available files, 'view' with an offset for recent captures, or specify a filename.

```python
view_screenshot_history({ 'operation': 'list' })

```

```python
view_screenshot_history({ 'operation': 'view', 'offset': 0 })

```

```python
view_screenshot_history({ 'operation': 'view', 'offset': 1 })

```

```python
view_screenshot_history({ 'operation': 'view', 'filename': '...' })

```

--------------------------------

### viewHistory

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Retrieves previously captured screenshots from the current session's captures/session-<uuid>/ folder. Supports three sub-operations: list (enumerate files newest-first), view with an offset (0 = most recent, 1 = previous, etc.), and view with a specific filename. Returns the image as a base64 JPEG content block identical to take_screenshot.

```APIDOC
## viewHistory

### Description
Retrieves previously captured screenshots from the current session's `captures/session-<uuid>/` folder. Supports three sub-operations: `list` (enumerate files newest-first), `view` with an `offset` (0 = most recent, 1 = previous, etc.), and `view` with a specific `filename`. Returns the image as a base64 JPEG content block identical to `take_screenshot`.

### Method
```typescript
const list = await viewHistory({ operation: "list" });
const recent = await viewHistory({ operation: "view", offset: 0 });
const older = await viewHistory({ operation: "view", offset: 2 });
const byName = await viewHistory({ operation: "view", filename: "error_dialog-2024-01-15T10-30-00.jpg" });
```

### Parameters
#### Request Body
- **operation** (string) - Required - 'view' or 'list'
- **offset** (number) - Optional - Used with 'view' operation to specify which screenshot to retrieve (0 is the most recent).
- **filename** (string) - Optional - Used with 'view' operation to specify a particular screenshot by its filename.

### Response Example (List)
```json
{
  "content": [
    {
      "type": "text",
      "text": "Available screenshots (Newest first):\n[0] error_dialog-2024-01-15T10-30-00.jpg\n[1] screenshot-2024-01-15T10-25-00.jpg"
    }
  ]
}
```

### Response Example (View)
```json
{
  "content": [
    {
      "type": "image",
      "data": "<base64>",
      "mimeType": "image/jpeg"
    },
    {
      "type": "text",
      "text": "Retrieved screenshot: error_dialog-2024-01-15T10-30-00.jpg"
    }
  ]
}
```

### Response Example (Error)
```json
{
  "content": [
    {
      "type": "text",
      "text": "Error: Offset 99 is out of range. Only 2 images available."
    }
  ],
  "isError": true
}
```
```

--------------------------------

### SessionManager.getInstance().getFilePath(filename)

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Resolves a given filename to its absolute path within the current session's directory.

```APIDOC
## SessionManager.getFilePath(filename)

### Description
Resolves a given filename to its absolute path within the current session's directory, facilitating file saving operations.

### Method
```typescript
import { SessionManager } from './src/utils/session.js';
const session = SessionManager.getInstance();
const fp = session.getFilePath("error_dialog-2024-01-15T10-30-00-000Z.jpg");
```

### Parameters
#### Path Parameters
- **filename** (string) - Required - The name of the file to resolve.

### Response Example
```json
"/path/to/extension/captures/session-a1b2c3d4/error_dialog-2024-01-15T10-30-00-000Z.jpg"
```
```

--------------------------------

### clearLock

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Removes the active window lock from the WindowController singleton, reverting all future take_screenshot calls back to full-screen capture mode with the 3-second countdown.

```APIDOC
## clearLock

### Description
Removes the active window lock from the `WindowController` singleton, reverting all future `take_screenshot` calls back to full-screen capture mode with the 3-second countdown.

### Method
```typescript
const result = await clearLock();
```

### Parameters
(no arguments)

### Response Example
```json
{
  "content": [
    {
      "type": "text",
      "text": "Window lock cleared. Next screenshot will capture the full screen."
    }
  ]
}
```

### Gemini slash-command equivalent
`/clear`
```

--------------------------------

### View Screenshot History with MCP Tool

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Retrieves previously captured screenshots. Supports listing files, viewing by offset (most recent first), or by specific filename. Use to access past captures.

```typescript
// Schema: { operation: "view" | "list"; offset?: number; filename?: string }

// List all screenshots in this session
const list = await viewHistory({ operation: "list" });
// { content: [{ type: "text", text: "Available screenshots (Newest first):\n[0] error_dialog-2024-01-15T10-30-00.jpg\n[1] screenshot-2024-01-15T10-25-00.jpg" }] }

// View the most recent screenshot
const recent = await viewHistory({ operation: "view", offset: 0 });
// { content: [{ type: "image", data: "<base64>", mimeType: "image/jpeg" }, { type: "text", text: "Retrieved screenshot: error_dialog-2024-01-15T10-30-00.jpg" }] }

// View two screenshots back
const older = await viewHistory({ operation: "view", offset: 2 });

// View by specific filename
const byName = await viewHistory({ operation: "view", filename: "error_dialog-2024-01-15T10-30-00.jpg" });

// Offset out of range:
const bad = await viewHistory({ operation: "view", offset: 99 });
// { content: [{ type: "text", text: "Error: Offset 99 is out of range. Only 2 images available." }], isError: true }
```

--------------------------------

### SessionManager.getInstance().sessionId

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Provides the unique identifier for the current session.

```APIDOC
## SessionManager.sessionId

### Description
Provides the unique identifier for the current session, used for organizing captured screenshots.

### Method
```typescript
import { SessionManager } from './src/utils/session.js';
const session = SessionManager.getInstance();
console.log(session.sessionId);
```

### Parameters
(no arguments)

### Response Example
```json
"a1b2c3d4-e5f6-..."
```
```

--------------------------------

### Focus Window MCP Tool

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Locks future screenshot calls to a specific window using fuzzy matching on app name and title. Stores the matched window's ID for subsequent `takeScreenshot` calls.

```typescript
// Schema: { query: string }

// Lock onto Google Chrome (matches by app name)
const result = await focusWindow({ query: "Chrome" });
// Returns:
// { content: [{ type: "text", text: "Locked onto window: 'GitHub - main branch' (App: Google Chrome, ID: 1234)" }] }

// Lock onto VS Code
const result2 = await focusWindow({ query: "VS Code" });
// { content: [{ type: "text", text: "Locked onto window: 'src/index.ts' (App: Code, ID: 5678)" }] }

// No match found:
const result3 = await focusWindow({ query: "xyzNonExistent" });
// { content: [{ type: "text", text: "No window found matching 'xyzNonExistent'." }], isError: true }

// After locking, take_screenshot captures only that window (no countdown):
const shot = await takeScreenshot({});
// { content: [{ type: "image", ... }, { type: "text", text: "Screenshot of locked window: src/index.ts (ID: 5678) captured and saved to: ..." }] }

// Gemini slash-command equivalent:
// /lock Chrome
// /lock VS Code
```

--------------------------------

### Clear Window Lock

Source: https://github.com/lyalindotcom/screenshotextension/blob/main/GEMINI.md

Removes any active window lock, reverting `take_screenshot` to full-screen capture. Use this when you no longer need to capture a specific window.

```python
clear_lock()

```

--------------------------------

### Clear Window Lock with MCP Tool

Source: https://context7.com/lyalindotcom/screenshotextension/llms.txt

Removes the active window lock, reverting screenshot capture to full-screen mode with a countdown. Use when you need to reset the capture mode.

```typescript
// Schema: {} (no arguments)

const result = await clearLock();
// Returns:
// { content: [{ type: "text", text: "Window lock cleared. Next screenshot will capture the full screen." }] }
```

```bash
// Gemini slash-command equivalent:
// /clear
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.