how to use

getting started

a short list of things to try, each one paying capy credits.

a new account starts with a reminders bucket and the guide open. it lists 18 things to try, from adding a reminder to connecting telegram.

each task ticks itself once you've done it.
hint takes you straight to the place in the app the task is done.
on heycapy.xyz every task gives capy credits, 50 for the whole list.

don't want the button in the header? hide it from the guide. it stays under ··· → getting started.

find it: header → [guide] or ··· → getting started

install as an app

put heycapy on your phone's home screen or your computer, like any other app.

heycapy then opens in its own window, without the browser around it. nothing to download from an app store, and it stays up to date by itself.

iphone and ipad: in safari tap share → add to home screen.
android: in chrome open the ⋮ menu and tap install app or add to home screen.
computer: in chrome or edge click the install icon in the address bar, or in chrome's ⋮ menu pick cast, save and share → install page as app.

on an iphone, push only works from the home screen app. open heycapy from there, then turn push on in tweaks → notifications.

find it: your browser's menu, on app.heycapy.xyz

buckets

organize anything into lists. pick a template or start blank.

buckets are top-level containers. each one is its own list with independent settings.

pick a template (blank, reminders, subscriptions, todo, work or ci/cd monitor) and name it anything.
drag the tab bar to reorder. archive buckets you don't need right now.
each bucket has its own sort order, readonly mode, and show/hide completed toggle.

deleted buckets go to trash — restore them anytime from the header menu.

find it: home → [add bucket][guide]

items

add tasks with titles, deadlines, and optional recurring schedules.

items have a title, optional deadline, status, and optional recurring config.

type the date into the title, like "pay rent friday 9am", and it fills in by itself.
click any item to edit it. enter to save, escape to cancel.
items on hold get no reminders until you change their status.
custom schema fields show up as extra inputs in the item editor.

items added via webhook show a source badge so you know where they came from.

find it: inside any bucket[guide]

search

find any open item in every bucket, shared ones too.

search looks through the titles of every item still to do, in all your buckets.

results show which bucket each item is in, and who it's for in a shared bucket.
the ones due soonest come first, up to 50 at a time.
tap a result to open and edit it right there.

completed and missed items, and items in archived or deleted buckets, are left out.

find it: [search], next to add + or on today

share a bucket with family or friends. [beta]

invite people with a code, a link or a qr code. everyone sees the same list and can add to it.

join one from ··· → join a bucket, or just open the link.
give an item to someone with assigned to, or type @ in the title. only they get reminded.
each person is reminded on their own channels, in their own timezone.

others only see your username and pixel avatar, never your email.

find it: bucket settings → members[guide]

notifications

email from your own account, push, telegram, ntfy, discord, slack or any url, per bucket. when to remind, overdue alerts, snooze and done buttons.

set channels and reminders once in tweaks → notifications → bucket defaults. buckets follow them, and each can change any setting for itself.

reminders: how long before the deadline you get reminded. you can pick different ones on a single item.
remind at: the time all-day items are reminded at. nothing from the bucket arrives earlier in the day.
keep reminding: once, or daily until the item is done.
if it's overdue: an alert after the deadline, then again as often as you pick.
remind me again in: the snooze buttons on each reminder.
notify on arrival: a notification for every item a webhook adds.

quiet hours live in tweaks → notifications: nothing is sent between, say, 22:00 and 07:00.

find it: bucket settings → notifications[guide]

webhooks

every bucket has a url + key. post {"title": "..."} from anywhere.

every bucket gets a unique url and key. rotate the key anytime.

minimum payload: {"title": "your item"}
optional: "deadline" (ISO datetime), "status" ("active" / "completed" / "on hold")

curl -X POST https://app.heycapy.xyz/api/webhook/ID \
  -H "Authorization: Bearer KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "deploy failed"}'

if the bucket has a custom schema, include those fields too — they get validated on arrival.

find it: bucket settings → advanced[guide]

ai chat

capy lives bottom-right. add items, parse deadlines, ask things.

capy can add items, parse natural language deadlines, and answer questions about your buckets.

ctrl+\ to toggle the chat open/closed.
use capy credits, or your own key in tweaks → ai.
supported: ollama (local), openai, anthropic, groq, gemini.

chat history is saved — access it via the history icon in the chat header.

find it: bottom-right corner[guide]

voice input

tap the mic in capy chat and say what you need.

tap the mic to start recording. tap again or hit stop when done.

the recording is turned into text and put in the chat box, so you can check it before sending.
a recording can be up to 2 minutes.
on heycapy.xyz voice itself is free, the message it becomes uses a capy credit.
with your own key, pick groq, openai or gemini for voice in tweaks → ai → voice.

keyboard shortcut: ctrl+shift+m to toggle recording without touching the mouse.

find it: capy chat → mic icon[guide]

bucket schema

define custom fields per bucket: text, numbers, money, dates, links, lists and more.

schema attaches structured data to every item beyond just title and deadline.

field types: text, textarea, number, currency, boolean, date, datetime, url, select and multiselect.
fields appear in the item editor and can be marked required or optional.

webhook payloads are validated against the schema — missing required fields get rejected with a clear error.

find it: bucket settings → advanced → schema[guide]

smtp

reminder emails go out from your own email account. gmail takes two minutes.

heycapy only sends sign-in codes itself. reminders need your own account.

fields: host, port, send from, app password.
gmail: smtp.gmail.com, port 587, your gmail address and an app password.

after saving, press send test email to check it works.

find it: tweaks → notifications → email[guide]

telegram bot

connect telegram for notifications and adding items from chat.

heycapy has its own telegram bot. no need to create one.

go to tweaks → notifications → telegram and press [connect].
open the link it gives you in telegram and tap start.
once connected, buckets with telegram enabled will push reminders directly to you.

per-bucket config (shortcuts, time slots, deadline buttons) is in bucket settings → notifications → configure telegram.

find it: tweaks → notifications → telegram[guide]

recurring items

repeat any item every so many days, weeks, months or years.

turn on repeat in an item and pick how often: every so many days, weeks, months or years.

weekly can be on chosen days, or on weekdays in one tap.
monthly can be on the same day, or on the last day of the month.
set an end date to stop it after a certain day.

each bucket decides what comes next: wait for me, move on if missed, or after completion.

find it: item editor → recurring[guide]

themes

18 color themes, from capy and gruvbox to tokyo night, catppuccin and terminal.

heycapy starts in gruvbox dark. tap any swatch and the whole app switches right away, no save needed.

light: capy, light, gruvbox light, rosé pine dawn.
dark: dark, gruvbox, gruvbox dark, everforest, tokyo night, rosé pine, nord, dracula, solarized, catppuccin, one dark, night owl, midnight.
and terminal: green on black, like an old screen.

each browser remembers its own theme, so your phone and laptop can look different.

find it: tweaks → appearance → theme

timezone

reminders arrive on your clock, and heycapy notices when you travel.

your timezone comes from your browser when you sign up. deadlines, quiet hours and repeats all run on it.

to change it by hand, type a timezone like "Europe/London" or "Asia/Kolkata" and save.
travel somewhere else and a note says "you seem to be in Japan now · reminders still run on India time".
press update to move your reminders to the new clock, or keep the old one. it won't ask again until you move on.

in a shared bucket everyone is reminded in their own timezone.

find it: tweaks → appearance → timezone

capy's personality

rename capy and pick how it talks: chill, professional, motivational or your own style.

this changes how capy sounds in the chat, in telegram and in ai reminder texts. what it can do stays the same.

name: call capy anything, up to 50 characters.
tone: chill, professional or motivational. rude & funny roasts you about procrastinating, but never gets truly mean.
custom: describe the style yourself, like "talk like a pirate". prompts asking for anything other than a style are refused.
use emoji: on or off.

find it: tweaks → personality

your account

your username and avatar, a download of all your data, and deleting your account.

your username and pixel avatar are what other people see when you share a bucket.

download my data: one file with your buckets, items, settings, notification history and chats. api keys and passwords are never in it.
delete account: heycapy emails you a code, and once you type it in everything is gone for good.
if you own a shared bucket, give it to someone else, delete it or remove everyone first.

copies in the nightly backups are gone within 7 days.

find it: tweaks → account

self-hosting

run heycapy on your own server with docker.

heycapy is open source. run it yourself for free.

clone the repo, copy .env.example to .env and fill it in.
put your domain in the Caddyfile, then docker compose up -d.

the guide covers email, telegram, ai and backups.

find it: github.com/heycapy/heycapy[guide]