A time tracker and earnings ledger for the desktop, Android and the web, built with Tauri v2, React, TypeScript and Rust. You track time in sessions against tasks with hourly rates, reconcile it against work logs imported from DataAnnotation, and see what you've earned and when it pays out. Signed in, your devices and the web app (https://taskmint-f9a05.web.app) share the same data through Firebase.
| Page | What it's for |
|---|---|
| Home | Where TaskMint always opens: what's running (or one-click starts for your favorite and most recent tasks), today's and this week's earnings and time as the Calendar counts them, the daily goal, the next withdrawal, your last few sessions, and a reminder to import work logs when the last import is a few days old. |
| Sessions | Pick a task and its timer starts; pause, resume and stop timers inside the session, and add timers for other tasks to it (each day's work gets its own session). Each timer's row shows its task, and live totals cover the active session. The list shows which tasks each session ran and their totals; it covers the last 30 days (older ones a click away) and filters by source. Add time logs a finished timer after the fact (a "Manual" session). |
| Tasks | Tasks with hourly rates and default note templates; start one, star favorites, archive tasks you're done with. Each task lists its newest entries and opens History for the rest. Time keeps the rate it was tracked at, so changing a rate only affects new time. |
| Notes | Free-form or template-based notes on a task (pick it on the Notes page), a session or a timer. A session's notes open from its row, which previews the newest one. Note templates have their own tab. |
| History | Every tracked, added and imported entry: quick ranges (remembered), search and task filters, totals and charts, the sortable entries table (edit, move an entry to another task, delete, CSV export; imported days are read-only, since each import rebuilds them), and the daily goal's results over the range. |
| Calendar | Earnings, hours and released amounts per day, and the month's totals; click a day for its tasks and releases. |
| Payouts | Import DataAnnotation work logs and see available, pending and upcoming releases, when the last import was, and a daily reconciliation grouped by month. An import's notice has Undo, which puts the ledger and the days it rewrote back as they were (refused once one of those days has changed). Project mappings lists which task each project goes to; moving a project moves its past imported days too. |
| Settings | Cloud sync, appearance, payouts (funds-release delay, days between withdrawals), idle detection and the long-run reminder, daily goal, backups (and restoring one), data export/import/exact restore/reset, privacy, and About (release notes, and About TaskMint…). |
Each page you open starts at its top. Keyboard shortcuts (⌘ on macOS, Ctrl elsewhere): ⌘1–⌘8 open the pages in sidebar order (Home first), ⌘N a new task, ⇧⌘N starts work, ⇧⌘P pauses or resumes the timer, ⌘, opens Settings, and ⌘K the command palette, which also has About TaskMint, Check for updates (desktop) and Sign out of cloud sync. On a phone, tabs along the bottom open Home, Sessions, Calendar and Payouts, and the top bar's menu opens every page.
The menu bar (macOS; on Windows, menus across the top of the window) has TaskMint's own menus: About TaskMint and Check for Updates…, Settings and Cloud Sync…; File (New Task, Start Work…, Add Time…, Import Work Logs…); View (each page, the command palette); Timer (pause or resume, and stop, the running timer, by name); and Help (TaskMint's help and a new problem report on GitHub, What's New, the keyboard shortcuts, and the data and logs folders). About TaskMint shows the version and release date, checks for updates on the desktop, opens those pages and folders, and copies diagnostics (version, system, folders, sync status, never your account) for a problem report.
The system tray (menu-bar item on macOS) shows the running or paused timer and can pause, resume or stop it, start a task's timer, or open the app. Its Start menu lists starred tasks first, then the ones you used most recently; Choose Task… opens the app's start dialog for any other task. Starting work behaves the same everywhere (tray, Sessions toolbar, the + button): with a session active, the task joins it, resuming its paused timer or starting a new one, and stopping whatever is running (a toast says so). Only End Session ends a session; a session left active from an earlier day gives way to a new one. Work starts from existing tasks; create new ones on the Tasks page. Closing the window hides TaskMint to the tray, where timers keep running; quit from the tray menu. On macOS, clicking the Dock icon brings the window back.
Earnings are rate × time everywhere, at the rate captured for each timer: its session's when it's on the task the session opened for, otherwise its own task's when the timer was created (imported days carry the rate the site's pay implies, so they match Payouts). With a daily goal set, the sidebar shows today's progress live, and notifications fire at 50%, 75% and 100% as you cross them.
Inactivity detection (off by default; Settings → Idle & Reminders) uses the system idle time, so work in any app counts. When there's been no keyboard or mouse input for the threshold, the running timer pauses as of when input stopped, so the away time isn't counted. When you're back, TaskMint comes to the front and asks whether to discard the away time and resume, keep it and resume, or stay paused; the tray offers the same choices. This works on macOS and Windows.
The long-run reminder (on by default, after 4 hours) sends a notification when a timer has run that long without a pause, for the timer you forgot to stop. It works with inactivity detection off. On a phone it's an alarm set when the timer starts, so it arrives with TaskMint closed, and its hours are under Settings → Notifications.
The desktop and Android apps keep everything on the device and work offline. With cloud sync on, they also keep it in step with your other devices and the web app.
| Data | Store |
|---|---|
| Sessions and timer instances | sessions.json in the app data dir, owned by the Rust backend |
| Imported work logs and project→task mappings | worklogs.json in the app data dir, owned by the Rust backend |
| Tasks, notes, note templates, the daily goal and its history, withdrawals, and the payout settings (funds-release days, days between withdrawals) | appdata.json in the app data dir, owned by the Rust backend (see below for data from older versions) |
| Cloud sync: the account this device syncs with, this device's id, and what the cloud last said | sync.json in the app data dir, owned by the Rust backend |
| Other settings and UI preferences (appearance, notifications, idle and reminders, backups, analytics) | The webview's localStorage (each device has its own) |
App data dir on macOS: ~/Library/Application Support/com.taskmint.desktop/
(a dev build's is com.taskmint.desktop.dev/).
Before 2.1 the app identifier was com.taskmint.app: the first launch of a
newer version moves that data folder and the webview's storage (the
settings) to the new identifier, and logs what it moved. Nothing moves if the
new folder is already there.
Before risky operations (a skipped-record load, an import that rewrites days, a
restore), the backend writes timestamped *.bak-* copies next to the stores,
keeping the newest 10 of each.
Data from older versions. Earlier versions kept tasks, notes, templates
and the goal in the webview's localStorage. On launch, an installed build
moves any it finds into appdata.json: list items are added by id, nothing
already in the file is replaced, a copy of what was moved is saved as
appdata.json.bak-<time>, and the localStorage copies are then removed.
Development builds (pnpm tauri dev) skip this: their webview storage is
separate from the installed app's, but the data folder is shared. The payout
settings used to be device settings: an installed build, and the web app,
move this device's values into the accountSettings record once, unless
it's set already, and then remove them from localStorage.
Backups. Settings → Data Management exports everything above to one JSON
file (format v3, with a copy of this device's own settings) and imports it
back. Import Data adds what isn't already present (existing data wins) and
leaves this device's settings alone. Restore Exactly asks first, then
replaces everything with the file's, this device's settings included, in one
change (the backend keeps its .bak copies first);
a section an older file doesn't have (work logs in v1, withdrawals and payout
settings before v3) is left as it is. The app reloads after either. Settings →
Automatic Backups writes the same file to a folder daily, weekly or monthly,
keeping the newest N, and lists the backups in that folder with Restore
exactly and Merge for each. They start on (weekly, into Backups
inside the app's data folder, which needs no permission; About → Show data
folder shows it) unless you've saved a backup setting before.
Reset. Settings → Data Management → Reset All Data wipes the data files
(sync.json too), their .bak copies and localStorage, and signs this
device out of cloud sync. The cloud's copy and your other devices keep their
data. In the web app, whose data is the cloud's, it deletes the cloud data.
A scratch data folder. TASKMINT_DATA_DIR=<folder> makes a development
build keep its files and its logs (in logs/) there, so the installed app's
are left alone.
Settings → Cloud sync signs this device in with an email and password, or with Google, and keeps its sessions, work logs, tasks, notes, templates, goal, withdrawals and payout settings in step with your other devices and the web app. Anyone can make an account. Without one, everything stays on the device. Device settings (appearance, notifications, idle, backups) don't sync.
- First sign-in. When both this device and the account already have data, TaskMint asks: Merge them (lists join by id; where the same item changed on both, this device's version wins), or Use the cloud's data (this device's is replaced, after a copy is kept in the data folder).
- Offline. Changes wait on the device and go when it's back online. The chip says how many are waiting. When two devices changed the same data meanwhile, the changes merge: timers added to the same session on both are both kept, and where the same task, note or setting changed on both, the device that syncs last wins.
- One running timer. When devices started timers while apart, the one started or resumed last keeps running and the others stop at its start. Each timer runs on the device that started it: idle detection and the long-run reminder on the desktop act only on timers running there, not on the phone's (the phone sets its own long-run alarm).
- Sign out (in Settings → Cloud sync, or "Sign out of cloud sync" in the ⌘K palette) asks first, then signs this device out and keeps its data; the cloud and the other devices keep theirs. Delete cloud data deletes the account's data from the cloud and stops every device syncing, each keeping its own copy. The foot of the sidebar shows where sync stands (Synced, Syncing…, Not signed in, Sync needs attention) and opens these settings.
- Another account. A device that syncs with one account and is signed in with another says so, and offers to sync with the new one from then on (its data joins that account's). After signing out, signing in to a different account asks before this device's data goes there, even when that account is empty: Add it to this account, or Start empty (this device's data is cleared, after a copy is kept in the data folder).
- Newer data. Data saved by a newer TaskMint is left alone and Settings says to update.
- BudgetMint. A synced device also publishes your payout forecast (what the coming withdrawals will take, as amounts and times only) for BudgetMint, which keeps its own data in its own Firebase project and signs in to TaskMint's only to read the forecast. It's written only when your payout data changes. Delete cloud data and Delete account delete it, and leave BudgetMint's own data alone. The contract is docs/contracts/payout-forecast.md, the design ADR 0003.
The design is ADR 0002. How the Firebase project is set up, and how to develop against its emulators: Firebase.
apps/extension/ is a Chrome extension that captures your DataAnnotation
work logs from the payments page and delivers them to the app over
http://127.0.0.1:43117, or through a taskmint:// link that launches the app
if it's closed. The app accepts localhost deliveries only from this
extension's fixed ID. Payloads that arrive only by link wait in Payouts for
review, since any web page can open a link. When the app window isn't in
front, each capture's result also shows as a desktop notification. With cloud
sync on, a capture reaches your other devices and the web app from there. See
apps/extension/README.md.
If VITE_SENTRY_DSN is set at build time, crashes and errors are reported to
Sentry. Reports contain the error and where in the app it happened. Task
names, notes, earnings and work-log data are stripped before sending, and
there's no session replay or tracing. Turn it off in Settings → Privacy.
The web app and the Android app also send which pages are opened to Firebase Analytics, and nothing else: no data. Share usage statistics in Settings → Privacy turns it off on that device; in the web app, Google's tag doesn't load while it's off. The desktop app has no analytics.
Prerequisites: Node 24 (.node-version), pnpm (pinned via
packageManager; corepack enable picks it up), and rustup. The Rust version,
its components and the wasm32-unknown-unknown target are pinned in
rust-toolchain.toml; rustup toolchain install in the repo installs them.
The web app's core also needs the wasm-bindgen CLI at the version of the
wasm-bindgen crate in Cargo.lock (pnpm build:wasm says which, and how
to install it), and the Firestore rules' tests need Java 21 or later
(brew install openjdk). node scripts/check-toolchains.mjs checks the pins
agree.
pnpm install
pnpm tauri dev # desktop app with hot reload (Vite on :1420)
pnpm dev # Vite only, for tauri dev; a plain browser has no backend and stops at the startup errorTaskMint in a browser is the web app: see Web app.
Every build you make here is a dev build: "TaskMint Dev", which installs and runs beside the real TaskMint with its own data, on the dev Firebase project. Only releases are the real app (Dev environment).
App icons. The masters are in assets/brand/: icon.png (the app icon),
icon-macos.png (the same on Apple's icon grid), the wordmark logo.png and
logo-dark.png, and the leaf mark.png. After changing the icon, regenerate
the bundle icons, then replace the .icns with the macOS-grid one:
cd apps/desktop && pnpm tauri icon ../../assets/brand/icon.pngcd apps/desktop && pnpm tauri icon ../../assets/brand/icon-macos.png -o /tmp/taskmint-icons && cp /tmp/taskmint-icons/icon.icns src-tauri/icons/tauri icon also writes Android, iOS and Windows Store sizes the bundle
doesn't use; delete them again:
cd apps/desktop/src-tauri/icons && rm -rf android ios Square*Logo.png StoreLogo.png 64x64.pngThe menu-bar icon (src-tauri/icons/tray-template.png, a black leaf on
transparent that macOS tints) and the images in packages/client/public/ and
apps/extension/icons/ are made from the same masters, and so is Android's
launch screen (Android).
Copy .env.example to .env to set a Sentry DSN (otherwise reporting stays
off), the desktop's Google sign-in client (Firebase; without
it the desktop signs in by email only), or the Firebase emulators' host.
The desktop crate also builds as a Tauri Android app (apps/desktop, the same
Rust and webview), package com.taskmint.android (tauri.android.conf.json
sets it; the desktop app stays com.taskmint.desktop). A
dev build is com.taskmint.android.dev, "TaskMint Dev",
and installs beside it. Each release has
TaskMint-X.Y.Z-android-arm64.apk for arm64 phones, every phone from roughly
the last eight years.
Installing it. Open the release on the phone and download the APK.
Opening it asks you to let the browser (or Files) install unknown apps;
allow it, go back and install. A later release's APK installs the same way,
over the app, and keeps its data: they're all signed with the same key (see
Android signing). The app checks for a new release at
launch and daily, as the desktop does (Settings → Updates). Its Download
fetches the new APK itself (AppUpdate.kt, into the app's cache), shows how
far it is, and opens Android's installer on it; the first time, Android asks
to let TaskMint install apps. A download that's interrupted keeps what it
has and asks GitHub for the rest only: by itself once TaskMint is in front
again when leaving it was the reason (Android takes an app off the network
within seconds of it leaving the screen), and on Try again otherwise. The
whole APK is checked against its signature before the installer opens. If
the download fails, Open in browser hands the APK's
link to the browser, as releases up to 4.8.0 always did. With Android's
Advanced Protection on, the phone installs nothing from outside Google Play:
the update dialog then shows the steps to turn it off, with a button to the
phone's Security settings, and offers the download once it's off.
What the phone adds, around the same app:
- the running timer in a notification: the task you're on, today's time counting and the money earned today, with Pause, Switch task and Stop. Both figures keep up with TaskMint closed. On Android 17 it's a Live Update, so today's time also counts in the status bar (an Android 16 system that has Live Updates promotes it too; 16's first release takes the request and shows it as before). From Android 16 its channel has the default importance with no sound, since a lock screen leaves out a low-importance notification, Live Update or not;
- the long-run reminder, end-of-day summary and goal milestones as alarms that arrive with the app closed;
- launcher shortcuts (long-press the icon) for the likeliest tasks, Add time and Payouts;
- Today, Payouts, Calendar and This week home-screen widgets, which the widget picker shows with your own figures (Android 15 and later). With cloud sync they and the running timer's notification follow your other devices with TaskMint closed: within seconds where a push message gets through, and at a check every quarter of an hour otherwise;
- touch feedback on the timer;
- a swipe in from the left edge, just above the bottom tabs, to open the menu.
Most of the Android-only code is gen/android/.../MainActivity.kt (its
TaskMintApp bridge), Widgets.kt, Launch.kt, Reminders.kt and
TimerNotice.kt (the two kinds of notification TaskMint posts itself, which
the shell reaches through RemindersPlugin).
Prerequisites, besides the ones above:
- Android Studio, or the command-line tools, with SDK Manager's Android SDK Platform, Platform-Tools, Build-Tools, Command-line Tools and NDK (Side by side).
- JDK 17 or later; Android Studio's own works
(
/Applications/Android Studio.app/Contents/jbr/Contents/Homeon macOS). JAVA_HOME,ANDROID_HOME(usually~/Library/Android/sdk) andNDK_HOME($ANDROID_HOME/ndk/<version>) set in your shell.- The Rust Android targets.
tauri android initinstalls them; by hand:
rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-androidThe Android project, apps/desktop/src-tauri/gen/android, is committed. It
was made by pnpm tauri android init from tauri.conf.json and
tauri.android.conf.json, and changed in these places (each marked
TaskMint:):
-
app/build.gradle.ktssigns release builds with the release key whenTASKMINT_ANDROID_KEYSTOREandTASKMINT_ANDROID_KEYSTORE_PASSWORDare set (Android signing). Without them a release build is unsigned. It also readsTASKMINT_ENV(Dev environment): unless it'sproduction, the app iscom.taskmint.android.dev("TaskMint Dev",applicationIdSuffix; the code's package stays the same) with Analytics off (firebase_analytics_collection_deactivatedin the manifest). The debug build type's suffix is the line the Tauri CLI keeps in step withdebugApplicationIdSuffixintauri.android.conf.json, which is also the nametauri android devstarts after installing. -
Firebase:
app/firebase/google-services.production.jsonandgoogle-services.dev.json(each project's Android app's public config, downloaded from the Firebase console;app/build.gradle.ktscopies the build's to the gitignoredapp/google-services.json), thegoogle-servicesGradle plugin (in the rootbuild.gradle.kts, applied inapp/build.gradle.kts), and the Firebase BoM with Analytics, Credential Manager and googleid as dependencies. Firebase and googleid need Kotlin 2.3, which the rootbuild.gradle.ktsandbuildSrc/build.gradle.ktspin. -
MainActivity.ktgives the webview five bridges:TaskMintSplash: the launch screen stays until the app has drawn.TaskMintSystemBars: the status bar follows the app's theme. It also reports the navigation bar's and the keyboard's heights, which the webview doesn't pass to CSS, and callswindow.__taskmintInsetswhen they change.TaskMintGoogleSignIn: Credential Manager's Google sign-in, for cloud sync.TaskMintAnalytics: Firebase Analytics, and its off switch.TaskMintApp: back on Home sends the app to the background. The page takes over Android's back through Tauri'sonBackButtonPress. It also says whether Advanced Protection blocks installing an update, opens the phone's Security settings, and downloads and installs an update (AppUpdate.kt), reporting towindow.__taskmintUpdate.
app/proguard-rules.prokeeps the bridges, and Credential Manager's Play services provider, through R8. -
AndroidManifest.xmlkeeps the app in portrait (android:screenOrientation). -
The launch screen is androidx
core-splashscreen's, themed byTheme.taskmint.Starting(values/themes.xml, andvalues-v31for the wordmark, which Android 12 and later show): the leaf on the app icon's teal.MainActivitykeeps it up until the page callsTaskMintSplash.hide()(or 10 s pass), then fades it out. Its images,drawable-*/splash_icon.pngandsplash_branding.png, come fromassets/brand/mark.pngandlogo-dark.png. After changing those, make them again (macOS):
swift scripts/brand/android-splash.swift- The launcher icons in
app/src/main/res(mipmap-*, and the adaptive icon's background invalues/ic_launcher_background.xml) come fromassets/brand/icon-macos.png. Its padding keeps the clock and leaf inside the circle a launcher crops to, and the background is the tile's colour, so no edge shows. After changing the icon, make them again and copyandroid/overres:
cd apps/desktop && pnpm tauri icon ../../assets/brand/icon-macos.png --ios-color '#0A3A3E' -o /tmp/taskmint-icons && cp -R /tmp/taskmint-icons/android/. src-tauri/gen/android/app/src/main/res/Tauri writes its per-build files into the project (they're gitignored), so a
fresh checkout builds without an init. A Tauri upgrade can change the
template: tauri android init in a scratch copy shows what's new.
Run it in an emulator or on a phone plugged in over USB, or build a debug APK:
cd apps/desktop && pnpm tauri android devcd apps/desktop && pnpm tauri android build --debug --apk --target aarch64For a phone on the network, pnpm tauri android dev --host serves Vite on
this computer's network address (vite.config.ts reads TAURI_DEV_HOST;
tauri.android.conf.json lets live reload connect to it).
On Android the Rust side reports the runtime mobile (get_capabilities).
The app has its timers, data, dialogs and notifications (it asks for
permission to notify at the first launch), and cloud sync. Google sign-in
there needs Google Play services, and the build's signing certificate
registered on the Firebase Android app (Firebase console → Project settings
→ Your apps): the debug key's and the release key's SHA-1 are, in both
projects. A new key needs its own in each, and both google-services.*.json
downloaded again. The parts only a
desktop has are left out, in the Rust (#[cfg(desktop)], and those crates
are desktop-only dependencies) and in the webview (tauriBackend.ts,
extensions.tsx): the tray, idle detection (a phone sets the long-run
reminder as an alarm instead), folder backups, showing a file in the file
manager, the capture server and taskmint:// links for the browser
extension, installing updates (a phone downloads the new APK and hands it
to Android's installer instead), and
the move from the old identifier. Export and Import go through Android's file picker,
which returns a document (a content:// address) rather than a path:
tauri-plugin-fs, a mobile-only dependency, opens it (platform/os.rs), and
the export's message names no location.
To check the Rust compiles for Android without the Gradle build, point Cargo
at the NDK's compiler (the tauri android commands do this themselves):
TC=$NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin CC_aarch64_linux_android=$TC/aarch64-linux-android24-clang AR_aarch64_linux_android=$TC/llvm-ar cargo clippy -p taskmint --target aarch64-linux-android -- -D warningspnpm verify (scripts/verify.sh) runs every gate below in order; run it
before merging. It needs the prerequisites above, Java
included, and nothing else: no Docker, and no network once firebase-tools
and its Firestore emulator have been downloaded the first time.
pnpm lint # Biome: formatting and lint for the TypeScript and JavaScript
pnpm test:rules # the Firestore rules' tests, on the emulator (Java 21+)
pnpm build:wasm # the web app's core in WebAssembly (apps/web/src/wasm, not committed)
pnpm typecheck # tsc for sources and tests, every package (needs build:wasm first)
pnpm build # tsc for every package + the desktop and web vite builds
pnpm test # vitest in every package
pnpm test:coverage # vitest, held at 100% coverage
cargo test --workspace # Rust tests (bare `cargo` skips the desktop crate)
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all --check
cargo llvm-cov -p taskmint-core --fail-under-lines 100 --fail-under-functions 100 --fail-under-regions 100 # verify.sh adds the policy's ignore regex
node scripts/check-coverage-policy.mjs # see docs/coverage-policy.md
node scripts/check-toolchains.mjs # the wasm target and wasm-bindgen pins agree
pnpm test:scripts # the release script's logic (node --test)pnpm lint:fix applies Biome's formatting and safe fixes (biome.jsonc says
which rules are off and why). pnpm install points git at .githooks/,
whose pre-commit hook checks the staged TypeScript with Biome and the Rust
with cargo fmt --check. It only checks; git commit --no-verify skips it.
.git-blame-ignore-revs lists the formatting-only commits: GitHub skips
them, and git blame --ignore-revs-file .git-blame-ignore-revs does locally.
CI (.github/workflows/ci.yml) runs them on pushes to main and on pull
requests, on macOS. The Release workflow (.github/workflows/release.yml)
builds the release files and deploys the web app (see Releasing).
Each branch with a change users would notice adds a note in changes/
(changes/README.md). The notes say how big the change
is and what CHANGELOG.md says about it. In the main checkout,
on main:
pnpm release --dry-run # the next version and its CHANGELOG section; changes nothing
pnpm release # bump, CHANGELOG, commit "Release X.Y.Z", tag vX.Y.Z
pnpm release publish # push main and the tag; CI builds and publishes the releasepnpm release takes the highest bump among the notes. It writes that
version into every manifest (the desktop, web, client and contracts
package.jsons, the three crates and Cargo.lock; the extension keeps its
own), adds the CHANGELOG section, deletes the notes, then commits and tags.
It builds nothing: the Release workflow builds every installer from the
pushed tag. If the commit fails, the version files, CHANGELOG and notes are
put back. Nothing is pushed.
| Option | |
|---|---|
--patch, --minor, --major |
bump this level instead (needed when there are no notes) |
--publish |
then push main and the tag |
--rebuild |
only build the current version's installers into releases/, with no bump or commit: this computer's (TaskMint-X.Y.Z-macos-arm64.dmg on Apple silicon), or the --target and --windows ones |
--target <name> |
with --rebuild, build this instead of this computer's installer (repeat it for more): macos-arm64, macos-x64 (cross-compiled on Apple silicon), windows-x64, android-arm64 (on macOS or Linux, with the Android prerequisites and the release key, see Android signing), chrome-extension |
--windows |
with --rebuild, also build windows-x64 (on a Mac, cross-compiled with cargo-xwin) |
pnpm release publish pushes main and the current version's tag. The tag
starts the Release workflow, which builds every file a release ships on
GitHub's runners and then creates the GitHub release with the version's
CHANGELOG section (gh run list --workflow release.yml follows it):
| File | Built on |
|---|---|
TaskMint-X.Y.Z-macos-arm64.dmg |
macOS, Apple silicon |
TaskMint-X.Y.Z-macos-x64.dmg |
macOS, cross-compiled for Intel |
TaskMint-X.Y.Z-windows-x64-setup.exe |
Windows |
TaskMint-X.Y.Z-android-arm64.apk |
Linux, for arm64 Android phones (Android says how to install it) |
TaskMint-X.Y.Z-chrome-extension.zip |
Linux (apps/extension/README.md says how to install it) |
Each is the real app: release.mjs --rebuild builds with
TASKMINT_ENV=production and tauri.production.conf.json, then checks the
webview's dist/environment.json, the Mac app's identifier and the APK's
package (Dev environment).
Next to them are the desktop updates (see Desktop updates):
TaskMint-X.Y.Z-macos-{arm64,x64}.app.tar.gz and their .sig files,
TaskMint-X.Y.Z-windows-x64-setup.exe.sig, and latest.json.
The release is created only once all five are built, and a re-run replaces
the files of a release that already exists. The repository is public, so a
published release's files are public too. Running the workflow by hand
(Actions → Release → Run workflow), or a pull request that changes how
releases are built, builds the same files as workflow artifacts and
publishes nothing. The desktop builds report errors to Sentry when the
repository has a VITE_SENTRY_DSN secret (Settings → Secrets and variables
→ Actions); without it they report nothing. They sign in to cloud sync with
Google when it has VITE_GOOGLE_DESKTOP_CLIENT_ID and
VITE_GOOGLE_DESKTOP_CLIENT_SECRET (Firebase); without them,
by email only.
The web app. The workflow also builds the web app, and a tag deploys
it to Firebase Hosting (https://taskmint-f9a05.web.app) with the Firestore
rules and indexes, once every build has passed (deploy-web). The GitHub
release doesn't wait for the deploy, and a failed deploy can be re-run on
its own. The deploy signs in to Google through Workload Identity Federation,
so no key is stored: the repository variables GCP_WORKLOAD_IDENTITY_PROVIDER
and GCP_DEPLOY_SERVICE_ACCOUNT name the provider (pool github, provider
taskmint-releases, which trusts only this repository's v* tags) and the
github-deploy service account, which can deploy Hosting, the rules and the
indexes, and can't read or change anyone's data (Hosting Admin, Firebase
Rules Admin, Cloud Datastore Index Admin and Service Usage Consumer; no
viewer role, since Firebase Viewer reads Firestore and the user list). docs/runbook.md says how to
deploy by hand, or roll back.
The installers aren't signed (the Mac app is signed ad hoc). The first time a downloaded build is opened, macOS says it can't verify TaskMint: open System Settings → Privacy & Security and click Open Anyway. On Windows, SmartScreen says it protected the PC: click More info, then Run anyway.
A plain pnpm tauri build makes a dev build ("TaskMint Dev"); its installer
stays in target/release/bundle/.
The installed app updates itself from the latest GitHub release. A few
seconds after launch, and then once a day, it reads
https://github.com/BeardedUnicorn/taskmint/releases/latest/download/latest.json
(Settings → Updates checks now, or turns the automatic check off). When that
names a newer version, the app asks. On yes it downloads the update, checks
its signature, installs it and restarts. On macOS the update replaces the app
where it is. On Windows the installer runs in passive mode (a progress window
and no questions), then starts TaskMint again. The Rust side does all this
with tauri-plugin-updater (src/platform/os.rs, src/updates.rs), so the
webview needs no extra permission. A development build checks but won't
install.
Besides the new version's own notes, latest.json carries every release's
notes (changelog: the CHANGELOG's sections). An app several releases
behind shows what each release since its own brought, not only the newest.
Updates are signed with a minisign key:
- The public key is
plugins.updater.pubkeyinapps/desktop/src-tauri/tauri.conf.json. The private key and its password are the repository secretsTAURI_SIGNING_PRIVATE_KEYandTAURI_SIGNING_PRIVATE_KEY_PASSWORD. Only the Release workflow's build step sees them, and a tag's build stops at once if the key isn't set. - With the key in the environment, a build also makes the updates
(
src-tauri/tauri.updater.conf.jsonturns oncreateUpdaterArtifacts). The macOS update is made from theappbundle target, sobundle.targetsmust keepappnext todmg. The Tauri CLI refuses to sign with a public key it can't read, such as a placeholder.pnpm release --rebuildchecks each signature against the public key before the update goes intoreleases/, so a mismatched key can't ship. Without the key, as in a localpnpm release --rebuild, it builds the installer only. - The workflow's last step writes
latest.jsonfrom the signatures and the CHANGELOG section. requireSignedVersionis on. The bundler records the version in each signature, and the app installs an update only when that matches the versionlatest.jsonannounces. So an older signed build can't be passed off as a newer one.- Keep a copy of the private key and its password away from this computer (in a password manager, say). Without them, no later release can update the installed apps.
- A new key (lost or leaked): run
pnpm --filter @taskmint/desktop tauri signer generate -w ~/.tauri/taskmint-updater.key, replace both secrets andplugins.updater.pubkey, and release. Installed apps can't verify an update signed with the new key, so that one release has to be downloaded and installed by hand. Updates work again after that. - Releases before 2.3.0 have no updater, so 2.3.0 is installed by hand once.
Settings → Updates and its dialog come from apps/desktop/src/updates.ts,
UpdatePrompt.tsx and settings/UpdatesSection.tsx.
docs/qa/excluded-code-checklist.md
says how to try an update against a local feed.
Android installs an APK over the app only when both are signed with the same key, so every release's APK is signed with one release key:
- The key is a PKCS12 keystore with one key, alias
taskmint, whose password is the keystore's. The keystore (base64) and its password are the repository secretsANDROID_KEYSTOREandANDROID_KEYSTORE_PASSWORD. The Android build writes the keystore to the runner's temp folder, and only the build step sees the password. pnpm release --rebuild --target android-arm64refuses to build withoutTASKMINT_ANDROID_KEYSTORE(the keystore's path) andTASKMINT_ANDROID_KEYSTORE_PASSWORD. After the build it runsapksignerand checks that the APK's one signer has the certificate whose SHA-256 isANDROID_SIGNER_SHA256inscripts/release.mjs. So an APK that wouldn't install over the last one can't ship. A local build with the key:
TASKMINT_ANDROID_KEYSTORE=~/.android/taskmint-release.p12 TASKMINT_ANDROID_KEYSTORE_PASSWORD="$(cat ~/.android/taskmint-release.password)" pnpm release --rebuild --target android-arm64- Keep a copy of the keystore and its password away from this computer (in a password manager, say). Without them, no later APK installs over the app.
- A new key (lost or leaked): make one with
keytool -genkeypair -storetype PKCS12 -alias taskmint -keyalg RSA -keysize 4096 -validity 36500 -dname "CN=TaskMint" -keystore <file>, replace both secrets andANDROID_SIGNER_SHA256(keytool -list -v -keystore <file>shows the SHA256, without the colons), and release. Phones have to uninstall the app before installing that APK, which deletes its data: Settings → Data Management → Export first, and Import after (or sync it first, and sign in again after). Register the new key's SHA-1 on the Firebase Android app and commit the newgoogle-services.json, or Google sign-in stops working on the phone (Android).
The backend logs through tauri-plugin-log to stdout and to the app log dir
(~/Library/Logs/com.taskmint.desktop/ on macOS). Release builds log info and
above, dev builds include debug.
Cloud sync and the web app run on the Firebase project taskmint-f9a05,
on the free Spark plan with billing off. Every build that isn't a release
uses its twin, taskmint-dev (Dev environment). There's
no server of TaskMint's own: every client runs TaskMint's rules itself, and
Firestore holds the shared copy (ADR 0002).
| Part | What it's for |
|---|---|
| Authentication | Accounts: email and password, and Google. Anyone can sign up |
Firestore ((default), nam5) |
Each account's data: users/{uid} holds its epoch, users/{uid}/data/{kind~key} one session, work-log entry, project mapping or record each, and users/{uid}/published/payoutForecast the forecast for BudgetMint |
| Hosting | The web app, at https://taskmint-f9a05.web.app |
| Analytics | Page views from the web app and the Android app (Error reporting and analytics) |
Each client has its own Firebase app registration and config, in each
project: the desktop's web config in apps/desktop/src/firebaseConfig.ts,
the web app's in apps/web/src/firebaseConfig.ts, and Android's
google-services.*.json.
They're public by design: the API key only names the project, and the rules
decide what a signed-in user can reach.
The rules (firebase/firestore.rules) let a signed-in user read and
write only under their own users/{uid}. A data document must have exactly
the sync fields, with a known kind, an updatedAt of the server's time, and
the account's current epoch, so a device that missed a Delete cloud data
can't write its old copy back. firebase/firestore.rules.test.mjs tests
them on the emulator (pnpm test:rules), and firestore.indexes.json keeps
the json and hash fields out of the indexes.
Hosting (firebase.json) serves apps/web/dist with a content security
policy (script-src 'self' 'wasm-unsafe-eval', plus Google's sign-in and
Analytics hosts), nosniff, a referrer policy, COOP (same-origin-allow-popups,
for Google's popup), CORP, X-Frame-Options and a permissions policy. Every
path the app doesn't have serves index.html. The hashed files in /assets
are cached for a year; everything else is revalidated. Before a deploy,
scripts/check-web-environment.mjs checks apps/web/dist was built for the
project it's going to.
pnpm firebase runs firebase-tools at the version package.json pins
(through npx, outside the workspace). Deploys normally come from the
release workflow (Releasing); docs/runbook.md
has deploying by hand and rolling back.
TASKMINT_ENV says which TaskMint a build is: production for a release,
dev (also when it's unset) for every other build. Vite, Cargo and Gradle
all read it (scripts/environment.mjs), so
pnpm tauri dev, a plain pnpm tauri build, an Android build and the web
dev server are all dev builds. Only the release workflow
(Releasing) sets production. Any other value stops the
build.
| Production (releases) | Dev (every other build) | |
|---|---|---|
| Firebase project | taskmint-f9a05 |
taskmint-dev |
| Web app | https://taskmint-f9a05.web.app | https://taskmint-dev.web.app |
| Desktop app | TaskMint, com.taskmint.desktop |
TaskMint Dev, com.taskmint.desktop.dev |
| Desktop links and capture port | taskmint://, 43117 |
taskmint-dev://, 43127 |
| Desktop updates | from the latest GitHub release | none |
| Android app | TaskMint, com.taskmint.android |
TaskMint Dev, com.taskmint.android.dev |
| Analytics | on, with the off switch | none |
Sentry environment |
production |
dev |
A dev build is a separate app: its own data folder, webview storage (the
settings and the Firebase sign-in), single-instance lock and link scheme, so
it runs beside the installed TaskMint and never touches its data. Its
capture server listens on its own port, so the browser extension's captures
always go to the real app. It doesn't take over a pre-2.1 com.taskmint.app
folder. tauri.conf.json is the dev build, and tauri.production.conf.json
makes a build the real app. A build whose identifier and environment don't
match refuses to start (src-tauri/src/environment.rs).
Building production yourself: both halves, or it won't start.
cd apps/desktop && TASKMINT_ENV=production pnpm tauri build --config src-tauri/tauri.production.conf.jsonThe dev project mirrors production: email and Google sign-in (the dev
project safelists the desktop's Google client, so the same .env works),
email enumeration protection, Firestore in nam5 with the same rules and
indexes, and Hosting. It has no Analytics. Sign up there with any account.
.firebaserc makes it the default project, so a bare pnpm firebase command
works on dev; production needs --project taskmint-f9a05 (or production).
Deploy the web app, rules and indexes to dev (it runs the rules' tests first):
pnpm deploy:devThe Auth and Firestore emulators (firebase.json: 9099 and 8085) need Java
21 or later. A development build talks to them when
VITE_FIREBASE_EMULATOR_HOST is set; installed builds ignore it. They run as
the dev project, the default in .firebaserc.
pnpm firebase emulators:start --only auth,firestoreVITE_FIREBASE_EMULATOR_HOST=127.0.0.1 pnpm --filter @taskmint/web dev # http://localhost:1421TASKMINT_DATA_DIR=$HOME/tmp/taskmint-dev VITE_FIREBASE_EMULATOR_HOST=127.0.0.1 pnpm tauri devFrom the Android emulator the host is 10.0.2.2. Android 17 keeps an app
off the local network, that address included, until it's allowed: there,
forward the two ports (adb reverse tcp:9099 tcp:9099, adb reverse tcp:8085 tcp:8085) and use 127.0.0.1. Accounts made there exist only in the
emulator, and its data is gone when it stops.
To check the production headers, build the web app and serve it from the Hosting emulator (port 5002). That build talks to the dev project:
pnpm build:wasm && pnpm --filter @taskmint/web build && pnpm firebase emulators:start --only hosting- Web app: Firebase's Google provider (Authentication → Sign-in method),
in a popup. Its OAuth client was made by Firebase. The popup works only on
the authorized domains (Authentication → Settings): the Hosting domains
and
localhost. - Desktop: the system browser, then back to a loopback address the app
listens on (
src-tauri/src/google_sign_in.rs, with PKCE), which answers with a page in TaskMint's look (google_sign_in.html) and brings the app forward, withtaskmint://open(taskmint-dev://openfrom a dev build) for when the browser keeps the focus. It's Google's "Desktop app" OAuth client in Google Cloud console → APIs & Services → Credentials, intaskmint-f9a05; the dev project accepts it too (Authentication → Google → Safelist client IDs from external projects). Its id and secret go in.envasVITE_GOOGLE_DESKTOP_CLIENT_IDandVITE_GOOGLE_DESKTOP_CLIENT_SECRET, and in the repository secrets of the same names. Google treats an installed app's secret as public, but keep it out of the repository anyway. Without them the button is hidden. - Android: Credential Manager, with the web client's id from the
build's
google-services.*.json(Android says which certificates must be registered).
apps/web (@taskmint/web) is TaskMint in a browser, at
https://taskmint-f9a05.web.app: the same app as the desktop's
(packages/client), on TaskMint's own rules compiled to WebAssembly
(crates/taskmint-wasm), with the account's data from Firestore.
- Signing in comes first: an email and password, a new account, a reset link, or Google. The app's code loads only after that, and opens once the account's data has been read.
- Settings → Account: the email you're signed in with, sign out, change password (by an emailed link), and delete the account with its cloud data. Reset All Data deletes the cloud data and keeps the account.
- Live across tabs and devices: changes from your other devices and tabs show up as they're made. Each tab is a device of its own to sync.
- Offline: the app needs the network to open. Once open, it keeps working, and Firestore keeps the changes in the browser until it's back online (if the tab is closed first, they go the next time the app opens there).
- What only the desktop app has: idle detection and the long-run reminder, automatic backups into a folder, the system tray, and the localhost capture server. Their settings are hidden. Exports are downloads, and imports use the browser's file picker. ⌘N and ⌘, belong to the browser, so the command palette (⌘K) offers both instead.
Develop it against the dev project (pnpm --filter @taskmint/web dev) or
the emulators (Firebase).
pnpm build:wasm must run first, and again after a change to
crates/taskmint-core.
A pnpm workspace and a Cargo workspace share the repo root. How the code came to be shared by every app is docs/adr/0001-web-support.md; how sync and the web app work, docs/adr/0002-firebase.md.
packages/client/ React app (@taskmint/client)
src/components/pages/ One folder/file per page (payouts/, settings/, tasks/)
src/contexts/ App-wide providers: sessions, tasks, work logs, backups, …
src/hooks/ Data hooks (useSessionManagement, useWorkLogs, useDataBackup, …)
src/services/ Tasks, notes, templates (appRecords.ts: the appdata.json cache)
src/cloud/ Cloud sync: the engine, and Firebase behind the CloudStore seam
src/utils/ Pure logic: time math, payouts, work-log import, Sentry, analytics
src/types/ Shared types and zod schemas
public/ Favicon, wordmark and app icon
packages/contracts/ Wire types, CommandMap and constants (@taskmint/contracts),
generated from taskmint-core: don't edit src/generated
crates/taskmint-core/ Business rules shared by every host: sessions, timers, work-log
import, restore, idle, sync, the wire contract (pure: no I/O, no clock)
src/sync/ Cloud sync's rules: what to send, applying the cloud's, merges
crates/taskmint-wasm/ taskmint-core in WebAssembly, for the web app (pnpm build:wasm)
apps/desktop/ Desktop app (@taskmint/desktop): Vite entry + Tauri shell
src/tauriBackend.ts The client's Backend: every call goes through dispatch
src-tauri/src/dispatch.rs The one IPC command: shell commands here, data commands to the backend
src-tauri/src/backend/ LocalBackend: one lock, run taskmint-core on a copy, save, then swap
src-tauri/src/store/ sessions.json / worklogs.json / appdata.json / sync.json and the .bak copies
src-tauri/src/files.rs Save/open dialogs, the backup folder, showing a file in Finder
src-tauri/src/capture_server.rs localhost capture server and taskmint:// deep links
src-tauri/src/google_sign_in.rs Google sign-in for cloud sync: the browser and a loopback address
src-tauri/src/google_sign_in.html The page the browser comes back to, in TaskMint's look
src-tauri/src/tray/ System tray
src-tauri/src/legacy_identifier.rs Moves the data left under the pre-2.1 identifier
src-tauri/src/config.rs Constants
src-tauri/capabilities/ Frontend permission grants
src-tauri/gen/android/ The Android project (see Android)
apps/web/ Web app (@taskmint/web): sign-in page, then the client on the wasm core
src/wasmBackend.ts The client's Backend: taskmint-core in WebAssembly
src/settings/ The Account section
src/wasm/ pnpm build:wasm's output (not committed)
apps/extension/ Work-log capture extension (MV3, TypeScript; built into dist/)
apps/functions/ The Cloud Function that tells phones their published widgets changed (built into dist/)
firebase/ Firestore rules, their tests, and indexes (firebase.json deploys them)
assets/brand/ Logo and app-icon masters (see Development)
docs/ ADRs, the coverage policy, the security review, the runbook
qa/ The manual checklist for the code coverage leaves out
After changing a wire type, a command, or a constant in
crates/taskmint-core/src/contract.rs, regenerate the TypeScript and commit
it with the Rust (scripts/verify.sh fails while they differ):
cargo test -p taskmint-core --features ts --test contracts