taskboard

A small, local-first task manager for macOS, with an optional installable iPhone web app.

taskboard is designed for fast capture and a quiet workflow: create boards, move tasks between Todo, Running, and Done, and hand any task to a coding agent in T3 Code with one click. taskboard tracks the T3 thread and moves the task to Done once you settle it. The Mac app works entirely offline. Firebase sync is optional and only needed if you want the iPhone PWA and Mac app to share data.

Watch the full-quality video

Features

• Native SwiftUI macOS app with light, dark, and system appearance
• Multiple boards with local JSON persistence
• A Today view that selects and ranks tasks while preserving their project boards
• Optional task deadlines with due-today and overdue cues for you and your agent
• Optional scoped read/write access for a remote planning agent
• Todo, Running, and Done lanes with drag and drop
• Menu bar companion for open tasks
• Global Quick Capture window with a configurable shortcut
• Boards linked to T3 Code projects
• One-click sends to T3 Code using your favourite models
• Background monitoring that moves tasks to Done when their T3 thread is settled
• Optional Firebase Realtime Database sync with an installable iPhone PWA
• Offline storage on both Mac and iPhone

Choose your setup

What you want	What you need
Mac app only	macOS 15 and Swift 6.2/Xcode 16 or newer
Mac app + iPhone sync	The Mac requirements, Node.js 22, and a free Firebase project
PWA development only	Node.js 22 and a free Firebase project

The Mac app has no third-party Swift package dependencies. An Apple Developer account is not required for local builds or for installing the PWA.

Quick start: macOS

Clone the repository and run the app directly:

git clone https://github.com/WittorioJaro/taskboard.git
cd taskboard
swift run taskboard

You can also open Package.swift in Xcode, select the taskboard scheme, and press Run.

Build an app for Applications

On an Apple silicon Mac, run:

./scripts/build-app.sh

The script creates an ad-hoc signed app at dist/taskboard.app. Install or replace it with:

rm -rf /Applications/taskboard.app
ditto dist/taskboard.app /Applications/taskboard.app
open /Applications/taskboard.app

The included logo is converted to a macOS .icns file automatically. For distribution with your own Developer ID, provide a signing identity:

TASKBOARD_SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)" \
  ./scripts/build-app.sh

The script signs the build but does not notarize it.

Optional: iPhone PWA and sync

The PWA is the supported iPhone client. It runs in Safari, can be added to the Home Screen, and syncs through your own Firebase project.

1. Create the Firebase backend

1. Create a Firebase project on the free Spark plan. Do not attach a billing account.
2. In Build → Authentication → Sign-in method, enable Email/Password.
3. In Build → Realtime Database, create a database in locked mode.
4. Open the database Rules tab, paste web/firebase/database.rules.json, and publish it.
5. In Project settings → Your apps, add a Web app and copy its Firebase configuration.

The rules allow an authenticated user to access taskboardSnapshots/{their uid}, with optional explicit grants for a separate agent account. See agent access and Today planning. Firebase Web configuration is visible to browser clients, but project-specific values must not be committed to this repository. Never provide an Admin SDK service-account key.

2. Run the PWA locally

cd web
npm install
npm run dev

Vite prints a local development URL. For on-device PWA testing, use an HTTPS deployment or HTTPS development tunnel; service workers and installation require a secure context.

Firebase configuration can be entered in the PWA's connection screen. For development or deployment, copy web/.env.example to web/.env.local and fill in:

VITE_FIREBASE_API_KEY="..."
VITE_FIREBASE_AUTH_DOMAIN="your-project.firebaseapp.com"
VITE_FIREBASE_DATABASE_URL="https://your-project-default-rtdb.europe-west1.firebasedatabase.app"
VITE_FIREBASE_PROJECT_ID="your-project"
VITE_FIREBASE_APP_ID="..."

These values will be present in the browser bundle. Keep .env.local untracked and configure the same variables in the deployment provider rather than committing them. Security comes from Firebase Authentication and the included Realtime Database rules.

3. Deploy the PWA

The repository includes web/vercel.json, so Vercel can build the PWA without additional routing configuration:

cd web
npx vercel --prod

Alternatively, run npm run build and deploy the generated web/dist directory to any HTTPS static host with SPA fallback routing.

Before deploying with Vercel, add the five VITE_FIREBASE_* variables from web/.env.example to the project’s Production environment. Do not commit their values.

On iPhone, open the deployed URL in Safari, tap Share, choose Add to Home Screen, and launch taskboard from the new icon.

4. Connect both clients

1. Export a JSON backup from the PWA connection panel before changing providers.
2. In the Mac app, open Settings → Sync.
3. Enter the Realtime Database URL, Web API key, email, and password.
4. Select Create Account, then restart taskboard so its local snapshot seeds Firebase.
5. In the PWA, open the Offline connection panel, enter the Firebase web configuration, and sign in with the same account.

Both clients keep a local copy and remain usable while offline. When the Firebase account is empty, the first Mac connection seeds it with the Mac's current snapshot. Verify edits in both directions before disconnecting the legacy Supabase sync.

For the full migration and rollback sequence, see docs/firebase-migration.md.

Today and remote agents

Use the sun button on a project task to include it in Today. The task stays in its original board, and Today shows its project label. T3 sends still use that project. Drag open Todo tasks within the Mac Today view to prioritize them. Existing tasks captured directly in Today stay as personal tasks; dated project selections expire after the selected day, leaving unfinished tasks in their project backlog.

Click Set deadline on a task to add an optional calendar date. Deadlines stay with the original task and appear in agent data, so the agent can account for overdue and upcoming work when planning Today.

An agent can create tasks and submit an ordered daily selection using scripts/taskboard-agent.py. See agent access and Today planning for scoped Firebase grants, commands, a suggested agent instruction, and the local Kindle dashboard integration. Recurring planning runs in the agent's own scheduler; that guide also covers deploying the phone app.

Kindle dashboard (how I set mine up)

Not a recommendation. This is a write-up of what I did on my own device, not an endorsement of jailbreaking. Jailbreaking a Kindle is unofficial, may go against Amazon's terms, can void your warranty, and can brick the device if a step goes wrong. Do it only if you understand and accept that, and follow the community guides linked below rather than this summary. taskboard works fully without any of it.

My Today list sits on an e-ink Kindle next to my desk. Tapping a task there ticks it off in taskboard, and the change syncs to the Mac and phone.

Device. Kindle Paperwhite 4 (10th gen, 1072 × 1448), firmware 5.18.1.

What runs on the Kindle

1. Jailbreak: SpiderCat, which supports this model and firmware. Check your exact model and firmware against its supported list first.
2. Block automatic updates so a firmware update doesn't undo the jailbreak (guide).
3. Hotfix and KPM, the community package manager (installing homebrew).
4. KOReader, installed through KPM (guide).
5. A small custom KOReader plugin that shows a full-screen image fetched from the Mac, refreshes it every few minutes and on wake, and sends taps back. A top-right button returns to the normal Kindle interface.

What runs on the Mac

• A local Python (Flask + Pillow) server that renders the Today list as a 1072 × 1448 grayscale PNG and accepts taps. It listens only on the home network, behind long random link tokens.
• integrations/kindle/taskboard_today.py, which reads the Mac app's local boards.json and ticks tasks in their home board. It uses the same file lock as the app, so edits don't collide. scripts/install-kindle-integration.py wires it into an existing dashboard server.

The Kindle never talks to Firebase. Changes go Kindle → Mac file → Firebase, and the other way back, so the Mac has to be awake and running taskboard. The dashboard server and KOReader plugin are specific to my setup and aren't in this repository yet; see agent access and Today planning for the data contract they use.

T3 Code integration

taskboard can hand tasks to coding agents running in T3 Code on the same Mac.

1. Link a board to a project. Use the t3 button in the board header to pick a T3 Code project. A project whose folder matches the board's folder is suggested first. New boards can be linked when they are created.
2. Send a task. Click the t3 icon on a task and choose a model. The list comes from the favourites you starred in T3 Code; press 1–9 to pick by number. taskboard starts a new thread in the linked project with the task text and any image attachments, and moves the task to Running.
3. Follow it. The task's icon shows whether the thread is running, needs input, or is ready for review. Click it to see the status or open the thread in T3 Code.
4. Finish it. When you settle the thread in T3 Code, a background check (every 10 seconds) notices and moves the task to Done. Monitoring continues after taskboard restarts.

In Quick Capture, pressing Return adds the task and sends it straight to T3 Code with your last-used model, provided the board is linked.

How it connects:

• taskboard finds the running T3 Code server through ~/.t3/userdata/server-runtime.json and talks to its local MCP endpoint.
• The first time, it signs itself in using a one-time pairing code from the t3 CLI. No browser step is required. The resulting token is stored at ~/Library/Application Support/taskboard/t3-mcp-token, readable only by your user, and is renewed automatically when it expires or is revoked.
• Threads are started in full-access mode, so agents can work without stopping for approval prompts. Treat sending a task like typing it into T3 Code yourself.

The integration needs T3 Code running locally. Task management itself does not depend on T3 Code.

Data and privacy

Without sync, task data never needs to leave the Mac. The native app stores its board snapshot at:

~/Library/Application Support/taskboard/boards.json

The PWA caches data in browser storage. When Firebase sync is enabled, each authenticated user can access their own snapshot; a separate agent can also access it when explicitly granted through the Realtime Database rules. The Mac stores its refresh token in Keychain; project configuration remains local to each client.

Before experimenting with sync or schema changes, exporting a PWA JSON backup is recommended.

Development

Mac app

swift test
swift run taskboard

The T3 Code tests use stubs and fixtures, so they do not need T3 Code to be running.

Web app

cd web
npm install
npm run build
npm run test:sync
npm run preview

Project structure

Sources/taskboard/
  TaskBoardApp.swift          App entry point, windows, and appearance
  MainWindowView.swift        Main board interface and drag and drop
  MenuBarCompanionView.swift  Menu bar interface
  QuickCaptureSupport.swift   Global shortcut and Quick Capture window
  SettingsView.swift          Appearance, sync, and app preferences
  TaskBoardStore.swift        State, task operations, and persistence
  Models.swift                Board, task, attachment, and theme models
  T3CodeClient.swift          T3 Code MCP client, sign-in, and favourites
  T3RunMonitor.swift          Background monitoring of launched T3 threads
  T3SendPopover.swift         t3 button, model picker, and project linking
  FirebaseSyncService.swift   Preferred Mac authentication and snapshot sync
  SupabaseSyncService.swift   Legacy rollback sync
web/
  src/                        React PWA and realtime sync client
  public/                     Manifest, icons, and service worker
  firebase/database.rules.json Database security rules
scripts/
  build-app.sh                Release app bundle and signing script
iOS/                          Experimental legacy native iPhone source
taskboard-ios.xcodeproj/      Experimental legacy CloudKit project

The legacy native iPhone target remains for experimentation, but device builds using CloudKit require Apple signing. The PWA is the recommended no-fee iPhone installation path.

Troubleshooting

The Mac app will not open

The locally built bundle is ad-hoc signed rather than notarized. If macOS blocks it, Control-click the app, choose Open, and confirm once.

The PWA stays offline

• Confirm that all five Web app configuration fields belong to the same Firebase project.
• Confirm that Email/Password authentication is enabled.
• Confirm that web/firebase/database.rules.json is published.
• Do not use an Admin SDK service-account key.

Realtime changes do not arrive

Confirm that the Realtime Database URL is exact, including its region, and that the database rules are published.

Contributing

Issues and pull requests are welcome. For changes, please include:

• A concise explanation of the behavior being changed
• The platforms you tested
• swift test results for Mac changes
• npm run build and npm run test:sync results for PWA changes
• Screenshots or a short recording for visible UI changes

Please keep credentials, local task data, build products, and signing identities out of commits.

License

taskboard is available under the MIT License.