Cascade

A local-first, Markdown-backed project & task manager for your desktop.

Why I built this

I built this because I needed it. I wanted a place to keep every project and every task that lived on my own machine, in files I could read and edit anywhere, without an account or a subscription or my data sitting on someone else's server. Once it started working the way I think, I figured maybe someone else needs the same thing and can benefit from it too. So here it is, open for anyone.

Features

• 🌲 Infinitely nested projects — organize everything as a parent/child tree in the sidebar.
• ✅ Infinitely nested subtasks under each task, with collapse/expand.
• 🧩 Subprojects inline — a child project shows up as a task row inside its parent.
• 🚦 Three priority lanes — Urgent, Important, Normal.
• 🏷️ Rich task statuses — todo, in-progress ⏳, paused ⏸️, waiting-on-someone 🟣, done.
• 📊 Dashboard with KPIs — totals, weekly and monthly completion rate, open urgent count, plus inline SVG charts (30-day line + per-project bars). No chart libraries.
• 🔍 Search that auto-expands matching branches.
• 🌗 Dark & light themes.
• 📝 Everything is human-readable Markdown — your data is yours, git-friendly, and editable in any editor.

Getting started

Prerequisites: Node.js 18 or newer.

git clone https://github.com/azzamalmutairi/cascade.git
cd cascade
npm install
npm start

Electron is installed as a devDependency through npm install, so it works the same on Linux, macOS, and Windows with no extra setup.

Building installers

Cascade uses electron-builder to produce native installers.

npm run dist          # build for your current platform
npm run dist:linux    # AppImage + deb
npm run dist:mac      # dmg
npm run dist:win      # exe (NSIS)

Output lands in the dist/ folder.

How it works / Your data

Every project is a plain Markdown file named project_*.md with YAML frontmatter and a ## Progress block. Nothing is locked inside a database. Here is what one file looks like:

---
name: Website Redesign
description: Marketing site refresh
type: project
parent: project_acme
---

# Website Redesign

## Progress: 40% (2/5)

**Started:** 2026-06-01 · **Last update:** 2026-07-02 · **Since last update:** today

### Counters
- ✅ Done: 2 · ⏳ Doing: 1 · ⏸️ Paused: 0 · 🟣 Waiting: 1

### Tasks

#### 🔴 Urgent
- [x] Finalize brand palette
- [ ] ⏳ Build the landing page
  - [x] Hero section
  - [ ] Pricing table

#### 🟡 Important
- [ ] 🟣 Legal review — *waiting: legal team*

#### 🟢 Normal
- [x] Set up analytics

• Where files live. You choose a data folder inside the app. By default it uses your OS app-data directory, but you can point Cascade at any folder — for example a git repo or a synced directory.
• Edit by hand, anytime. Open a project_*.md file in any editor, make your changes, and Cascade reflects them on reload. Nested subtasks are just indented checkbox lines; statuses are the emoji prefixes shown above.
• OVERVIEW.md. A dashboard file is generated automatically so you get a readable summary of everything, even outside the app.
• Nothing is truly deleted. Deleting a project moves its file into a _trash/ folder inside your data folder, so it is always recoverable.

Because it is all Markdown, your data survives Cascade. You can commit it, grep it, diff it, and read it in twenty years.

Languages

Cascade ships in English (default) and Arabic, with full right-to-left (RTL) support. Switch languages with the in-app toggle at any time.

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, project layout, and conventions. PRs welcome.

License

MIT © 2026 Azzam Al-Mutairi. See LICENSE.

---

بالعربية

Cascade مدير مشاريع ومهام لسطح المكتب يعمل محلياً بالكامل، ويحفظ كل شيء في ملفات Markdown مقروءة يمكنك تعديلها بأي محرر — بلا حساب، بلا اشتراك، وبلا إنترنت.

لماذا بنيته؟ بنيته لأنني احتجته: مكان يجمع كل مشاريعي ومهامي على جهازي أنا، في ملفات أملكها. وبعد أن اشتغل بالطريقة التي أفكر بها، رأيت أن غيري قد يحتاجه ويستفيد منه، فجعلته مفتوح المصدر للجميع.

المزايا: مشاريع متداخلة بلا حدود، مهام فرعية متداخلة قابلة للطي، مشاريع فرعية تظهر كصفوف مهام داخل المشروع الأب، ثلاث مستويات أولوية (عاجل / مهم / عادي)، حالات للمهمة (قيد الانتظار، جارٍ ⏳، معلّق ⏸️، بانتظار طرف آخر 🟣، مكتمل)، لوحة مؤشرات مع رسوم SVG مدمجة، بحث، وثيمة داكنة وفاتحة. كل البيانات تُحفظ كـ Markdown، والحذف يذهب إلى مجلد _trash/ قابل للاستعادة.

كيف تشغّله؟

git clone https://github.com/azzamalmutairi/cascade.git
cd cascade
npm install
npm start

يتطلب Node.js بإصدار 18 أو أحدث. الترخيص MIT © 2026 عزام المطيري.