KanStack

KanStack is a local-first desktop app for working with markdown kanban boards.

It opens a TODO/ folder, loads todo.md plus local cards, and lets you manage nested sub-boards from a Tauri + Vue desktop UI.

What it does

• opens a local markdown workspace
• renders boards, columns, cards, and sub-boards
• edits card content and board structure without adding a database
• keeps the markdown files as the source of truth

Quick start

Requires Node.js, npm, and a working Rust/Tauri desktop toolchain.

1. Install dependencies:

npm install

2. Start the desktop app:

npm run tauri:dev

3. When the app opens, choose a TODO/ folder that contains todo.md and cards/.

To try the app with the workspace already in this repo, open TODO/.

Build and install locally

To package KanStack as a local desktop app:

1. Build the app bundle:

npm run tauri:build

2. Open src-tauri/target/release/bundle/ and install the artifact for your platform.

• macOS: open the generated .dmg or move the .app from src-tauri/target/release/bundle/macos/ into /Applications
• Windows: run the generated installer from src-tauri/target/release/bundle/msi/
• Linux: install the package from src-tauri/target/release/bundle/deb/ or run the AppImage

If you only want to test the production frontend bundle without creating a desktop installer, run:

npm run build
npm run preview

GitHub macOS releases

Pushing a tag like v0.6.1 triggers .github/workflows/release-macos-dmg.yml, which builds the macOS app on GitHub Actions and uploads the generated .dmg to the GitHub Release for that tag.

To support in-app updates, add the GitHub repository secret TAURI_SIGNING_PRIVATE_KEY with the private key generated by npm run tauri signer generate. If the key has a password, also add TAURI_SIGNING_PRIVATE_KEY_PASSWORD.

Workspace shape

KanStack expects a board root like this:

project/
  TODO/
    todo.md
    README.md
    cards/
      some-card.md

• todo.md controls column order, card placement, and saved sub-board links
• cards/*.md holds metadata and long-form content for the current board
• README.md can hold local notes for that board root
• sub-boards are saved in ## Sub Boards as relative paths to child TODO/ folders
• KanStack keeps a lightweight known-board set and can auto-build parent/child links for known boards from path containment
• Attach Existing Board is used for boards that are not yet known to the app
• machine-local app state such as known boards and global view preferences is stored in config.md in the app's local data/config directory

For a fuller walkthrough of the workspace format, see TODO/README.md and docs/schemas/kanban-parser-schema.ts.

Development

Useful commands:

npm run tauri:dev
npm run build
npm run test
npm run wiki:export

The frontend lives in src/ and the Tauri shell/backend lives in src-tauri/.

Wiki export

To snapshot the DeepWiki docs for this repo into local markdown files, run:

npm run wiki:export

This writes a browsable offline copy into wiki/, including a generated wiki/README.md index and inline mermaid fences when DeepWiki exposes them in the embedded markdown payload.

Repo layout

• src/ - Vue app and markdown workspace logic
• src-tauri/ - desktop shell and filesystem commands
• docs/ - plans and schema notes
• TODO/ - the repo's own KanStack workspace used for task tracking