> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenpipe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code - AI coding with screen context

> Use screenpipe with Claude Code CLI to give Claude access to your screen history, meeting transcriptions, and app context while coding.

[Claude Code](https://code.claude.com) is Anthropic's official CLI for agentic coding. with screenpipe integration, Claude can reference what you've been working on, recall information from your screen, and access meeting transcriptions.

## setup

```bash theme={null}
claude mcp add screenpipe --transport stdio -- npx -y screenpipe-mcp
```

to make it available across all your projects:

```bash theme={null}
claude mcp add screenpipe --transport stdio --scope user -- npx -y screenpipe-mcp
```

## verify connection

```bash theme={null}
# list MCP servers
claude mcp list

# or inside Claude Code, use
/mcp
```

## available tools

once connected, Claude Code has access to these tools:

| tool               | description                                                                             |
| ------------------ | --------------------------------------------------------------------------------------- |
| `search-content`   | search screen text (accessibility-first, OCR fallback), audio transcriptions, and input |
| `activity-summary` | lightweight overview of app usage, speakers, and recent texts for a time range          |
| `search-elements`  | search structured UI elements from the accessibility tree                               |
| `frame-context`    | full accessibility tree, URLs, and text for a specific frame                            |
| `list-meetings`    | list detected meetings with duration, app, and attendees                                |
| `export-video`     | export screen recordings as MP4 for a time range                                        |

## usage examples

ask Claude Code to use screenpipe naturally:

```
> what was I looking at in my browser an hour ago?

> find mentions of "kubernetes" from my screen today

> show me audio transcriptions from my last meeting

> what code was I reading in VS Code yesterday about async?

> export a video of my screen from 2-3pm today

> what did I type in Slack today?

> show me my app usage stats for the past 2 hours

> what did I copy to clipboard recently?

> which apps did I switch between most today?
```

## search parameters

### search-content (vision + audio + input)

| parameter        | description                                                            |
| ---------------- | ---------------------------------------------------------------------- |
| `q`              | search query (optional - omit to get all content)                      |
| `content_type`   | `vision`, `audio`, `accessibility`, `input`, or `all` (default: `all`) |
| `limit`          | max results (default: 10)                                              |
| `offset`         | pagination offset                                                      |
| `start_time`     | ISO 8601 UTC start time                                                |
| `end_time`       | ISO 8601 UTC end time                                                  |
| `app_name`       | filter by app (e.g., "Chrome", "Slack")                                |
| `window_name`    | filter by window title                                                 |
| `include_frames` | include base64 screenshots                                             |
| `speaker_ids`    | comma-separated speaker IDs for audio filtering                        |
| `speaker_name`   | filter audio by speaker name                                           |

## example workflows

**recall context from earlier:**

```
> I was reading a blog post about rust async earlier today,
> search screenpipe and summarize the key points
```

**reference meeting discussion:**

```
> search my audio transcriptions for what was discussed in standup
> about the API refactor, then help me implement it
```

**debug with screen history:**

```
> I saw an error message flash on screen, search screenpipe
> to find it and help me fix the issue
```

**find code examples:**

```
> search screenpipe for the python code I was looking at
> in the browser yesterday about asyncio patterns
```

**track what you typed:**

```
> what did I write in Notion this morning? search for my
> keyboard input using content_type=input
```

**recall clipboard history:**

```
> I copied something important earlier, search clipboard
> events to find it
```

## requirements

* screenpipe running on localhost:3030
* Claude Code CLI installed
* Node.js >= 18.0.0

## troubleshooting

**AI agent crashed with "Error: AI agent crashed — restarting automatically..."?**

this happens when Claude Code can't communicate with screenpipe or screenpipe encounters an error. try these steps in order:

1. **check screenpipe is running:**
   ```bash theme={null}
   curl http://localhost:3030/health
   ```
   you should see `{"status":"healthy"}`. if this fails, start screenpipe first.

2. **verify MCP is connected:**
   ```bash theme={null}
   claude mcp list
   ```
   you should see `screenpipe` in the list with status "ready".

3. **check screenpipe has recorded data:**
   ```bash theme={null}
   curl "http://localhost:3030/search?limit=1"
   ```
   if empty, screenpipe hasn't recorded anything yet—let it run for a minute and try again.

4. **restart the MCP connection:**
   ```bash theme={null}
   claude mcp remove screenpipe
   claude mcp add screenpipe --transport stdio -- npx -y screenpipe-mcp
   ```

5. **check screenpipe logs:**
   * macOS/Linux: `~/.screenpipe/screenpipe.log`
   * Windows: check event viewer or `%APPDATA%\screenpipe\logs`

**MCP not connecting?**

* verify screenpipe is running: `curl http://localhost:3030/health`
* check MCP status in Claude Code: `/mcp`
* remove and re-add: `claude mcp remove screenpipe && claude mcp add screenpipe --transport stdio -- npx -y screenpipe-mcp`

**queries returning empty?**

* check screenpipe has data: `curl "http://localhost:3030/search?limit=1"`
* ensure screen recording permissions are granted
* verify the time range you're querying

**permission errors?**

* macos: check System Settings > Privacy & Security > Screen Recording
* ensure screenpipe app is listed and enabled

still stuck? [ask in our discord](https://discord.gg/screenpipe).