| name | screenpipe-team |
| description | Query the org's screenpipe telemetry as an enterprise admin — devices, members, recent activity, and substring search across the team's screen recordings and audio transcripts. Use when the user asks about their team, a teammate's activity, what their organization worked on, app usage across the org, or anything that requires seeing data beyond the user's own machine. The skill is only installed for enterprise admins; ordinary users won't see it. |
Screenpipe Team
Query the customer's team telemetry. Data lives in the customer's own Azure Blob (or our R2 bucket for hosted ingest). All reads transit our control plane today (https://screenpi.pe/api/enterprise/v1/*) which checks the bearer's admin role and returns matched records. The model (you) is the user's own local pi-agent — your prompts and the user's chat never leave their machine.
Auth
The skill authenticates with an enterprise admin API token the admin minted once on https://screenpi.pe/enterprise?tab=tokens (with scopes read:devices, read:search, read:records) and pasted into Settings → Privacy → Admin Team API Token. The desktop stored it in ~/.screenpipe/enterprise.json under team_api_token.
License-key + token are intentionally separate concerns:
license_key proves which org this machine belongs to (deployed by IT, same on every employee's device).team_api_token proves this user is an admin of that org and grants the read scopes. Employees who don't have it can't query team data even though they have the same license_key.
TEAM_TOKEN=$(jq -r .team_api_token ~/.screenpipe/enterprise.json)
SP_URL="https://screenpi.pe/api/enterprise/v1"
AUTH_HEADERS=(-H "Authorization: Bearer $TEAM_TOKEN")
If TEAM_TOKEN is empty / null, tell the user verbatim:
I need an admin API token to query team data. Open
https://screenpi.pe/enterprise?tab=tokens, create one with the
read:devices, read:search, read:records scopes, then paste it
into Settings → Privacy → Admin Team API Token. Token can be rotated
or revoked any time from the same page.
Then stop. Don't try to call the endpoints.
If the server returns 401 the token is invalid, expired, or revoked — tell the user to mint a new one. 403 means the token is missing a required scope — same dashboard, regenerate with the right scopes.
Context window protection
API responses can be large (matched OCR text + audio transcripts). Always:
- Write curl output to a file (
-o /tmp/sp_team_*.json).
- Check size (
wc -c /tmp/sp_team_*.json).
- If over ~5KB, extract with
jq rather than dumping the file into context.
- Cite results by
t (timestamp) and device (hostname or pseudonym) — don't quote multi-paragraph blocks.
Progressive disclosure
Escalate from cheap to expensive:
| Step | Endpoint | When |
|---|
| 1 | GET /devices | Always start here when the user names a teammate — match the human to a device_id. |
| 2 | GET /search?q=...&since_hours_ago=24 | The user has a topic (e.g. "atlas", "q3 forecast"). Default 24h, narrow further if results are noisy. |
| 3 | GET /search?q=...&device_id=... | Once you know whose data you want, scope to that device. |
| 4 | GET /records?device_id=...&since_hours_ago=4 | "Walk me through what X did between Y and Z" — chronological dump. Use AFTER you know the device + window from steps 1–3. |
Default since_hours_ago to 24 unless the user implies otherwise. Max 720 (30d).
1. List devices
curl -s "${AUTH_HEADERS[@]}" "$SP_URL/devices" -o /tmp/sp_team_devices.json
jq '.devices[] | {device_id, label, platform, last_seen}' /tmp/sp_team_devices.json
Each device has:
device_id — the opaque id used by /search and /recordslabel — hostname OR pseudonym (e.g. john-mbp or user_a3f201 for anonymous devices)last_seen — ISO 8601; "offline" if older than ~30minplatform, app_version — for debugging stale clients
When the user names a person ("what's john doing"), match against label. If multiple devices match, ask the user which one (or query all and aggregate).
2. Search
curl -s "${AUTH_HEADERS[@]}" \
"$SP_URL/search?q=atlas&since_hours_ago=24&limit=20" -o /tmp/sp_team_search.json
jq '.results[] | {t, device, app, window, snippet: (.text // .transcription // "")[0:160]}' /tmp/sp_team_search.json
Parameters
| Name | Description |
|---|
q | Case-insensitive substring across app_name, window_name, frame text, audio transcription, speaker, device label, browser URL. Empty = all records in window. |
device_id | Restrict to one device. Get it from /devices. |
app_name | Exact match on app_name (case-insensitive), e.g. Excel, Slack. |
since_hours_ago | Default 24, max 720. Smaller = faster + cheaper. |
since / until | ISO 8601 alternatives to since_hours_ago. |
limit | Default 50, max 200. Keep small to protect context. |
Response includes truncated: true if the byte budget was hit before the full window was scanned — narrow q or since_hours_ago and re-query rather than ask for limit=200.
3. Records (chronological)
curl -s "${AUTH_HEADERS[@]}" \
"$SP_URL/records?device_id=DEVICE&since_hours_ago=4&kind=frame&limit=100" \
-o /tmp/sp_team_records.json
jq '.records[] | {t, app, window, text: (.text // "")[0:120]}' /tmp/sp_team_records.json
| Name | Description |
|---|
device_id | Required-ish. Without it you get the whole org — usually noisy. |
kind | frame (screen) / audio / all. Default all. |
since_hours_ago / since / until | Time window. |
limit | Default 50, max 200. |
Records come oldest-first so you can describe a chronological flow.
Privacy & expectations
- Some devices report as
user_xxxxxx instead of a hostname — those users chose anonymous visibility. You can chat about them by pseudonym but should never speculate about their real identity. If the user asks "who is user_a3f201", say: that user opted into anonymous visibility and identity cannot be revealed without their consent.
- Don't dump raw text in your reply when summarizing — quote short snippets, cite by timestamp + device.
- Don't volunteer data the user didn't ask for. If they ask about engineering, don't include design.
When NOT to use this skill
- The user is asking about their own machine → use
screenpipe-api (queries localhost:3030).
- The user isn't an admin → this skill shouldn't even be installed; if it is, the API will return 403 and you should tell them their license role doesn't permit team queries.
