Singularity Todo

Kotlin Multiplatform task manager with AI assistance. Targets Android and JVM Desktop (no iOS).

Stack: Compose Multiplatform · Room · Koin · Kermit · Supabase · Koog AI framework

CI: ci.yml on main

---

Features

---

Licensing

This is an open-core project. The split is real, not aspirational, and it is verified by a gate on every commit.

A default build contains no pro code at all. settings.gradle.kts includes :pro only when the build is run with -PwithPro=true, so:

./gradlew :androidApp:assembleDebug                      # Apache-2.0 only
./gradlew :androidApp:assembleDebug -PwithPro=true      # includes pro/

scripts/check-pro-licence-boundary.py enforces the direction of the dependency (no Apache-2.0 file imports com.singularity.todo.pro), the absence of non-OSI vendor dependencies from the free build, and that the free artifact really is free — --verify-apk inspects a built APK at the dex level. A licence split asserted only in a document is a claim the project cannot honour.

Under FSL-1.1-ALv2 the pro/ modules convert to Apache-2.0 two years after they are last used commercially.

Provenance

Some code here is derived from other projects, and saying so is part of the release rather than an apology for it. The task query language under feature/search/query/ derives from Orgzly (GPL-3.0) and was rewritten against a written specification — see docs/specs/search-query-grammar.md. No GPL or source-available code is vendored.

Every non-original file is classified in docs/legal/PROVENANCE.md, machine-readably in config/legal/provenance-registry.tsv, and attested in NOTICE. PORTED — the one class that would have blocked publication — is empty. No plagiarism detection was run, and most unmarked .kt files are classified ORIGINAL by absence of markers rather than by inspection; both limits are stated in the provenance document.

---

Quickstart

Build

# Android
./gradlew :androidApp:assembleDebug

# Desktop
./gradlew :desktopApp:run

# Run tests
./gradlew :shared:jvmTest
./gradlew :shared:testAndroidHostTest

# Full check (tests + lint + assemble)
./check.sh

Working in parallel worktrees

Use ./gw instead of ./gradlew when more than one checkout builds at the same time:

./gw :shared:jvmTest
./gw koverReport

It points GRADLE_USER_HOME at a private directory inside the worktree, so each checkout owns its daemon registry and ./gradlew --stop can no longer kill a neighbour’s build. The Gradle distribution, dependency caches and toolchain JDK stay shared through symlinks — nothing is re-downloaded. direnv users get the same thing from the committed .envrc.

One command when you create a worktree:

git worktree add ../my-worktree -b my-branch
./scripts/setup-worktree.sh   # run inside ../my-worktree

It also points core.hooksPath at that worktree’s own .githooks. A single absolute value in the shared config otherwise makes every worktree run the hooks of one checkout — silently, and in the wrong directory.

Never run ./gradlew --stop in a shared home; if a daemon must go, stop it through ./gw --stop. See docs/decisions/2026-10-04-gradle-daemon-isolation.md.

Dogfooding with AI agent

# Build MCP server
./gradlew :mcp-server:build

# Connect ZCode / Claude Code / Cursor to:
java -jar mcp-server/build/libs/mcp-server-jvm-*.jar --profile=ai-agent

See AGENTS.md for the full agent cheatsheet (architecture, DI patterns, test strategy, CLI).

---

Architecture

• shared/ — all shared code (commonMain + androidMain + jvmMain + tests)
  • core/ — infrastructure: database, auth, backup, sync, DI, notifications, security
  • feature/ — UI features: tasks, notes, projects, tags, search, AI, settings, agenda, calendar
• androidApp/ — Android shell (MainActivity, manifest)
• desktopApp/ — Desktop Compose entry
• mcp-server/ — AI agent MCP server (Koog → MCP adapter)

See ARCHITECTURE.md for the full design doc (package maps, expect/actual table, layer boundaries, refactoring playbook).

---

Documentation

Run just docs-audit to check doc freshness, normalize ADRs, and regenerate DIGEST.

---

Tech choices

Learn more about Kotlin Multiplatform.