README.md

Task Cascade

Task Cascade keeps a parent checklist item's status in sync with its children, and adds a quick shortcut for tagging a task to be deleted once it's done.

※ Note: Tasks are ordered from top to bottom. Their horizontal positions in the image are adjusted for compactness and do not reflect the actual layout.

• How it works
• Supported statuses
• Configurable rules
• Disabling the cascade sync for a note
• Settings
• Manual installation
• Alternatives
• Development
• Release Notes

Warning

Task Cascade 1.0.0 and later requires Obsidian 1.13.0 or newer due to its use of the declarative settings API.
If you're using an older version of Obsidian, install Task Cascade 0.2.2, the last compatible release.

How it works

Task Cascade watches editor changes with a short debounce, walks the checklist bottom-up so children are resolved before their parents, and only rewrites a checkbox's marker when the computed status actually differs from what's on the line — so it never touches lines that don't need to change.

Supported statuses

Marker	Status
[ ]	Todo
[x]	Done
[-]	Cancelled
[/]	In Progress
[>]	Forwarded
[<]	Scheduling

Unrecognized or missing checkbox status

A checkbox whose status is a single character that isn't one of the markers above (e.g. - [⁇]) is ignored by default: it is skipped like a plain list item or an empty - [], and never affects its parent. Checkboxes nested under an ignored checkbox attach to the nearest checkbox above it instead, so a parent whose only children are unrecognized checkboxes is left untouched.

Pick a status instead — Todo, Done, Cancelled, or In Progress — to make such checkboxes count toward their parent's rules as that status. Plain list items that aren't checkboxes at all, and malformed checkboxes with empty (- []) or multi-character (- [xyz]) brackets, are always ignored — they never affect a parent's computed status.

Where checkboxes are ignored

Checkboxes that only look like tasks are never read or rewritten, and never affect a parent's status. This covers:

• fenced code blocks (``` and ~~~)
• the note's frontmatter
• $$ math blocks
• %% comments and <!-- --> HTML comments
• blockquotes and callouts (lines starting with >)

Configurable rules

Whenever you edit a checklist, Task Cascade looks at each parent's children and decides whether the parent's own status should change. The decision is made by an ordered list of rules — the first rule that matches wins.

Each rule has:

• An ALL or ANY quantifier — does every child need to match, or just one?
• An expression combining status names with and, or, and not (e.g. done or cancelled or forwarded).
• An outcome status the parent becomes when the rule matches.
• An enabled switch, so a rule can be turned off without deleting it.

The default rules ship ready to use:

1. All children Done → Done
2. All children Cancelled → Cancelled
3. All children Forwarded → Forwarded
4. All children Todo → Todo
5. All children Scheduling → In Progress
6. All children Done, Cancelled, or Forwarded → Done
7. Any child not Cancelled and not Forwarded → In Progress

If nothing matches, the parent is left untouched.

Disabling the cascade sync for a note

Add this to a note's frontmatter to turn off the parent-checkbox cascade sync for that note only:

---
task-cascade-enable: false
---

The #task. shortcut keeps working regardless — this only opts a note out of automatic parent-checkbox updates. Omitting the key, or setting it to true, keeps the default (enabled) behavior.

Settings

Open Settings → Community plugins → Task Cascade to:

• Preview rules — check off which statuses are present among a set of children and see which rule fires and what the parent would become, without touching a real file.
• Set the unknown-checkbox default — choose whether a checkbox with an unrecognized single-character marker is ignored (the default) or counts as Todo, Done, Cancelled, or In Progress; this same value can be toggled on in the rule preview to see its effect.
• Edit rules — change any rule's quantifier, expression, or outcome; add new rules; reorder or delete existing ones; reset back to the defaults at any time.
• Toggle the #task. shortcut — typing a period immediately after #task on a checklist line removes the period and appends 🏁delete to the line, so you can keep typing the task's description right after the tag. Turn this off if you don't use it.

Manual installation

If Task Cascade isn't available in the Community plugins catalog yet, you can install it manually from the GitHub repository:

1. Go to the latest release and download main.js, manifest.json, and styles.css.
2. Create a folder named task-cascade inside your vault's .obsidian/plugins/ directory and place the three downloaded files there.
3. In Obsidian, open Settings → Community plugins, reload the plugin list if needed, and enable Task Cascade.

Alternatives

• Checkbox Autochecker (by klaasklee) – offers predefined 3 propagation modes (Loose, Partial, and Strict) to control exactly how parent and child checkboxes sync in both upward and downward directions.
• Checkbox Sync (by groldsf) – focus on multi-status logic, this plugin provides straightforward bidirectional syncing paired with built-in rules to ignore specific files or folders from processing.

Development

Requirements: Node.js 22.12 or newer (24.x is used for releases) and npm installed.

1. Check esbuild.config.mjs exists. The dev/build npm scripts call it directly (node esbuild.config.mjs) — without it the build won't even start. The standard config bundles from src/main.ts to main.js, with external: ["obsidian", "electron", ...], format: "cjs".

2. Install dependencies:

   npm install

   Creates node_modules and package-lock.json, using devDependencies (esbuild, typescript) and dependencies (obsidian).

3. Build the plugin:

   npm run build

   Equivalent to tsc -noEmit -skipLibCheck && node esbuild.config.mjs production — type-checks first, then produces a minified main.js.

4. Watch mode for development (optional):

   npm run dev

   Runs esbuild in watch mode without minification (node esbuild.config.mjs without production).

   Verify the build succeeded by checking npm run build exits with code 0 and main.js has been updated.

5. Run the tests and the linter:

   npm test
   npm run lint

   npm test runs the Vitest suite in tests/; npm run lint runs ESLint with the Obsidian plugin rules.

Release Notes

1.2.4

• Resolved all npm audit findings in development dependencies: moment is forced to 2.31.x, brace-expansion, fast-uri and js-yaml are updated, and the test runner is upgraded to Vitest 5 (with esbuild 0.28.2); none of these are bundled into the plugin, so there is no change in behavior

1.2.3

• Renamed the settings page CSS classes from apc-* to tc-*; custom CSS snippets that target the old class names need updating
• Fixed the default rules list in this README (there are 7 rules, including "All children Scheduling → In Progress")
• Added an automated test suite (npm test) and an ESLint configuration (npm run lint)

1.2.2

• Rule expressions are now compiled once and reused instead of on every editor change, which makes the cascade sync faster on small notes (no change in behavior)

1.2.1

• Checkboxes inside fenced code blocks, frontmatter, $$ math blocks, and %% / <!-- --> comments are no longer treated as tasks by the cascade sync

1.2.0

• Added an Ignore option to Unknown checkbox status: checkboxes with an unrecognized single-character marker (e.g. - [?]) are skipped and never affect their parent
• Changed default: Ignore is now the default for new installs and for settings that were never saved; previously unrecognized checkboxes counted as Todo. To keep the old behavior, set Unknown checkbox status to Todo in Settings → Community plugins → Task Cascade

1.1.0

• Added a task-cascade-enable: false frontmatter key to disable the cascade sync on a per-note basis (the #task. shortcut is unaffected)

1.0.0

• Migrated the settings UI to Obsidian's new declarative Settings API (now requires Obsidian 1.13.0 or newer — see the warning above for older versions)
• Rules can now be reordered by dragging, not just with up/down buttons
• "Reset rules to defaults" now asks for confirmation before replacing all rules
• Invalid rule expressions now show a clearer error banner instead of just recoloring the row description

0.2.1

• Configurable default status for checkboxes with an unrecognized single-character marker (list items without a checkbox, and empty/multi-character brackets, are still ignored)

0.1.0

• Preview plate
• Auto removed task option
• Configurable rules
• Delete task on done when dot at the end