cubby logo
logindocsgithub

cubby turns your screen and microphone data into context, so you can let your favorite AI know what you're working on.

cubby overview

don't panic - your data is only stored locally, and cubby is completely open source.

why use cubby?

ai with memory

your ai assistant knows what you're working on, what you've read, and what you've discussed

local-first privacy

all data stays on your device. you control who accesses it

instant setup

one install command. works with claude, cursor, and any ai tool

open source

fully transparent. self-host or use our cloud tunnel

getting started

step 1

install cubby

one command installs everything. works on macos & linux.

curl -fsSL https://cubby.sh/install.sh | sh
what you get:
  • ✓ installs cubby binary and starts background recording
  • ✓ provides your CLIENT_ID and CLIENT_SECRET
  • ✓ stores all data locally in ~/.cubby/
  • ✓ starts local server on localhost:3030
  • ✓ creates secure tunnel at api.cubby.sh
save your credentials - you'll need them for step 2
step 2

deploy ai agent

one-click deploy gives your ai access to your personal memory:

  • search your screen and audio history
  • send desktop notifications to your devices
  • open applications and urls on your devices
  • human-in-the-loop confirmations for sensitive actions
you'll use the credentials from step 1 to configure the agent
or build your own

access your data using:

typescript sdk

npm i @cubby/js

node, cloudflare, browser

rest api

api.cubby.sh

openapi spec available

mcp server

localhost:3030/mcp

claude, cursor, etc

how it works

live events streamed from your screen and microphone

// ocr event
const ocrEvent = {
  name: 'ocr_result',
  data: {
    text: 'design doc - project alpha',
    timestamp: '2025-10-18T12:34:56Z',
    app_name: 'chrome',
    window_name: 'docs.google.com',
    browser_url: 'https://docs.google.com/document/d/...',
  }
};

// audio transcription event
const transcriptionEvent = {
  name: 'realtime_transcription',
  data: {
    transcription: 'let's ship this today',
    timestamp: '2025-10-18T12:35:10Z',
    device: 'macbook-pro',
    is_input: false,
    is_final: true,
    speaker: 'sam',
  }
};

// ui frame event
const uiFrameEvent = {
  name: 'ui_frame',
  data: {
    window: 'zoom meeting',
    app: 'zoom',
    text_output: 'Recording… | Mute | Share Screen',
    initial_traversal_at: '2025-10-18T12:35:20Z'
  }
};

build with cubby

use the cubby js sdk in node, cloudflare workers, and browsers. published as @cubby/js

installation

npm i @cubby/js

authentication

get credentials at cubby.sh/dashboard

export CUBBY_CLIENT_ID="your_client_id"
export CUBBY_CLIENT_SECRET="your_client_secret"

common ways to use cubby:

search

query your history

import { createClient } from '@cubby/js';

// credentials auto-detected from env
const client = createClient({ 
  baseUrl: 'https://api.cubby.sh',
  clientId: process.env.CUBBY_CLIENT_ID,
  clientSecret: process.env.CUBBY_CLIENT_SECRET,
});

// list devices and select one (for remote)
const { devices } = await client.listDevices();
client.setDeviceId(devices[0].id);

// find that article you read last week
const results = await client.search({
  q: 'dolphins',
  content_type: 'ocr',
  limit: 5
});

watch

process live events and trigger actions

// auto-create todoist tasks from spoken todos
for await (const event of client.streamTranscriptions()) {
  if (event.text?.toLowerCase().includes('todo')) {
    const task = await ai.generateStructuredOutput({
      prompt: `extract task from: "${event.text}"`,
      schema: { title: 'string', priority: 'high|medium|low' }
    });
    await todoist.create(task);
    await client.notify({ 
      title: 'task added', 
      body: `"${task.title}" - ${task.priority} priority` 
    });
  }
}

contextualize

power ai with your personal context

// smart email responses based on recent chats
const recentChats = await client.search({
  q: 'slack messages project alpha',
  content_type: 'ocr',
  limit: 15
});

const draft = await ai.chat.completions.create({
  messages: [
    { role: 'system', content: 'draft professional email' },
    { role: 'user', content: `context: ${JSON.stringify(recentChats)}` }
  ]
});
await gmail.users.messages.send({ raw: encodeDraft(draft) });

automate

build smart automations

// auto-log work hours when specific apps are active
for await (const event of client.streamVision()) {
  if (event.data.app_name === 'Linear' && event.data.text?.match(/ENG-\d+/)) {
    const ticketId = event.data.text.match(/ENG-\d+/)[0];
    await timeTracker.startTimer({ project: 'engineering', ticket: ticketId });
    await client.notify({ title: 'timer started', body: `tracking time on ${ticketId}` });
  }
}

use with ai assistants

model context protocol (mcp) gives ai assistants direct access to your cubby data.

local access (claude desktop, cursor)

add to your mcp config:

{
  "mcpServers": {
    "cubby": {
      "type": "streamable-http",
      "url": "http://localhost:3030/mcp"
    }
  }
}
no authentication required for local use

remote access

use https://api.cubby.sh/mcp with bearer token authentication

  1. get credentials at cubby.sh/dashboard
  2. exchange for token: curl -X POST https://api.cubby.sh/oauth/token -d "grant_type=client_credentials&client_id=ID&client_secret=SECRET&scope=read:cubby"
  3. add to mcp config:
{
  "mcpServers": {
    "cubby": {
      "type": "streamable-http",
      "url": "https://api.cubby.sh/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
remote tools require deviceId parameter

available tools

devices/list

list enrolled devices

devices/set

select device for calls

device/search

search content

device/search-keyword

fast keyword search

device/speakers/search

find speakers by name

device/open-application

launch applications

device/open-url

open urls in browser

device/notify

send notifications

device/audio/list

list audio devices

device/vision/list

list monitors

+ more

frames, tags, embeddings

rest api

full openapi spec for custom integrations

local server

# runs on localhost:3030 after install
curl http://localhost:3030/openapi.json

# example: search content
curl "http://localhost:3030/search?q=project&limit=10"

key endpoints

GET /searchsearch across screen, audio, ui
GET /search/keywordfast keyword search
GET /speakers/searchfind speakers
POST /open-applicationlaunch apps
POST /open-urlopen urls
POST /notifydesktop notifications
WS /eventsstream live events

remote api

# authenticate
curl -X POST https://api.cubby.sh/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@email.com", "password": "pass"}'

# list devices
curl -H "Authorization: Bearer TOKEN" \
  https://api.cubby.sh/devices

# search on specific device
curl -H "Authorization: Bearer TOKEN" \
  "https://api.cubby.sh/devices/DEVICE_ID/search?q=hello"
full api reference: api.cubby.sh/openapi.json