CoreLive is a personal task tracker and LiveEditor archive whose centerpiece is an Activity Heatmap — every completed task accumulates as warm density across a year, so you close the app feeling validated, not graded. Built with Next.js, available as a web app and a macOS desktop app (Electron).
⚠️ Pre-launch — there are no users yet. Breaking changes are fine, anywhere. Reshape the database, Drizzle schema, APIs, or any other element freely and abruptly — there is no need to keep existing data or maintain backward compatibility. Every schema change still ships as a generated migration (CI fails whenapps/web/src/db/schema.tsandapps/web/drizzle/disagree): runpnpm db:generate, commit the SQL, then reset the database (pnpm db:reset) — a reset only replays the committed migrations.
The design system (typography, color, motion, voice) is in DESIGN.md. The product roadmap is in docs/ROADMAP.md, and per-feature design notes live under docs/design/. See docs/settings-audit.md for settings consumers, AGENTS.md for development and same-PR resolution rules, and the design-system lint package for its rules. Release changes are recorded in CHANGELOG.md.
Categories organize writing and completed history in two levels:
- Create a main category or choose a main category as its parent to create a subcategory, such as
Work / CoreLive. The sidebar shows both levels; Manage categories lets you rename, recolor, move, or promote them. A main category with children must have those children moved or promoted before it can become a subcategory. The defaultGeneralcategory stays a main category and cannot be deleted. - In the signed-in LiveEditor picker, search by the main or subcategory name, select the full displayed path, or use Create category… and Manage categories… without leaving the editor.
- Completed-history filters include a main category's direct entries and its subcategories. Weekly summaries, daily detail, and year in review group totals by main category with an optional subcategory breakdown. Moving a subcategory changes the grouping of past entries under the current hierarchy; their dates stay the same.
- Deleting a category moves its direct entries to the destination shown in the confirmation, preserving the entries and their dates. The initial destination is the parent for a subcategory and
Generalfor a main category. Children of a deleted main category become main categories with their entries still attached; rename any child that conflicts with another main category before deleting. - Deletion also preserves unsaved writing in the app or browser that performs it. Other signed-in browsers and native editors rescue their own local drafts into the selected destination when they next refresh while visible, including on focus and every 15 seconds. Draft text stays in each host's local store; failed rescue keeps the source and offers Retry. See the completed maintenance record.
This project supports:
- Web: Browser-based application accessible via web browsers
- Desktop (macOS 13+): Electron-based desktop application for macOS 13 or later
Note: Desktop builds are currently limited to macOS. Windows and Linux support has been removed.
- Docker and Docker Compose
- Node.js (24.20.0; pinned in
mise.tomland CI) - mise, installed and activated in your shell so all development commands use the pinned Node.js version
- pnpm
- Clerk
- ngrok (for local development see Clerk docs)
- Clone the repository
- Run
mise installto install the pinned Node.js version - Run
mise exec -- pnpm installto install the dependencies
The commands below assume mise is activated in your shell. After mise install, confirm that node --version prints v24.20.0 before continuing.
Use pnpm dev with pnpm qa:browser open for an isolated headless browser on
the public LiveEditor. pnpm qa:browser snapshot, screenshot, video-start,
and close operate without taking over the Mac's desktop. See
Headless development for setup, CLI examples,
Hammerspoon/accessory-mode limitations, and native QA isolation.
One root pnpm lockfile owns all workspaces. Root commands delegate to their app;
pnpm dev starts only Web, and pnpm electron:dev starts Web plus desktop.
Web-specific framework instructions are in apps/web/AGENTS.md.
| Directory | Responsibility |
|---|---|
apps/web |
Next.js, oRPC, Drizzle schema/migrations, renderer and DB tests |
apps/desktop |
Electron main/preload, macOS packaging and native unit tests |
packages/desktop-contract |
Browser-safe IPC/preload contracts and native constants used by both apps |
packages/eslint-plugin-dslint |
Design-system ESLint rules |
assets |
Canonical icons and shortcut sounds; app outputs are generated |
scripts |
Workspace, asset, environment and Headless QA orchestration |
Run pnpm install --frozen-lockfile from the root. App prebuild hooks generate
icons/sounds even in a clean checkout. pnpm clean removes compiled outputs;
pnpm check:workspace rejects old app paths and nested lockfiles. Desktop release
version, main, build resources and artifacts belong to apps/desktop; release
outputs are under apps/desktop/dist. Web does not require a new desktop release.
Configure Vercel's project Root Directory as apps/web, with files outside the root enabled
for the shared contracts and asset generator. Run Vercel commands with
--scope laststance; Preview protection remains enabled.
- Copy
.env.exampletoapps/web/.envand fill in your values. - For an existing root
.env, runpnpm setup:envonce; it preserves the root file and never overwrites existing app files. - Keep desktop signing configuration in
apps/desktop/.env. No environment files are committed.
All Next.js environment variables are loaded and validated via apps/web/src/env.mjs using @t3-oss/env-nextjs. The app will fail to start if required variables are missing or invalid.
| Variable | Side | Description |
|---|---|---|
POSTGRES_PRISMA_URL |
Server | PostgreSQL connection string |
WEBHOOK_SECRET |
Server | Clerk webhook signing secret |
CLERK_SECRET_KEY |
Server | Clerk API secret key |
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY |
Client | Clerk publishable key |
NEXT_PUBLIC_CLERK_SIGN_IN_URL |
Client | Sign-in page path (e.g., /login) |
NEXT_PUBLIC_CLERK_SIGN_UP_URL |
Client | Sign-up page path (e.g., /sign-up) |
NEXT_PUBLIC_CLERK_SIGN_IN_FORCE_REDIRECT_URL |
Client | Post-login redirect path (e.g., /home) |
| Variable | Description |
|---|---|
APPLE_ID |
Apple Developer account email |
APPLE_APP_SPECIFIC_PASSWORD |
App-specific password for notarization |
APPLE_TEAM_ID |
Apple Developer Team ID |
GH_TOKEN |
GitHub token for release uploads (optional) |
This project uses PostgreSQL v17 as the database, managed through Docker Compose for local development.
The Docker Compose service maps host port 5491 to the container's default 5432, so CoreLive does not collide with other local Postgres instances on the standard port.
# Start the PostgreSQL database
docker compose up -d postgres
# Apply migrations (SQL lives in apps/web/drizzle/, schema in apps/web/src/db/schema.ts)
pnpm db:migrate
# Seed initial data (optional)
pnpm db:seed
# After editing apps/web/src/db/schema.ts, generate the next migration
pnpm db:generateLocal database built before the move to Drizzle? It has application tables without a migration ledger. For a disposable local database, run
pnpm db:resetonce to rebuild it from every committed migration; this discards local data. Preserve needed data first. The deployment guard is read-only and never reconstructs a missing ledger automatically.
Set POSTGRES_PRISMA_URL in apps/web/.env to use the host port:
POSTGRES_PRISMA_URL="postgresql://postgres:password@localhost:5491/corelive"
Schema changes go through migrations only. Edit apps/web/src/db/schema.ts, run pnpm db:generate, review and commit the SQL, then pnpm db:migrate. Never use drizzle-kit push or pull here: their live-database introspection cannot see SkillNode_skillTreeId_id_key (the index both composite NodeEdge foreign keys point at), so they always plan to drop and re-add those keys and then fail halfway through. apps/web/drizzle.config.ts also refuses any drizzle-kit command that could connect to a non-local database when the URL comes from the environment or .env; only the deploy workflow opts out (DRIZZLE_ALLOW_REMOTE=1, honored only on a GitHub Actions runner). Credential flags typed on the command line (--url, --host, …) make drizzle-kit skip the config, so that gate does not cover them.
Basic Commands:
# Start database
docker compose up -d postgres
# Stop database
docker compose down
# View database logs
docker compose logs postgres
# Access database directly
docker compose exec postgres psql -U postgres -d coreliveAfter setting up the database, run the development server:
pnpm devOpen http://localhost:4991 with your browser to see the result.
You can start editing the page by modifying files under apps/web/src/app/. The page auto-updates as you edit.
This project loads no web fonts: text renders in the stock shadcn/ui + Tailwind system font stacks (font-sans for UI, font-mono for data).
Suites that need a real PostgreSQL (describeIfDb) are skipped unless RUN_DB_INTEGRATION_TESTS=1, which CI sets, so pnpm test and pnpm validate do not run them. With the local database up (docker compose up -d postgres), run pnpm test:db to include them before you push.
Run pnpm validate before committing. Alongside tests, lint, the build, and type checks, it runs three Fallow gates:
| Command | Checks |
|---|---|
pnpm fallow:dead-code |
Unused files, exports, types, and dependency problems |
pnpm fallow:dupes |
Duplicated source code |
pnpm fallow:health |
Function complexity and estimated change risk |
The same three checks run for pull requests and pushes to main in .github/workflows/fallow.yml, following the setup in Skills Desktop. Fallow is pinned in package.json; .fallowrc.jsonc uses its installed schema and documents the Electron entry points, generated files, indirect runtime dependencies, and component-catalog exports. Tests remain in the dependency graph, but their repeated fixtures are excluded from duplication checks. Complexity limits are 40 cyclomatic, 40 cognitive, and 120 CRAP, using Fallow's static coverage estimate rather than a machine-local coverage report.
Need ngrok to recive create.user event webhook from Clerk in local.
like ngrok http --domain=foo.bar-ngrok.app 4991
This project includes an Electron desktop application that wraps the Next.js web app. Desktop builds require macOS 13 or later.
Beyond the web app, the macOS build adds native surfaces:
- LiveEditor — a distraction-light freeform capture window
- Login window — a small fixed-size sign-in shell (
/login-shell) shown while signed out; after OAuth sign-in it closes and LiveEditor opens. If the panel fails to load, use Open LiveEditor on the signed-in recovery screen to retry without signing in again. - Startup — the app opens LiveEditor at launch, or the login window while signed out; the first launch after upgrading removes retired keys (
window.floating,behavior.startup, the retiredshortcuts.*toggles,liveEditor.syncMode/lastCategoryId) fromconfig.json - Settings — a native settings window
- System tray — menu-bar access and quick toggles
- Always-on-top — keep LiveEditor above other windows (off by default)
- Hide dock icon — run as a menu-bar-only accessory; the choice persists across restarts
- Global keyboard shortcuts — optional system-wide hotkeys, including lone-modifier keys (opt-in, off by default). If a single-modifier shortcut such as Right Option stops after an unfinished start, open Settings and select that shortcut again to retry. Startup keeps the crash guard.
- In-app shortcuts — while any CoreLive window has focus,
⌘Nopens LiveEditor in the browser and⌘Mminimizes; both release when the app loses focus - Deep links —
corelive://URLs open the app - Connection recovery — if corelive.app can't be reached, or answers with an HTTP error, while the login window or LiveEditor loads, the app retries three times and then shows a native Retry / Close dialog
- Auto-update — signed, notarized releases update in place. Choose Download Now or Later when prompted; Settings → Updates shows download progress and offers Restart to Update when ready. Check for Updates is available in Settings and the app menu.
# Run the desktop app in development mode
pnpm electron:dev
# Run Electron directly (requires Next.js dev server to be running)
pnpm electron| Command | Purpose |
|---|---|
pnpm electron:build:mac |
Production release (DMG + ZIP + signed + notarized) |
pnpm electron:build:dir |
Local production testing (unpacked .app only) |
# Local production testing (connects to corelive.app)
pnpm electron:build:dir
# Transfer apps/desktop/dist/mac-arm64/CoreLive.app to the QA VM (dist/mac/ on Intel).
# Launch and exercise it inside the guest; see docs/headless-development.md.
# Production release
pnpm electron:build:macThe built macOS applications (DMG and ZIP) will be available in apps/desktop/dist/.
Note: Only macOS builds are supported. Windows and Linux builds have been removed.
See monorepo QA and deployment ordering for the current migration, its Headless verification boundaries, and the additive category-deletion receipt migration.