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