Muse

Autonomous Task Scheduling Engine
A deterministic, constraint-satisfaction scheduling system that dynamically maps flexible tasks into rigid temporal availability windows — without requiring human intervention.

What is Muse?

Muse is an autonomous task scheduler inspired by FlowSavvy. Unlike static task managers or manual time-blocking tools, Muse runs a constraint-satisfaction algorithm that evaluates task duration, deadlines, priorities, dependencies, scheduling hour profiles, and event buffers to construct a mathematically optimized schedule — then automatically recalculates when reality deviates from the plan.

When a meeting runs over, a task gets skipped, or a deadline changes — hit Recalculate and the engine purges all future placements and regenerates an optimal schedule from the present moment forward.

Key Differentiators

Deterministic Algorithm — No LLMs, no hallucinations. A dedicated constraint-satisfaction solver evaluates thousands of permutations to map tasks into available time windows.
Autonomous Rescheduling — Missed a task? The engine automatically reschedules remaining work into future availability.
Priority Supersedes Deadline — When conflicts arise, high-priority tasks are preserved even if it means a low-priority task misses its deadline. The sacrificed task turns red.
Balanced vs Front-Load Distribution — Choose between evenly spreading work across days (prevents burnout) or greedily packing everything into the earliest slots (clears your queue fast).
Cross-Platform — Desktop (Electron), Web (PWA), and Mobile (responsive browser + Android WebView APK).
Cloud Sync — Optional email account (Firebase Auth) with live sync across devices (Firestore).

Screenshots

The interface uses the Nord color palette — a cold, arctic blue theme with both dark and light modes.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                       Electron Shell                        │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                   React + Vite SPA                   │   │
│  │  ┌──────────┐ ┌───────────┐ ┌────────────────────┐  │   │
│  │  │ Sidebar  │ │ Calendar  │ │  Floating Modals   │  │   │
│  │  │ (Lists,  │ │ (Day/3D/  │ │  (Task, Event,     │  │   │
│  │  │  Inbox,  │ │  Week)    │ │   Settings)        │  │   │
│  │  │  Missed) │ │           │ │                    │  │   │
│  │  └──────────┘ └───────────┘ └────────────────────┘  │   │
│  │                      │                               │   │
│  │               ┌──────┴──────┐                        │   │
│  │               │   Zustand   │                        │   │
│  │               │    Store    │                        │   │
│  │               └──────┬──────┘                        │   │
│  │          ┌───────────┼───────────┐                   │   │
│  │    ┌─────┴─────┐ ┌───┴───┐ ┌────┴─────┐             │   │
│  │    │ Scheduler │ │Repeat │ │  Depend  │             │   │
│  │    │  Engine   │ │ Gen   │ │  Graph   │             │   │
│  │    └───────────┘ └───────┘ └──────────┘             │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────┐  ┌────────────────────────┐   │
│  │  Cloud Sync (Supabase)   │  │  Persistence           │   │
│  │  Auth + PostgreSQL       │  │  localStorage+IndexedDB│   │
│  └──────────────────────────┘  └────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Tech Stack

Layer	Technology
Desktop Shell	Electron 32.3.3
Frontend	React 18 + TypeScript 5.6
Build Tool	Vite 5.4
State Management	Zustand 4.5
Styling	TailwindCSS 3.4 + Nord Theme
Persistence	localStorage + IndexedDB (dual-write)
Cloud Sync	Firebase Auth + Firestore (optional)
Icons	Lucide React
Date Handling	date-fns 3.6

Scheduling Engine — Deep Dive

The scheduling engine (src/engine/scheduler.ts) is a constraint-satisfaction solver that runs in 9 stages:

Pipeline

1. Compute Urgency Colors (Green/Orange/Red)
2. Handle Auto-Ignore (garbage-collect missed repeating tasks)
3. Filter schedulable tasks (autoSchedule, !completed, !inbox, remaining > 0)
4. Sort by scheduling priority
5. Build busy map (events + buffers + manually pinned tasks)
6. Build available slots per scheduling-hours profile
7. Clear all existing auto-scheduled blocks
8. Run constraint-satisfaction placement algorithm
9. Recalculate urgency colors after placement

Priority Sort Order

The engine sorts tasks for placement in this strict order:

Red urgency (overdue) — scheduled first, front-loaded aggressively
Orange urgency (danger zone) — front-loaded aggressively
Priority (High > Medium > Low > None) — priority supersedes deadline
Due date (earlier deadline first)
Remaining duration (shorter tasks first, for optimal bin-packing)

Workload Distribution Models

Model	Behavior
Balanced (default)	Calculates `remaining_duration ÷ days_until_deadline` and distributes work evenly across days. Per-task daily cap with 1.3x flexibility factor.
Front-Load	Greedy algorithm. Packs every task into the earliest available slot.

Both models force-front-load Red and Orange urgency tasks regardless of the global setting.

Task Splitting

Large tasks (e.g., a 10-hour research report) are unlikely to find contiguous 10-hour blocks. When splittable = true, the engine fractures the task into multiple blocks distributed across available gaps. The minBlockDuration field prevents hyper-fragmentation (e.g., no useless 5-minute blocks for deep-focus work).

Dependencies

Tasks can declare dependencies via dependsOn: string[]. The engine:

Computes the finish timestamp of all prerequisite tasks
Sets that as the effective startAfter for the dependent task
If a prerequisite is incomplete and unscheduled, the dependent task is blocked (not scheduled)
Circular dependency detection via DFS prevents infinite loops

Scheduling Hours (Temporal Masks)

Each task can be assigned to a Scheduling Hours Profile — a 168-hour weekly boolean grid defining when that type of work is allowed. Examples:

Deep Work: Mon–Wed 06:00–10:00
Admin: Fridays 13:00–16:00
Personal: Weekends all day

The engine intersects each task's duration exclusively with its assigned profile's available blocks, ignoring all other free time.

Event Buffers

Events support bufferBefore and bufferAfter (in minutes). These create impenetrable dead zones around events — the engine treats buffer time identically to busy blocks, protecting transit and decompression time.

Auto-Scheduling Cutoff

The engine stops scheduling beyond a configurable horizon (default: 8 weeks). Days beyond the cutoff display gray stripes in the UI. This prevents unbounded computation and keeps the algorithm fast.

Data Model

Events vs Tasks — Strict Ontological Separation

	Events	Tasks
Nature	Rigid temporal anchors	Fluid algorithmic entities
Movable	Never	Always (when auto-scheduled)
Engine behavior	Treated as impenetrable walls	Placed, split, and shuffled
Examples	Meetings, appointments	"Write report", "Study chapter 5"

Task Properties

Property	Type	Purpose
`autoSchedule`	boolean	Engine controls placement vs. manually pinned
`duration`	int (mins)	Total work required
`progress`	int (mins)	Work completed — engine schedules `duration - progress`
`dueDate`	datetime	Absolute deadline
`startAfter`	datetime	Earliest possible start
`schedulingHoursId`	FK	Links to temporal mask profile
`priority`	enum	High / Medium / Low / None
`splittable`	boolean	Can be fractured into multiple blocks
`minBlockDuration`	int (mins)	Anti-fragmentation shield
`dependsOn`	string[]	Task IDs that must complete first
`autoIgnore`	boolean	Auto-complete missed repeating instances
`repeatingRule`	object	Daily/Weekly/Monthly/Yearly recurrence

Urgency Color System

Color	Meaning	Engine Behavior
🟢 Green	Normal scheduling	Standard placement
🟠 Orange	Dangerously close to deadline	Bypasses balanced distribution, front-loads aggressively
🔴 Red	Overdue or missing deadline	Scheduled first, past-deadline placement allowed

Features

Core Scheduling

Task Management

Quick-capture Inbox with bi-directional state transition
List-based organization with inherited defaults (color, scheduling hours)
Repeating tasks (Daily/Weekly/Biweekly/Monthly/Yearly/Custom)
Auto-Ignore for missed repeating task instances
Missed Deadlines Resolution Center
Multi-select toolbar with bulk operations
Floating modal task/event editor (no calendar squish)
Discard Changes confirmation modal

Calendar

Day / 3-Day / Week views
Drag-and-drop task rescheduling
All-day event row
Now-line indicator
Double-click to create task/event at specific time
Cutoff zone visualization (gray stripes)

UI/UX

Nord theme (dark + light modes)
Terminal/monospace aesthetic (JetBrains Mono)
Custom frameless window with title bar controls
Command palette (Ctrl+K)
Keyboard shortcuts (Escape, Delete, navigation)
Responsive mobile layout with hamburger menu
PWA support (installable on mobile browsers)

Sync & Storage

Dual persistence: localStorage (fast) + IndexedDB (durable)
Firebase cloud sync (email sign-in, live updates across devices)
Data export and import

Cross-Platform

Project Structure

Muse/
├── electron/
│   ├── main.js              # Electron main process
│   └── preload.js           # Context bridge (IPC)
├── src/
│   ├── engine/
│   │   ├── scheduler.ts     # Constraint-satisfaction scheduling algorithm
│   │   ├── repeating.ts     # Repeating task/event instance generator
│   │   └── dependencies.ts  # Dependency graph + cycle detection (DFS)
│   ├── components/
│   │   ├── CalendarView.tsx  # Main calendar grid (Day/3D/Week)
│   │   ├── Sidebar.tsx       # Navigation sidebar with lists
│   │   ├── InboxView.tsx     # Quick-capture inbox
│   │   ├── TaskListView.tsx  # Task list per category
│   │   ├── MissedDeadlinesView.tsx  # Overdue task resolution
│   │   ├── FloatingTaskModal.tsx    # Task editor modal
│   │   ├── FloatingEventModal.tsx   # Event editor modal
│   │   ├── SettingsModal.tsx        # Full settings panel
│   │   ├── CommandPalette.tsx       # Ctrl+K command palette
│   │   ├── TitleBar.tsx      # Custom frameless title bar
│   │   ├── PhoneHeader.tsx   # Mobile header with hamburger
│   │   ├── AuthScreen.tsx    # Cloud auth (sign in/up)
│   │   ├── RecalculateButton.tsx    # Schedule rebuild trigger
│   │   └── DiscardChangesModal.tsx  # Unsaved changes guard
│   ├── store/
│   │   └── useMuseStore.ts   # Zustand store (state + actions)
│   ├── hooks/
│   │   ├── useCloudSync.ts   # Supabase auto-push/pull
│   │   └── useNotificationScheduler.ts  # Browser notifications
│   ├── utils/
│   │   ├── cloudSync.ts      # Supabase auth + CRUD helpers
│   │   ├── supabase.ts       # Supabase client initialization
│   │   ├── storage.ts        # localStorage + IndexedDB persistence
│   │   └── dateUtils.ts      # Date formatting utilities
│   ├── types/
│   │   └── index.ts          # Complete TypeScript type system
│   ├── App.tsx               # Root component
│   ├── main.tsx              # React entry point
│   └── index.css             # Nord theme CSS variables + global styles
├── supabase/
│   └── schema.sql            # Database schema (run in Supabase SQL Editor)
├── public/                   # Static assets (icons, manifest)
├── android/                  # Android WebView APK project
├── .env.example              # Environment variable template
├── package.json
├── tailwind.config.js
├── tsconfig.json
└── vite.config.ts

Getting Started

Prerequisites

Node.js ≥ 18
npm ≥ 9
Git

Installation

# Clone the repository
git clone https://github.com/siddhantharsh/Muse.git
cd Muse

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

Development

# Start Vite dev server (web only)
npm run dev

# Start Electron + Vite together
npm run electron:dev

The project builds two HTML entry points:

index.html (served at /) — the marketing landing page.
app.html (served at /app.html) — the actual scheduler app. This is what Electron, the installed PWA, and the "Launch App" links on the landing page open. When running npm run dev, visit http://localhost:5173/app.html directly to work on the app itself.

Production Build

# Build the web app
npm run build

# Build Linux desktop (.deb + AppImage)
npm run electron:build

# Build Windows desktop (NSIS installer)
npm run electron:build:win

Cloud Sync Setup (Optional)

The app is preconfigured for the muse-in Firebase project. To enable accounts:

Firebase console → Authentication → Get started → enable Email/Password.
Firebase console → Firestore Database → Create database (production mode).
Deploy the security rules and site: npx firebase-tools deploy --only hosting,firestore:rules

Until step 1 is done, the welcome screen's email login shows a clear "not switched on yet" message and the app works fully offline.

Tests

npm test runs the Vitest suite (scheduler, repeating series, ICS, sync merge, store).

Keyboard Shortcuts

Shortcut	Action
`Ctrl+K` / `Cmd+K`	Open command palette
`Escape`	Close any popup/modal
`Delete` / `Backspace`	Delete selected task/event

Design Philosophy

Why Not an LLM?

The FlowSavvy PRD explicitly notes that generalized LLM interfaces "suffer from hallucinations and struggle with the immense number of constraints required to map several weeks of tasks." Muse uses a dedicated, deterministic scheduling algorithm — no AI randomness, no API costs, no latency. The same inputs always produce the same schedule.

Why Nord Theme?

The interface deliberately adopts a terminal/monospace aesthetic with the Nord color palette. Zero border-radius, JetBrains Mono font, minimal visual noise. The calendar grid lines are intentionally subtle — the focus is on your tasks, not the grid.

Why Floating Modals?

Legacy calendar apps force the calendar to compress when a detail pane opens (the "calendar squish" problem). Muse uses floating, draggable windows that overlay the calendar without reflowing it, preserving spatial context.

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT

_{Built with obsessive attention to scheduling correctness.}

Name		Name	Last commit message	Last commit date
android		android
electron		electron
public		public
src		src
.env.example		.env.example
.firebaserc		.firebaserc
.gitignore		.gitignore
Muse_logo.gif		Muse_logo.gif
README.md		README.md
app.html		app.html
firebase.json		firebase.json
firestore.rules		firestore.rules
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Latest commit

History

Folders and files

Repository files navigation