# Project pack: Super Productivity @ 78139c5

Facts about **Super Productivity** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v1.md). This pack is pinned to one version and never changes after publication.

> Super Productivity is a to-do list and day planner for deep work. Plan your day, track time on tasks, use focus sessions and breaks, and pull in tasks from tools like GitHub, Jira or calendars. It works in the browser, on desktop and on mobile, with no account, no tracking, and data that stays on your device unless you choose to sync.

## Version and source
- Repository: https://github.com/johannesjo/super-productivity
- Pinned commit: `78139c531c808bab7c46ef96fd0fbb0a3b6f7d6d`. Use exactly this version.
- Get it: `git clone https://github.com/johannesjo/super-productivity super-productivity && cd super-productivity && git checkout 78139c531c808bab7c46ef96fd0fbb0a3b6f7d6d`
- Or download a zip: https://github.com/johannesjo/super-productivity/archive/78139c531c808bab7c46ef96fd0fbb0a3b6f7d6d.zip
- Official docs: https://github.com/super-productivity/super-productivity/wiki
- Live demo: https://app.super-productivity.com. The full web app. Data is stored in your browser only.
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Running it
- Easiest: Easiest: open https://app.super-productivity.com in your browser. Self-host: docker run -d -p 8080:80 johannesjo/super-productivity:latest # then open http://localhost:8080
- Needs: Nothing for the web app; Node 22 + npm for development
- Develop: `npm install && npm run startFrontend   # web dev server on http://localhost:4200`
- Test: `npm run test:affected`
- Check/lint: `npm run checkFile <changed files>`
- Stack: typescript, scss (Angular, NgRx, Angular Material, Electron, Capacitor). Difficulty for a non-developer with an AI: **advanced**. A large Angular app with sync logic, so core code changes are for agent-mode AIs only. But plugins (plain JavaScript, no build) and CSS themes make many adaptations easy without touching the core.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `CLAUDE.md`, `ARCHITECTURE-DECISIONS.md`, `docs/repository-map.md`, `packages/plugin-dev/QUICK_START.md`.

## Customisation points (settings → extend → code)
- **settings** [settings]: Most behaviour is configurable in the app. → `Settings (focus mode, Pomodoro timings, breaks, reminders, keyboard shortcuts, language)`
- **themes** [extend]: Choose or write a CSS theme (e.g. calm pastel, high contrast). → `Settings → Theme; built-in themes in src/assets/themes/*.css (wiki 3.09 Theming)`
- **plugins-js** [extend]: Plain-JavaScript plugins with manifest.json + plugin.js and no build step. They can add buttons, panels, automations and prompts. → `packages/plugin-dev/yesterday-tasks-plugin (copy it), upload a .zip via Settings → Plugins`
- **plugins-ts** [extend]: Richer plugins with TypeScript or SolidJS UI, built with npm run build. → `packages/plugin-dev/* (e.g. automations, brain-dump, voice-reminder, todoist-import), API in packages/plugin-api`
- **core-code** [code]: Changes to the core app. Agent mode only; follow AGENTS.md strictly. → `src/app/features/** (see docs/repository-map.md)`

## Must keep working
- User data and sync. Never change persisted models or the op-log without following AGENTS.md and the sync docs.
- Offline use and privacy (no analytics, no tracking, no network calls without user consent).
- Never add packages to the root dependencies. A plugin may bundle its own.

## Staying updatable
Strongly prefer themes and plugins. They install into the official app (including the web app), so the user keeps automatic updates with no fork at all.

## Data, costs and safety
- Personal data: **yes**. Stored in: In the browser (IndexedDB) or the desktop app's local storage; optional sync to a provider you choose. Export a backup (Settings → Sync & Backup → Import/Export) before trying plugins or code changes.
- Service: Sync (WebDAV, Dropbox, local file, or SuperSync) (optional, free (self-hosted WebDAV) or provider pricing): Keep tasks in sync across devices.
- Service: Integrations (GitHub, Jira, GitLab, CalDAV, Google Calendar…) (optional, free): Import tasks and events from other tools.
- Plugins run inside your app with access to your tasks. Only install plugins whose code you (or your AI) have read.

---

# Customising Super Productivity

Super Productivity's core is a large Angular app with sync logic. **Don't fork the core for personal tweaks.** Use the plugin and theme system instead. Plugins install into the official web, desktop or mobile app, so the user keeps receiving updates.

## Level 1: Settings (no code)
Focus mode, Pomodoro and break timings, reminders, idle tracking, keyboard shortcuts, language, projects, tags and boards. Show the user where these live before writing anything.

## Level 2: Extend (recommended for most adaptations)

### Themes
- Built-in themes live in `src/assets/themes/*.css`. Copy one (e.g. `everforest.css`) as a starting point.
- See the wiki page "3.09 Theming": https://github.com/super-productivity/super-productivity/wiki/3.09-Theming

### Plugins
Read `packages/plugin-dev/QUICK_START.md` and `packages/plugin-dev/README.md`. Three options:
1. **Plain JavaScript, no build:**
   - Copy `packages/plugin-dev/yesterday-tasks-plugin`.
   - Edit `manifest.json` (unique `id` and `name`) and `plugin.js`, plus an optional `index.html` UI.
   - Zip the files and upload them in **Settings → Plugins**.
   - **Best for non-developers.**
2. **TypeScript:** copy `github-issue-provider`, then `npm install && npm run build` → `dist/` → zip and upload.
3. **SolidJS UI** for complex panels: start from `boilerplate-solid-js`.

The API surface is in `packages/plugin-api/`. Look at similar bundled plugins for patterns:
- `automations`: rules and triggers
- `brain-dump`: quick capture
- `voice-reminder`
- `procrastination-buster`
- `ai-productivity-prompts`
- `todoist-import`

## Level 3: Core code (agent mode only)
Follow upstream `AGENTS.md` exactly:
- Run `npm run checkFile <files>` on every changed `.ts`/`.scss` file.
- Run `npm run test:affected`.
- Edit only `en.json` for text.
- Add no root dependencies.
- Never mutate NgRx state.
- Read the sync docs before touching persisted models.

## Running locally
- **No setup:** https://app.super-productivity.com (the user can install their plugin zip there).
- **Self-host:** `docker run -d -p 8080:80 johannesjo/super-productivity:latest`
- **Develop:** `npm install && npm run startFrontend`, then open http://localhost:4200.

## Pitfalls
- Plugins see the user's tasks. Keep plugins local, request no network access unless the user asks for it, and explain any data that leaves the device.
- Ask the user to export a backup (Settings → Sync & Backup → Import/Export) before installing new plugins.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/super-productivity/78139c5/bespoke.yaml) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/super-productivity/78139c5/SKILL.md)