Everby

Everby is a native macOS accountability companion. It is a small, chat-first desktop app that stays available like a messaging app, remembers useful context, and checks in at intentional moments.

It is an early, local-first project. Contributions, bug reports, and thoughtful product feedback are welcome.

The product is not a task manager, streak tracker, calendar, or productivity dashboard. The core idea is simpler: a thoughtful companion that can ask what is happening, remember what the user said they care about, and nudge them back into the conversation through native notifications.

Product Shape

Everby currently runs as a normal macOS Dock app. When opened, it shows a centered chat window with previous conversations visible. The user can type or dictate at any time, without starting a separate ritual or clicking a menu-bar item.

The app also checks in through notifications. Activity-based prompts can appear while the Mac is awake and the user session is active, and user-created reminders can fire later. Native macOS inline notification replies are supported, so the user can reply directly from a notification and the response is saved into the same ongoing chat.

The intended feeling is close to a quiet WhatsApp or Messages thread with someone who is paying attention, not a utility panel. It should feel personal, calm, and available.

Current Features

• Normal macOS app with Dock icon and centered main chat window.
• Persistent chat history with left/right message bubbles.
• Header area with Everby wordmark, compact tagline, and appearance settings menu.
• Push-to-talk dictation in the composer using Apple's Speech and AVFoundation frameworks.
• Dock badge for unread assistant messages, modeled on a messaging app: it appears when a check-in or reply arrives while the user is not looking at the chat, and clears the moment the chat window is brought to the foreground (window becomes key, or the app becomes active with the chat on screen). A message that arrives while the user is already viewing the chat is treated as read and never badges. Badge authorization is requested up front (.alert, .sound, .badge), so a fresh install shows the badge from the first notification without a System Settings trip; the count is driven by UNUserNotificationCenter.setBadgeCount with the AppKit dock tile as a fallback.
• Local memory for full transcript, conversation summaries, daily summaries, weekly summaries, durable facts, open commitments, reminders, check-ins, and notification logs.
• Memory review window for adding, editing, activating/deactivating, and permanently deleting durable memories. The same window exports memories, reflections, and the full transcript as a readable Markdown journal.
• Two regular check-ins per day by default: one when the user first becomes active, one anchored near wind-down time (learned from when the user typically stops being active, 19:00 by default, or set explicitly in chat or Preferences).
• Cadence is adjustable in chat: "check in four times a day", "every 6 hours", or "do the evening check-in at 10 PM".
• One open question at a time: a new proactive check-in replaces an unanswered one instead of stacking questions in the chat.
• Scheduler observes system sleep/wake, screen wake/sleep, session activity, lock state, and display activity so regular check-ins wait until the Mac is available.
• Native macOS notifications, delivered as temporary banners (the bundle sets NSUserNotificationAlertStyle to banner) so they auto-dismiss WhatsApp-style and the unread Dock badge becomes the durable signal, rather than a persistent alert that lingers on screen.
• Assistant replies count as notifications too: if a reply finishes generating while the user has switched away from the chat, it sets the unread badge and is delivered as a notification, not just silently appended to the transcript.
• Inline notification reply using UNTextInputNotificationAction.
• "Remind me in 1 hour" notification action: snoozes the prompt and re-delivers the same notification later, repeatable; answering in the app or a newer check-in cancels the snoozed copy.
• Exact notification outcome tracking: a reply is attributed only to the notification that opened the conversation or the currently visible unanswered proactive prompt. Explicit dismissals and prompts replaced by newer check-ins are recorded separately.
• Natural-language reminders such as remind me in 10 minutes to ask about this.
• OpenRouter-backed text understanding.
• Local tool calls for reminders, regular check-in cadence, commitments, durable memory, check-in summaries, conversation summaries, daily summaries, and weekly summaries.
• Local fallback extraction for simple commitments if the model fails.
• Preferences window for the evening check-in time, OpenRouter enablement, OpenRouter key, and model.
• Configurable OpenRouter provider routing and optional backup model. Automatic provider fallbacks are enabled by default instead of pinning the app to one supplier.
• Deterministic immediate-safety response for explicit self-harm language, plus prompt boundaries against diagnosis, dependency, delusion reinforcement, and presenting Everby as emergency support.
• App menu actions for ad-hoc/morning/midday/evening check-ins, test notifications, one-minute test reminders, preferences, notification settings, login item installation, and quit.

Current AI Setup

The app uses OpenRouter chat completions for text understanding and tool calling.

Recommended primary model:

deepseek/deepseek-v4-pro

Current provider routing:

OpenRouter automatic routing, provider fallbacks enabled

Preferences can optionally pin a preferred provider, disable provider fallbacks, test the current connection before saving, or set a second model to try when the primary model request fails. The configured backup model is openai/gpt-5.6-terra.

GPT-5.6 Terra is currently an OpenAI limited-preview model. If the OpenRouter account does not have access to it, remove or replace the backup model in Preferences. Everby will still use its primary model first and reports the models it tried when a connection test fails.

The app exposes local tools to the model:

• schedule_reminder: stores a local reminder that later triggers a notification.
• update_regular_checkin_cadence: changes the activity-based check-in interval, daily limit, rest gap, or evening check-in time when the user explicitly asks.
• save_commitment: records a clear commitment the user made.
• update_commitment: marks an open commitment as done, slipped, or cancelled.
• save_memory: stores durable facts worth remembering across sessions.
• update_memory: corrects an existing memory when the user explicitly supplies corrected information.
• save_checkin_summary: saves a concise summary of the interaction.
• save_conversation_summary: saves the summary of the current conversation window, such as one continuous 4:00-4:15 PM exchange.
• save_daily_summary: updates the rolling memory of the current day.
• save_weekly_summary: updates weekly themes and open loops when there is enough signal.

Reasoning is enabled for the OpenRouter request with reasoning.effort = high and reasoning.exclude = true. That lets compatible models use thinking tokens internally without showing chain-of-thought in the chat UI.

The companion prompt treats questions as optional rather than the default. It asks the model to answer direct questions first, synthesize long multi-topic updates, make evidence-based observations, avoid reflexive paraphrasing and unsupported praise, and respect exits without manufacturing a new plan. Cross-day patterns must have at least two pieces of visible support and are presented tentatively.

The app also computes conversation pacing before each model reply. Pacing uses the current session length, number of assistant follow-up questions, recent short replies, time of day, and closing cues such as tired, bed, later, tomorrow, or not more than 10 mins. The model receives one of three modes:

• continue: one grounded follow-up is allowed.
• offer_choice: taper the thread or ask whether to continue now or pick it up later.
• close: end warmly with no question.

The app also strips questions from a close response if the model ignores the pacing instruction.

The JSON settings still use legacy names like geminiModel and geminiApiKey internally for backward compatibility with earlier local state files. Runtime behavior is OpenRouter-based.

Data Storage

Everby stores local state here:

~/.everby/everby.json

Logs are written here:

~/.everby/app.log

The OpenRouter API key lives in the macOS Keychain (service com.everby.app), not in the JSON file. On first launch the app migrates any key found in an older state file into the Keychain and clears the plain-text copy. Enter or change the key in Preferences; it is written straight to the Keychain.

Memory Shape

Everby stores memory in layers:

• Full transcript: every chat message with timestamp.
• Conversation summaries: one summary for a cluster of messages close together in time.
• Daily summaries: a rolling summary of what happened today, highlights, and open loops.
• Weekly summaries: recurring themes and open loops when enough context exists.
• Durable memories: stable facts such as work identity, projects, favorite teams, gym/eating patterns, friends, preferences, and routines.

This layered approach keeps the complete history locally while giving the LLM compact context for future check-ins.

Project Structure

• Package.swift: Swift 6.2 package manifest for macOS 14 and newer.
• Sources/EverbyApp: AppKit app, chat window, notification handling, OpenRouter integration, preferences, appearance, launch-agent install, logging, unread badge tracking, and speech dictation.
• Sources/EverbyCore: Local models, JSON store, commitment/reminder logic, layered memory, conversation pacing, and regular check-in scheduler.
• Sources/EverbySmokeTests: Executable smoke-test harness for core behavior.
• Resources: App logo copied into the .app bundle.
• scripts: App bundle and DMG build scripts.
• docs: Supporting product/technical decision notes.

Build And Run

Requirements:

macOS 14 or newer
Swift 6.2 toolchain

Run the development build:

swift run Everby

swift run is useful for local iteration, but native notification behavior is only fully available when launched from Everby.app. The development executable falls back to alerts when it is not running from an app bundle.

Build the app bundle:

scripts/build_app_bundle.sh

Install locally:

ditto .build/Everby.app /Applications/Everby.app
open -n /Applications/Everby.app

Build a shareable installer (rebuilds the app, then writes Everby.dmg to the Desktop):

scripts/make_dmg.sh

The bundle script ad-hoc signs the app and copies files from Resources/ into the app bundle.

Run the smoke tests:

swift run EverbySmokeTests

Contributing

Everby is released under the MIT License. Please read CONTRIBUTING.md before opening a pull request. In short: keep changes focused, do not commit API keys or local state, and run the smoke suite before submitting changes.

Logo And Brand Brief

The current logo asset lives here:

Resources/EverbyLogo.png

Recommended source size:

1024 x 1024 px, square PNG

The checked-in asset is a 1024 x 1024 RGBA PNG. The bundle script copies it into the app bundle and generates a padded .icns so Finder, notifications, the Dock, and the DMG use the real brand mark at normal macOS icon scale.

If this asset is replaced, transparent background is fine. Keep the main mark readable at small sizes and avoid full-bleed artwork that feels oversized next to other Dock icons.

Logo Direction

Everby is a calm accountability app, not an aggressive productivity brand. The logo should suggest presence, continuity, trust, and gentle attention.

Good directions:

• A simple abstract mark that feels like a companion, signal, pulse, orbit, chat, or guiding point.
• Soft but clear geometry.
• A mark that works at small sizes.
• Modern macOS-friendly visual language.
• Calm contrast, not overly playful.

Avoid:

• Mascots or cartoon characters.
• Corporate productivity cliches like checkmarks, trophies, rockets, targets, flames, streaks, or dashboards.
• Overly medical or therapy-like symbols.
• Loud neon gradients.
• Complex line art that disappears at Dock size.
• A generic chat bubble unless it has a distinctive companion-like twist.

Suggested visual mood:

quiet, personal, attentive, trustworthy, modern, native macOS, subtle energy

Suggested colors:

deep charcoal, clean blue, soft teal, warm white

The runtime fallback logo is a simple blue C mark. It is only used if Resources/EverbyLogo.png is missing, such as in an incomplete local build.

Product Principles

Everby should stay intentionally small during MVP validation.

Do not add task boards, dashboards, streaks, gamification, or project management until the basic daily loop proves useful. The important question is whether the user keeps answering the companion over multiple days because the interaction feels helpful.

The app should prioritize:

• A fast path to talk to the companion.
• Useful memory without feeling invasive.
• Short, grounded prompts.
• Notifications that feel like a person checking in, not an app yelling.
• Local-first storage while the product is personal.

Future Ideas

The current version focuses on a dependable, local-first chat and notification loop. Areas that may be worth exploring include richer history navigation, more granular provider controls and rate-limit feedback, and eventually moving from JSON to SQLite if history querying becomes a real constraint.