Ko-Do List

A fast, local-first task manager with a focused interface and optional GitHub-powered device sync. Built as an open-source fan project by codykoinabox.

Ko-Do works instantly without an account. Signed-out data stays in the browser; signing in with GitHub adds encrypted transport and per-user Supabase storage while preserving the local-first experience.

Features

• Fast task capture plus a detailed task editor
• Inbox, Today, Upcoming, All tasks, and Completed views
• Due dates with quick scheduling shortcuts
• High, medium, low, and unprioritized tasks
• Custom color-coded tags
• Search, priority filtering, and four sort modes
• Pointer, touch, and keyboard-friendly manual reordering
• Undoable task deletion
• Light, dark, and system themes
• JSON backup and restore
• Cross-tab local-storage updates
• Optional GitHub sign-in and automatic cross-device sync
• Offline edits, deletion tombstones, stale-write protection, and realtime refresh
• Account-scoped browser caches to keep users separate on shared devices
• Responsive desktop, tablet, and mobile layouts
• Keyboard shortcuts: N to add, / to search, and T to toggle theme
• Accessible controls, focus states, and reduced-motion support

When signed out, no task data is sent to a server. When signed in, tasks and tags are synchronized to the configured Supabase project and protected by per-user Row Level Security.

Run locally

Requires Node.js 24 and npm.

npm install
npm run dev

Open the local URL printed by Vite.

The app remains local-only when Supabase variables are absent. To enable GitHub sign-in and synchronization, follow the sync setup guide.

Quality checks

npm run check

This runs ESLint, the Vitest suite, TypeScript, and the production build. The built site is written to dist/.

Deploy to GitHub Pages

The repository includes .github/workflows/deploy-pages.yml. It verifies and builds the app, uploads dist/, and deploys it through GitHub Pages whenever main is pushed. It can also be started manually from the Actions tab.

For the first deployment:

1. Open the repository on GitHub.
2. Go to Settings → Pages.
3. Set Source to GitHub Actions.
4. Push to main, or run the workflow manually.

Vite uses relative production asset paths, so the build works at both a user site and a repository subpath without hard-coding the repository name.

Cloud-enabled deployments also require the two public repository variables documented in the sync setup guide.

Stack

• React 19 + TypeScript
• Vite
• Radix UI primitives and shadcn-style owned components
• Supabase Auth, Postgres, Row Level Security, and Realtime
• dnd-kit for accessible drag-and-drop
• Lucide icons
• Vitest and Testing Library

Roadmap

• Shared lists without compromising the local-first default
• Optional end-to-end encrypted task payloads

Contributing

Issues and pull requests are welcome. Run npm run check before submitting changes.

License

MIT

Ko-Do List is an independent fan project and is not affiliated with or endorsed by Cody Ko.