Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Productivity

Productivity is a calm, fast desktop task manager for macOS and Linux. Your tasks live in one SQLite file on your computer: no account, no cloud, and no internet connection required.

Downloads and build reports

This site brings the user guide and the latest successfully published main build together.

SectionWhat you will find
Installers and APTSetup instructions and the signed Ubuntu 26.04 amd64 repository. Latest download.
Test coverageMeasured Rust coverage, with browsable per-file reports.
SBOM and dependency policyThe release’s CycloneDX inventory, license policy, and RustSec checks.
Build identityThe version and source commit of the published Ubuntu package.

The Ubuntu APT repository is signed. Compare the key’s fingerprint with the one in the installation guide before adding it.

Explore the app

Six views show the same tasks:

  • Today plans due, overdue, and manually chosen tasks by part of the day, with optional timeboxes.
  • List shows Open, Done, and Archived tasks in due-date order.
  • Eisenhower matrix sorts open tasks by importance and urgency.
  • Kanban board shows To do, In progress, Done, and On hold columns.
  • Projects groups tasks with drag-and-drop assignment.
  • Calendar shows start-to-due spans by month or week.

Insights charts tasks by status and project and shows how long tasks take to start and finish.

An experimental Notes workspace browses and edits a folder of Markdown files.

This book is the user guide and reference. For a visual tour, see the project page.

Sync, reminders, recurrence, accounts, Obsidian/Apple Reminders integrations, and iOS are future work, not current features.

Installation

Productivity runs on macOS (Apple silicon or Intel, Metal required) and Linux (Wayland or X11, normally with a Vulkan driver). The Ubuntu APT repository is signed; macOS builds have no Developer ID signature or notarization.

macOS with Homebrew

You need Apple’s Command Line Tools (xcode-select --install), Rust, and uv for the packaging helper.

git clone https://gitlab.com/framezero/productivity.git
cd productivity
brew tap-new local/productivity  # once
uv run --locked python tools/brew_local.py
brew trust --cask local/productivity/productivity
brew install --cask local/productivity/productivity

tools/brew_local.py builds an optimized release, ad-hoc signs and verifies the finished app bundle, and writes a local archive and cask. The archive excludes Finder/resource-fork metadata that would invalidate strict signature verification. The helper never installs or launches the app. To update, quit Productivity, pull, rerun the Python command, and run brew reinstall --cask local/productivity/productivity. Uninstall with brew uninstall --cask productivity; your data stays in place.

This is not a published tap, so brew update does not fetch new builds. Ad-hoc signing checks bundle integrity but does not establish a developer identity or notarize the app; macOS may still ask for approval in System Settings → Privacy & Security. brew trust approves the local cask, not the app’s macOS signature.

If an older local build says it is damaged and should be moved to the Bin, regenerate the bundle with the current helper and reinstall it:

# Save your work and quit Productivity first.
uv run --locked python tools/brew_local.py
brew reinstall --cask local/productivity/productivity

brew install skips an already-installed version even after rebuilding; reinstall replaces it. Do not repeat brew tap-new if the tap already exists. To check the replacement’s signature, run codesign --verify --deep --strict --verbose=2 /Applications/Productivity.app.

Ubuntu 26.04 (APT repository)

CI publishes a signed amd64 repository on every successful main pipeline. Installation from the earlier unsigned repository worked on Ubuntu 26.04; the signed setup below and graphical launch of the packaged app have not been verified on Ubuntu yet.

Latest .deb download and build details · Release SBOM · Test coverage

APT checks every update against the repository’s signing key. Its fingerprint is:

BD52 1CD6 100F C5CF D197  ECE9 9F9C F1D4 7765 E81C

The key file is also committed in the source repository as packaging/apt/productivity-archive-keyring.asc. These commands work in bash, zsh, and fish. First download the key and compare its fingerprint with the one above:

sudo install -d -m 0755 /etc/apt/keyrings
sudo wget -qO /etc/apt/keyrings/productivity.asc https://productivity-b29eff.gitlab.io/productivity-archive-keyring.asc
gpg --show-keys /etc/apt/keyrings/productivity.asc

If the fingerprint differs, stop and delete the file. Otherwise add the source and install:

printf '%s\n' 'Types: deb' 'URIs: https://productivity-b29eff.gitlab.io' 'Suites: resolute' \
  'Components: main' 'Architectures: amd64' 'Signed-By: /etc/apt/keyrings/productivity.asc' |
  sudo tee /etc/apt/sources.list.d/productivity.sources >/dev/null
sudo apt update
sudo apt install productivity

/etc/apt/sources.list.d/productivity.sources then contains:

Types: deb
URIs: https://productivity-b29eff.gitlab.io
Suites: resolute
Components: main
Architectures: amd64
Signed-By: /etc/apt/keyrings/productivity.asc

Upgrading from the earlier unsigned repository: if your source file still says Trusted: yes, run both blocks above. tee replaces the file, which removes Trusted: yes; APT then refuses any repository data that this key did not sign.

The signing key is valid until 2028-11-14. Before then, a renewed key will be announced here; you will need to download it again with the same wget command.

If Productivity cannot start, it shows the error and this session’s log instead, with buttons to copy both, open the log folder, or report it: Report on GitLab copies the error and log and opens the project’s issues, so you can paste them into a new issue. “This database was created by a newer version” means a newer build, such as one run from source, has already upgraded your database; this package is older and will not open it. Install a package at least as new as that build. Your data is not changed.

Quit Productivity before upgrading with sudo apt update && sudo apt install --only-upgrade productivity. Uninstall with sudo apt remove productivity, and delete the source file if you no longer want it. Neither deletes your tasks or Markdown files. The repository keeps only the current package. The build identity of the published package is available too.

From source

Install Rust (stable) and, on Linux, the native libraries below. Then:

git clone https://gitlab.com/framezero/productivity.git
cd productivity
cargo run --locked --release

The first build takes a while because GPUI compiles its rendering stack.

macOS requirements

Install Apple’s Command Line Tools. The app uses GPUI’s runtime Metal shaders, so the standalone Metal compiler is not needed. If your developer tools point to a fresh Xcode, finish its first-run setup and review its license before building.

Linux requirements

On Ubuntu or Debian:

sudo apt-get install -y build-essential clang cmake pkg-config \
  libasound2-dev libfontconfig1-dev libfreetype6-dev \
  libwayland-dev libx11-dev libx11-xcb-dev libxcb1-dev \
  libxkbcommon-dev libxkbcommon-x11-dev libxi-dev libxrandr-dev \
  libxcursor-dev libxinerama-dev libgl1-mesa-dev libegl1-mesa-dev libvulkan-dev

Package names vary by distribution. Also install a Vulkan driver for your GPU, for example mesa-vulkan-drivers.

Test coverage

Browse the published Rust coverage report →

The HTML report shows measured line, function, and region coverage per file, including annotated source. It comes from the same successful main pipeline as the Ubuntu package, release SBOM, and book on this site.

CI uses cargo-llvm-cov with stable Rust and --all-features, including the core/storage tests and GPUI’s headless UI tests. Branch coverage is not collected. Coverage is not evidence of a graphical or installer test on Ubuntu or macOS. SAST, Secret Detection, and dependency advisory checks are separate CI checks, not part of the coverage percentage.

The report covers this application’s Rust code, not a security review of its dependencies. This site retains only the latest successful publication; a newer failed pipeline does not replace it.

See Development → Coverage to run the report locally. Report links are populated when CI publishes Pages; an ordinary local mdBook build contains the guide but not the generated reports.

SBOM and dependency policy

Published release SBOM

Browse the release SBOM: components, versions, and licenses →

Download the Ubuntu amd64 CycloneDX SBOM (JSON) for tools. The browsable page is generated from this file in the same pipeline. Pages also publishes sbom/badge.json, a shields.io endpoint that the README’s SBOM badge reads to show the format and component count.

This CycloneDX 1.6 inventory comes from the package job, after the release version is assigned and the executable is built. It describes the Cargo dependencies of the Ubuntu 26.04 amd64 desktop binary, not the broader check job’s inventory.

The SBOM records transitive dependencies, declared license expressions, package URLs, registry archive checksums, and dependency relationships. Its metadata records the target, desktop features, lockfile checksum, and the built executable’s SHA-256. Build-only dependencies are retained with excluded scope, rather than marked as runtime requirements.

The executable hash in the SBOM identifies the binary inside the .deb. It is not the hash of the .deb archive; the downloads page and SHA256SUMS provide that separately. Checksums detect mismatches but do not authenticate the publisher. The APT repository’s signature does that for packages installed through APT.

Only the latest successful Pages publication is retained. Its book, coverage, SBOM, vulnerability scan, and installer come from the same pipeline. macOS SBOMs remain available with their opt-in CI job’s artifacts; this site does not imply a macOS release.

License policy

The checked-in dependency_policy.toml checks dependencies across all supported desktop targets, including build and test dependencies. It permits the existing approved licenses and has exact-version exceptions for existing MPL-2.0 crates. New licenses and MPL upgrades require review. GPL, AGPL, LGPL, and EPL are not approved; dual-licensed crates can pass under an approved alternative.

A component’s declared license expression in the SBOM is not a statement that every offered alternative is approved or selected. The application’s own license is still undecided; the dependency policy does not grant one.

RustSec

cargo-deny checks the dependency graph against the RustSec advisory database. Known vulnerabilities, unsoundness, and yanked releases block packaging. Unmaintained-crate advisories are visible warnings, not ignored findings. This checks published advisories; it does not prove an absence of vulnerabilities.

Maintenance follow-up

The November 2026 dependency review found seven maintenance advisories. A compatible lockfile refresh removes the EXR → pulp → paste path, and Notify 8 removes the application’s notify-types 1 → instant path, but the remaining consumers below still require all seven crates:

CrateRemaining consumersMaintained replacement / next step
instantGPUI Base and GPUI ComponentUpstream migration to web-time or native std::time.
pasteGPUI ComponentUpstream migration to pastey or equivalent macros.
rustybuzzGPUI and Mermaid’s SVG/font stackMigrate consumers to harfrust and newer usvg/resvg.
ttf-parserGPUI, Mermaid, and font dependenciesMigrate consumers to skrifa and newer font/SVG libraries.
zbus_names, zvariant, zvariant_deriveLinux portal, keyring, and accessibility dependenciesCoordinated migration to zbus 6, which incorporates these standalone crates.

GPUI’s published snapshot and GPUI Component must remain version-matched. Recheck new releases of GPUI, GPUI Component, Mermaid, and the Linux integration stack during dependency updates; do not substitute incompatible transitive versions, disable text rendering/accessibility, or suppress advisories merely to clear the warnings. These findings are maintenance risks, not known vulnerabilities, and remain visible in CI until their consumers migrate.

Vulnerability scan

Browse the latest vulnerability scan → · Grype JSON report · RustSec JSON report

After packaging, a pinned Grype scans the published release SBOM above, and the same job records every RustSec finding from cargo-deny. Pages publishes both on one report page, with vulnerabilities/badge.json for the README badge. The badge lists Grype’s severity counts (or “none found”) followed by RustSec findings by kind, for example “none found, 7 unmaintained”. A vulnerability reported by both counts once.

RustSec also records crates that are unmaintained, unsound, or yanked. These are not vulnerabilities, so the GitHub Advisory Database and NVD do not list them and Grype can be clean while cargo-deny warns. The report shows them so maintenance risks are visible outside the CI log; unmaintained crates stay warnings and do not fail the pipeline.

Grype is a second, independent opinion beside RustSec. Its database combines the GitHub Advisory Database (which imports most RustSec advisories and adds its own) with NVD data, so findings carry CVE aliases, CVSS-based severities, and CWE weakness types. It checks exactly the crate versions recorded in the shipped SBOM.

cargo-deny (RustSec)Grype
InputCargo.lock graph, all supported targets, incl. build/dev dependenciesRelease SBOM (Ubuntu amd64 desktop binary)
DataRustSecGitHub Advisory Database, NVD, EPSS
VulnerabilitiesYes, fails CIYes, reported only
Unsound / yanked / unmaintainedFails / fails / warns; all shown in the reportNot checked
Licenses, sources, duplicate cratesChecked by policyNot checked
Severity, CVE, CWE detailsAdvisory textYes

The scan reports findings without failing the pipeline; the RustSec check in the supply-chain job remains the release gate. A scan failure (for example, an unavailable or outdated database, or cargo-deny output that ends early) blocks publication rather than showing a stale or falsely clean badge. The RustSec part covers the whole dependency graph that cargo-deny checks, which is wider than the release SBOM. The badge reflects publication time, not advisories disclosed afterwards. Like the SBOM, the scan covers Cargo crates only: bundled SQLite appears only as libsqlite3-sys, so SQLite CVEs are not matched by version, and Ubuntu’s system libraries are updated by the distribution, not this scan.

Inventory limits and local checks

This is a Cargo dependency SBOM, not a complete inventory of bundled native sources, system libraries, the Rust standard library, fonts, icons, or build tools. Bundled SQLite appears through libsqlite3-sys, not as a separate SQLite component. The SBOM does not replace required third-party notices or a license review.

See Development → Dependency licenses, RustSec, and SBOMs for pinned tools, local commands, policy details, and generation safeguards. Download links are populated by Pages publication, not by an ordinary local mdBook build.

Tasks

Choose + New Task (Cmd+N / Ctrl+N) or click any task to open the editor beside the current view. Every view edits the same tasks. Type and Status sit side by side at the top of the editor, above the title.

Fields

  • Title is required. Press Enter in the title to save.
  • Link (optional) is one web address for the work behind the task, such as a Jira Task or Bug, a GitLab merge request or issue, or a GitHub pull request or issue. Paste the address from your browser; it must start with https:// or http://. Productivity recognises these from the address alone and shows a short label with an icon (PROJ-123, app!7, repo#42) beside the field; other addresses show their server name. Every task card with a link has an open-link icon at the end of its title, in all views including Projects, Calendar, and Today’s timebox; click it, or the label beside the field, to open the link in your browser without opening the task. Nothing is fetched, so private and self-hosted servers work without signing in to anything; the title is still yours to write. Pasting a merge request, issue, or Jira link also sets the draft’s Type to match and puts the short reference in brackets at the front of the title, such as [!232] Review login fix or [PROJ-123] Fix crash. Changing the link updates that prefix; removing it removes the prefix. Your own brackets stay, and both changes wait for Save like any other edit.
  • Notes hold context, links, or the next step.
  • Start / Due opens one calendar popup. Choose Start or Due, then a day; clear either independently. Start only, due only, both, or neither are valid. Both endpoints and the days between them stay marked, and days that would put Start after Due are disabled. Dates are calendar dates, not reminder times.
  • Priority is a four-square pad. Important is the top row and Urgent the left column. Drag the selected square, click another, or use the arrow keys. Deadlines never change priority.
  • Type is Task (the default), Idea, Bug, Merge request, Issue, or Jira. It is descriptive only. A small colored icon before the title on task cards and in the editor tells them apart: a checkbox for Task, a light bulb for Idea, a bug for Bug, a branch for Merge request, a dot for Issue, and a ticket for Jira.
  • Status is To do, In progress, Done, or On hold. Only Done counts as completed.
  • Project selects one project or No project, applied only on Save. See Projects.

Saving

Edits stay in a draft until you save with ✓, Save task, or Cmd+S / Ctrl+S. × or Cancel discards the draft. Invalid or failed saves keep the editor open and show the error.

While a draft has unsaved changes, opening another task, dragging, or completing that same task is refused until you save or cancel. Switching views keeps the draft. Drafts are not recovered after quitting.

Use a task’s circle button to complete it (Done) or reopen it (To do). Deleting a task asks for confirmation and cannot be undone.

Archive task in the task details moves the task to List’s Archived section at once, whatever its status, and takes it out of Today with its plan and timebox; its status and other fields do not change, and an unsaved draft stays open. Unarchive task brings it back; it is not planned for Today again automatically. Complete Day archives all Done tasks at once.

List and Today

The List (Cmd+2 / Ctrl+2) shows every task matching the current project and type filters, in Open, Done, and Archived sections. Within each section, tasks sort by due date, undated last, with stable creation-order ties. Completed and archived tasks are always shown; there is no completed-task visibility setting.

Today

The separate Today planner (Cmd+1 / Ctrl+1) opens by default. The sidebar’s overdue and Today counts open this screen without discarding editor drafts; both counts match the current project and type filters. They are disabled when Today is hidden in Settings. The parts of the day fill the screen, with Other open tasks beside them; each column scrolls on its own. The Timebox timeline is hidden by default: Show timebox in the toolbar opens it beside the lists for the current session, and Hide timebox closes it again without changing any plans. While it is hidden, timeboxed tasks stay in the list, in the part of the day their slot starts in and labelled with its time. With the timeline shown, the lists and the timeline scroll independently; scrolling the day leaves the lists, timebox controls, and page toolbar in place.

The Today list includes due, overdue, and manually planned tasks without a time slot today. Drag a task from Other open tasks into this panel to plan it. Manual plans persist across days until removed or archived. Drag a planned task back to Other open tasks to unplan it. Due and overdue tasks remain automatically.

Parts of the day

The list is grouped into Morning (until 12:00), Afternoon (until 17:00), Evening, and Anytime, which suits tasks that do not fit a time slot, such as replying to messages or reviewing changes. Drag a task onto a part to put it at the end, or onto a task to put it just above. Your order is kept; tasks you have not ordered, such as due tasks that are not planned, follow it, and Done tasks come last. Moving a task plans it for Today and removes its timebox for today; it never changes the task itself.

Unfinished tasks move on by themselves: once a part is over it disappears, and its tasks show at the top of the current part, marked Moved on from Morning (or from yesterday). A part chosen on an earlier day counts as over. Moving on is only shown, not saved, so the task keeps the part you chose until you move it again. Anytime tasks never move.

Tomorrow

Below the parts of the day, the Tomorrow list lets you plan the next day, for example in the evening. It is collapsed by default and shows how many tasks it holds; the chevron expands or collapses it for the current session. Drag a task onto it, even while collapsed, to plan it for tomorrow; drop it onto a listed task to put it just above. Your order comes first, then open tasks due tomorrow, which are listed automatically and are not in Other open tasks. Planning a task for tomorrow takes it out of Today and removes its timebox for today.

Move to tomorrow, beside Clear in the Today list, plans every unfinished task planned for today for tomorrow at once, across all projects. They follow the tasks already in Tomorrow, in Today’s order, and lose their part of the day and today’s timebox. Done tasks stay until Complete Day, and due or overdue tasks stay in Today because their dates do not change. It is refused while an affected task has an unsaved draft.

Tomorrow’s own header has Move to today, which plans everything in Tomorrow for today under Anytime, in Tomorrow’s order and after Anytime’s ordered tasks, including open tasks due tomorrow; and Clear, which removes the plans for tomorrow. Both work across all projects. Tasks due tomorrow stay in Tomorrow after Clear, because their dates do not change. Both are refused while an affected task has an unsaved draft.

Move to today in Other open tasks plans the tasks listed there for today under Anytime, in the listed order. Unlike the buttons above, it follows the project and type filters: only the tasks you see move.

Right-click a card in Today, Tomorrow, or Other open tasks for Move to Today, Move to Other open tasks, and Move to Tomorrow. The card’s own list is disabled, as are moves that cannot apply: Done tasks cannot be planned, and a task that is only due (not planned) cannot leave Today or Tomorrow, since its date does not change. Moving to Today plans the task under Anytime; moving to Tomorrow puts it at the end of Tomorrow.

When the next day starts, those tasks are simply in Today, under Anytime in your order; nothing needs to be saved at midnight. Drag a task from Tomorrow into a part of the day to plan it for today instead, or to Other open tasks to unplan it.

Timeboxes

Show the timeline with Show timebox, then drag an open task onto Timebox to give it a 30-minute timebox. Starts and durations snap to 15-minute steps and cannot cross midnight. Each task has at most one saved timebox. Timeboxing also adds a manual Today plan, without changing the task’s dates, status, priority, or project.

  • Drag a block to move it; drag its bottom edge to resize it.
  • − / + shorten or lengthen it by 15 minutes.
  • ×, or dragging the block into a part of the day, removes the timebox but keeps the Today plan.
  • Dragging a block to Other open tasks removes both the timebox and its manual plan.
  • With the timeline shown, the clock beside an open task without a timebox chooses the next free 30-minute slot from now, considering all tasks, including ones hidden by filters. It reports an error when no slot remains.

Overlapping blocks appear side by side. The timeboxed total sums durations, including overlaps. Settings → Day planner sets the workday’s start and end in 15-minute steps (default 06:00–22:00). Start must precede End on the same day; End can be 24:00. Changes save automatically and persist across restarts without changing tasks or drafts. The timeline uses that exact range, extending as needed to include saved earlier/later timeboxes. These are display hours, not a restriction on timeboxing or the clock action. Full day exposes all 24 hours; Workday returns to the saved range, still including out-of-hours blocks. The compact hour scale and separate scrolling are unchanged. A red line marks the current minute when in range; the planner refreshes every minute. After midnight, older timeboxes no longer appear on today’s timeline, but their tasks remain in the Today list through their manual plans.

Clear removes every manual plan for today and every timebox across all projects in one transaction. Plans for tomorrow stay. Due and overdue tasks remain, with a short explanation. Planning changes are refused while the affected task has an unsaved draft. Failed writes leave the saved plan unchanged.

Completed Today tasks stay in the planner, dimmed and struck through, until Complete Day. Done blocks cannot be moved or resized, but their timeboxes can be removed.

Complete Day

Complete Day, in the Today toolbar, archives every Done task across all projects and celebrates only the number newly archived. It removes their Today plans and timeboxes, and, like Clear, removes today’s manual plans and every timebox of unfinished tasks, so they return to Other open tasks. Due and overdue tasks stay in Today, and plans for tomorrow remain. It is refused while a Done or planned task has an unsaved draft. Archived tasks leave the planner and appear in List’s Archived section; their status does not change, and the other views retain them. Archiving persists across restarts.

Eisenhower matrix and Kanban

Eisenhower matrix

The matrix (Cmd+3 / Ctrl+3) sorts tasks into Urgent & important, Important, Urgent, and Neither. Drag a card to another quadrant to change its importance and urgency flags; its due date, status, and identity stay the same. The Status filter, shared with Projects and Calendar, chooses which statuses appear. It starts on Not done, so Done tasks are hidden; check Done or choose All to show them dimmed.

Kanban board

The board (Cmd+4 / Ctrl+4) has To do, In progress, Done, and On hold columns. Drag a card to change its status immediately; priority and dates stay unchanged. Each column’s + starts a new task in that status. Done cards remain visible while the Done column is shown and can be dragged back out.

Columns are configurable. The eye button in a column’s header hides it, together with its cards; at least one column stays shown. Hidden columns appear as buttons in the toolbar: click one to show the column again. Drag a column by its header onto another column to move it there. The order and hidden columns are saved and kept across restarts; they never change any task or an open draft. The board fills the window above the shortcut footer and each column scrolls vertically. The columns share the width and narrow to fit even the smallest window. Only when less space is left, for example beside the task editor, a scrollbar appears along the bottom: drag it or click its track, or use a trackpad, a horizontal wheel, or Shift+wheel.

Projects

Open Projects (Cmd+5 / Ctrl+5) to see every project as a container with its tasks laid out in rows. A task belongs to at most one project, or to No project. Cards fill available columns before extending into additional rows. The layout reflows when the window or editor changes the available width and never scrolls sideways: narrow space means fewer columns, then a single column of narrower cards.

Projects

  • New project asks for a name. Edit project renames or deletes it; deleting moves its tasks to No project instead of deleting them.
  • Drag a card into another project to move it, or into No project to unassign it. Moving keeps the task’s status, dates, and priority.
  • The chevron beside a project’s name collapses it to one row of title-only cards, in the usual order, as many as fit the width. When more tasks exist, a small +N more chip follows the last card that still fits (in very narrow space, the chip alone); click it or the chevron to expand the project again. The header keeps the full task count, and collapsed projects still accept dropped cards. Collapse all and Expand all at the top act on every project shown. Collapsing lasts for the current session and never changes tasks.
  • In the task editor, the Project dropdown sets or clears the project on Save. Cancel discards the change. Project details list their Child tasks, including Done ones.

A named project filter displays only its section. No project remains a drop destination under All projects or No project; use the task editor’s Project dropdown to unassign without changing the filter.

Projects hides Done tasks by default because the shared status filter starts on Not done; check Done or choose All to include them. Blocking links are no longer displayed or editable. Existing dependency records remain stored and are preserved when editing tasks or moving them between projects.

Calendar

The toolbar also counts unscheduled tasks with neither a start nor a due date. This count respects the project, type, and status filters.

Open Calendar (Cmd+6 / Ctrl+6) and pick Month or Week from the menu. Weeks start on Monday. ← / → move by the selected period and Today jumps back. The current day has a small today label. The Month / Week choice lasts for the current session. Weekly navigation crosses month and year boundaries without changing saved tasks.

The calendar fills the window above the shortcut footer, and its weeks share the height. In short windows the weeks scroll inside the calendar; in narrow ones a scrollbar along the bottom scrolls it sideways, as do a trackpad, a horizontal wheel, and Shift+wheel.

Enable Week numbers in Settings → Calendar to display ISO week numbers beside each week in both modes. The preference is saved.

Settings → Calendar also offers Work week only and a choice of Working days. The default is a full seven-day week, with Monday–Friday preselected as working days. For a Friday/Saturday weekend, deselect Friday and select Sunday. At least one working day must remain selected. Both modes keep Monday-first ordering and seven-day navigation; the setting only hides non-working columns. Task dates do not change, and period counts still include tasks on hidden days.

  • Tasks with both dates span Start through Due, continuing across weeks and months.
  • A start-only task has a hard left edge and a fading right edge; a due-only task fades on the left. The fade marks an unknown endpoint, not extra scheduled days.
  • Done tasks are hidden by the Status filter’s default Not done; check Done or choose All to show them muted. Tasks without dates do not appear.
  • The toolbar counts tasks overlapping the displayed month or week.

Click a card to edit it. Navigation never changes dates, and it keeps any open draft.

Insights

Open Insights (Cmd+9 / Ctrl+9, or the pie-chart button above Settings at the bottom of the sidebar) for read-only statistics. It has three tabs: Tasks for your work, App for storage and system details, and Logs for troubleshooting. Press Left or Right to switch tabs; the toolbar with its summary and filters stays the same on every tab, though the filters only affect Tasks. Insights never changes a task or an open draft, and you can keep editing a task beside it.

Filters

The shared Type and Project filters apply, plus two filters that belong to Insights and last for the current session:

  • Range: Last 7 days, Last 30 days (default), Last 90 days, or All time. It applies to the Created and Completed counts, the durations, and the completions chart.
  • Archive: Archived and not (default), Not archived, or Archived only. Archiving is independent of status, so Archived only usually shows tasks finished on earlier days.

What it shows

  • Tasks: how many tasks match the filters.
  • Created and Completed: tasks created, and Done tasks last completed, within the range. A task that was reopened is no longer counted as completed.
  • Creation to start: the average time from creating a task until it was first set to In progress, with the median and the number of tasks. It counts tasks first started within the range.
  • Start to done: the average time from a task’s first In progress to its last Done, for Done tasks completed within the range. Time spent On hold or back in To do in between is included. Tasks marked Done without ever being In progress are listed separately.
  • By status and By project: donut charts of the current status and project of every matching task, regardless of the range. The six largest projects are shown individually; the rest are combined as Other projects. To see the status breakdown of one project, pick it in the Project filter; the chart title then names the project.
  • Overdue: open tasks whose due date has passed, regardless of the range.
  • Due dates: a donut of Done tasks with a due date, completed within the range, split into On time (finished on or before the due day, in local time) and Late. Tasks without a due date, and tasks with no recorded completion time, are left out.
  • Task lists: a row of three cards below the donuts, each as wide as a donut card and listing up to three tasks. Click one to open it in task details.
    • Oldest open tasks: the earliest-created tasks that are not Done, with their age.
    • Longest in progress and Longest on hold: tasks with that status, longest first, with the time since they last moved into it. A + (such as 40d+) means the status predates the recorded history, so the task has had it at least that long. These two lists need the status history and say so when it cannot be loaded.
  • Completed per day / week / month: completions over the range, by day for 7 or 30 days, by Monday-first week for 90 days, and by month for All time.

Days follow your computer’s time zone.

Where the times come from

Every status change is recorded with the time it was saved, whether it comes from task details, Kanban, or the completion checkbox. Recording started with the version that added Insights (database schema 23). For tasks that already existed then, Productivity only knows their status at that moment:

  • their creation time is known, so a later first start still counts toward Creation to start;
  • a task that was already In progress, Done, or On hold has no known start, and an earlier Done has no known completion time, so those tasks are left out of the durations.

Load example creates example tasks with a backdated history, so Insights has something to show. Deleting a task removes its history.

App and Logs tabs

The App and Logs tabs measure what Productivity stores and reread the logs when you open them; the refresh button beside the tabs does so again. Every card has a copy icon in its top-right corner that copies its contents as plain text, for example for a bug report.

  • Storage lists each part separately with its location, number of files, and size, plus the total on disk:
    • the task database (tasks, projects, settings, status history, and the note index),
    • Markdown notes, note images (the notes folder’s assets/), and other files in the notes folder, when a notes folder is selected,
    • note recovery copies and logs. Productivity keeps no cache on disk; the in-memory caches for note previews (checked image paths and rendered diagrams) are shown separately. Entries that cannot be read are marked.
  • System shows the version and build, database schema and location, operating system, processor, memory in use, windowing system (macOS, Wayland, or X11) and window decorations, window size and scale, and graphics. On Linux, graphics names the GPU and driver and says when rendering falls back to the CPU (software rendering such as llvmpipe); macOS always renders with Metal on the GPU, but GPUI does not report the device name there.
  • Log files (on the Logs tab) shows the log folder’s path, how many log files and app sessions it holds, and the time of its oldest entry.
  • Logs (its own tab) shows the log lines of Productivity and the warnings and errors of the libraries it uses, for one session at a time: This session by default, or the Previous session. Sessions are split at each app start, even when a session spans several log files; a session whose beginning was already rotated away says so. Copy copies every line of the shown session. The newest lines can take a moment to reach the log file.

Hide Insights in Settings → Views if you do not need it. It does not count as one of the task views that must stay shown.

Filters

Two filters in the toolbar apply to List, Eisenhower, Kanban, Projects, Calendar, and Insights:

  • Type: All types, Task, Idea, Bug, Merge request, Issue, or Jira.
  • Project: All projects, No project, or a named project.

They combine, change only what is shown, and last for the current session. Counts follow the filters. A new task inherits a specifically selected project and type. Changing a filter never saves or discards an open draft.

Projects shows only matching tasks; legacy dependencies do not add external context. With a named project selected, only that project’s section is shown, even when empty. No project is shown under All projects or No project. To unassign a task while filtered by a named project, use its Project dropdown in task details.

The project filter is shared with Notes Browse.

Eisenhower, Projects, and Calendar also share a session-local Status filter. Open it and check any combination of To do, In progress, Done, and On hold. Tasks match any checked status, combined with the project and type filters. It starts on Not done (To do, In progress, and On hold), so Done tasks are hidden until you check Done or choose All. All selects every status; Clear unchecks every status and shows no tasks. Changes apply immediately, and the popup stays open while selecting multiple statuses. It does not affect List or Kanban, or change any task or editor draft.

Notes

In the note editor, the formatting toolbar provides bold, italic, inline code, links, headings, lists, quotes, and code blocks. Heading, list, quote, and code block actions apply to the selected lines.

Browse gives the note list about a quarter of the available width by default. Drag the divider to resize the list and preview. This session-local size is independent of the editor’s source/preview divider.

Sidebar shortcuts can be reordered by dragging a note onto another shortcut.

Notes is experimental and hidden by default. Turn it on in Settings → Views.

Library

Choose an existing folder of Markdown files. Productivity indexes it locally; Refresh rescans it. The Markdown files remain the source of truth.

Browse

  • The row under the page title shows how many notes the folder holds and where it is, with Choose folder…, Refresh, Import…, Recovery, and Export all….
  • Search matches titles and file contents. Press Enter or Search to apply it.
  • Sort by title, created, modified, or journal date. Each card shows its journal date (or Undated) before its file name.
  • Filter by project (shared with the task views) and by linked task or unlinked notes.
  • Click a note for a read-only preview; the selected note is highlighted. ↑ / ↓ move through the list and update the preview. Links, images, and HTML are inert, and previews are limited to 1 MiB.
  • The preview’s header reads like an e-mail: the note’s title with its action buttons, then its file, journal date, and creation time, with the time the file last changed on disk (including edits made in other apps) on the right. Below, Linked shows each linked task as a mini card (type icon, title, status, due date) and each project with its task count; click a card to open its details, or × to unlink it. The picker beside them links another task or project. Write shows the same cards beside its formatting toolbar.
  • The preview is an embedded block editor: click a block to edit it right there, as in Blocks. Your changes go into the same draft as Write and are saved the same way. Click beside the blocks, or select another note, to stop editing.
  • Double-click a note in the list, or a shortcut’s full preview, to open it in Write.
  • The star adds the note to Shortcuts, the pen opens the editor, and the arrow opens a full preview. The same three actions appear in each card and in the preview’s toolbar. Back returns to where you were.

Editing

The current local day appears above the page title, just as in the other views. The editor offers Edit, Split, Preview, Live Edit, and Blocks layouts. Split and Preview show a live, inert preview. Edits autosave after a one-second pause; Save or Cmd+S / Ctrl+S saves immediately. The row under the page title holds the note’s name (click it to rename the note within its folder), its save state, Save, discard (↶), delete (trash), and the full-preview arrow. Below it, a compact icon toolbar formats the text: bold, italic, inline code, and link; heading 1, heading 2, list, task checkbox, quote, and code block; and insert image. Inline code and quote toggle off when applied again; a code block fences the selected lines, or puts the caret between new fences. Hover an icon for its name and shortcut.

  • Find: Cmd+F / Ctrl+F opens a search panel in the source. Undo and redo work as usual.
  • Format: Cmd+B / Ctrl+B and Cmd+I / Ctrl+I wrap the selection in bold or italic markers, or remove them again. Cmd+K / Ctrl+K turns the selection into a link and selects url so you can type the address.
  • Lists: Enter continues a list item (-, *, +, 1., 1)), a task item with a new open checkbox, or a quote. Enter on an empty item moves it out one level, or ends the list. Tab nests the selected items under the item above; Shift+Tab moves them out one level. Shift+Enter is a plain line break. In fenced code and ordinary text these keys keep their usual meaning.
  • Tasks: Cmd+Alt+X / Ctrl+Alt+X, or the task-checkbox icon, adds [ ] to the selected lines, turning plain lines into task items, and checks or unchecks existing ones. This only changes the note’s text; it never completes a task in Productivity’s task views.
  • Layout: Cmd+Alt+P / Ctrl+Alt+P cycles Edit, Split, Preview, Live Edit, and Blocks. In Split, Cmd+Alt+[ and ] (Ctrl+Alt+[ and ]) narrow or widen the source pane; dragging the divider works too.

Live Edit

Live Edit formats the Markdown you are writing in place: headings, bold, italic, strikethrough, inline code and code blocks, links, lists, quotes, and checked task items (dimmed and struck through). The syntax stays in the text. Markers such as #, **, and link addresses are dimmed, and show in full in the block around the caret so you can edit them.

It reads like a page: a centred column of slightly larger, more widely spaced text without a frame. List bullets, numbers, and task checkboxes stay visible in the accent color.

  • / menu: type / at the start of a line for Heading 1–3, Bulleted list, Numbered list, To-do, Quote, Code block, Link, or Divider. Code block puts the caret between its fences and Link where its text goes. Keep typing to filter (/todo), choose with the arrow keys and Enter or a click, or press Escape. The /word is replaced by the block’s Markdown. A / inside a sentence stays text, and Edit and Split have no menu.

  • Checkboxes: click a [ ] or [x] to check or uncheck the item; the caret stays put and the change is an ordinary, undoable edit of the draft.

  • It is the same text as Edit and Split. Switching layouts keeps the draft, selection, and undo history, and never saves or changes the note; copying copies Markdown.

  • Headings are bold and colored but keep the body text size, and syntax is dimmed rather than hidden.

  • Tables, raw HTML, images, and Mermaid blocks stay plain, editable source.

  • Clicking places the caret. Cmd+click (macOS) or Ctrl+click on a link opens it in the browser (http(s) and mailto only); clicking a checkbox is the only click that changes text.

  • Notes over 128 KiB are shown as plain Markdown while typing, because formatting them would trail behind the keyboard.

  • + New Note opens a blank draft with a name field. Create note saves it, even when empty; an existing name is rejected, and a blank name becomes a unique Untitled.md.

  • Linked beside the formatting toolbar in Write (on its own row in Preview) shows the tasks and projects the note is linked to as mini cards. Click one to open its details without losing unsaved task or note text; ← Back to note returns to Write. Links are many-to-many: a note can be linked to several tasks and projects, and a task or project to several notes. Add or remove links in Browse.

  • New note in a saved task’s or project’s details, beside Linked notes, starts the same draft named after the task or project. Create note creates it and links it to that task or project; your unsaved task or project draft stays open. Characters not allowed in a filename, such as /, become -. The button shows only while Notes is enabled.

  • New notes default to today’s journal date; the calendar picker can change or clear it.

  • Productivity stores its metadata as YAML front matter. Notes without metadata ask for consent before the first save adds it.

  • If the file changed on disk, Compare shows the external version, Save local copy writes a separate Recovered-<UUID>.md, and Reload external replaces the draft after a second confirmation.

  • Closing the window or quitting saves a dirty draft first and stops if that fails. Forced termination can still lose unsaved text.

Blocks (early)

Blocks, the layout after Live Edit, is the start of a Notion-style editor. It shows the note as formatted blocks in a centred column: headings, paragraphs, each list item, quotes, code, dividers, tables, and front matter.

  • Click a block to edit its Markdown in place; the field grows with the text. Press Escape or click beside the blocks to finish. Click the empty line below the last block, or press Enter at the end of it, to add a block at the end.
  • Enter starts a new block below, splitting the text at the caret. In a list the new block is the next item (the next number, or an open checkbox after a task); Enter on an empty item ends the list. At the very start of a block, Enter opens a new block above it. Inside a code block Enter is an ordinary line break.
  • Shift+Enter breaks the line inside the block.
  • Backspace in an empty block removes it and continues at the end of the block before.
  • The block being edited has its own formatting strip: bold, italic, inline code, link, quote, and code block. Cmd/Ctrl+B, I, K, and Alt+X work there too.
  • Type / at the start of a line in a block for the same menu as Live Edit, shown under the block: Up/Down choose, Enter inserts, Escape closes it.
  • Links are blue; Cmd+click (macOS) or Ctrl+click opens one in the browser, and a plain click edits the block. Only http(s) and mailto links open.
  • The note is drawn as a page, apart from the app around it.
  • Click a task’s checkbox to check or uncheck it without opening the block.
  • It edits the same draft as the other layouts: every change is in the draft at once, and autosave and Save work as usual. Only the edited block’s text is replaced; blank lines and everything else stay exactly as written.
  • If the block’s text changes elsewhere while you edit it, the block closes instead of overwriting that change. Notes over 128 KiB and notes with an unresolved conflict are edited in the other layouts.
  • Not yet: arrow keys between blocks, undo across blocks, and dragging blocks.

Images

The insert image icon in the formatting toolbar copies a PNG, JPEG, GIF, or WebP file (up to 20 MiB) into the folder’s assets/ directory, under a new name if one is taken, and inserts a relative link at the caret. Previews show relative images that stay inside the notes folder. Remote, absolute, SVG, and out-of-folder images stay inert placeholders. Other attachments are ordinary links; Productivity has no viewers for them.

Import and export

Both copy files and never replace existing ones.

  • Import… in Browse copies Markdown files or folders from outside the notes folder.
    • A folder becomes a new top-level folder with the same name (Name 2 if taken). It keeps its Markdown files and images at their relative paths. Other files and symbolic links are skipped.
    • A file goes into the notes folder’s root (name 2.md if taken), along with the images it links inside its own folder. If one of those image paths already holds a different file, the note is skipped. Import its folder instead.
    • Imported files are copied byte for byte. A file whose Productivity ID is already used in the library is the exception: its copy gets a new ID. Links and shortcuts are never copied, and metadata-free files stay metadata-free.
  • Export all… in Browse, or Export… in a note’s preview toolbar, copies notes and the local images they reference to a folder you choose. Paths stay relative to the notes folder, so image links keep working in other Markdown apps. If any target file already exists, nothing is written. The export holds only Markdown and images. Task and project links and shortcuts stay in the database (see Data, backups, and logs).

Recovery and deletion

Recovery in Browse lists copies kept outside the notes folder: drafts whose save failed, conflicting local edits, interrupted operations, and deleted notes. For each entry you can View its text, Save as new note (a Recovered-<UUID>.md file with a fresh ID), Restore a deleted note to its original path (only if that path is free), or discard it after a second confirming click. Entries stay until you discard them.

The delete (trash) icon in the editor works on a saved note with no unsaved changes, after Confirm delete. The file’s content moves to Recovery. Browse keeps listing the note as missing so its links and shortcuts survive a restore.

Supported Markdown

Previews follow CommonMark plus common GitHub extensions: tables, task lists (read-only), strikethrough, and fenced code. Raw HTML is never executed. Links in the preview are inert; safe http, https, and mailto links appear as separate Open buttons that need a click. Productivity does not render Obsidian wikilinks or plugin syntax, but keeps such text unchanged in the file.

Mermaid diagrams

A fenced code block whose language is mermaid appears as a diagram in every preview:

```mermaid
flowchart LR
  Idea --> Task --> Done
```
  • Rendering: diagrams are drawn by merman, a native Rust implementation of Mermaid. No JavaScript, browser, or network access is involved. They follow Day or Night appearance and re-render when it changes. Labels are sized with the fonts installed on your computer, so the first diagram after starting the app can take a moment longer while they are found.
  • Diagram types: flowcharts, sequence, class, state, ER, Gantt, pie, journey, timeline, mindmap, Git graph, quadrant, XY, sankey, C4, architecture, block, packet, requirement, kanban, radar, treemap, and others that merman supports.
  • Errors and limits: while a diagram renders, or if it is invalid, the preview shows its source, with a short error below an invalid block. Diagrams over 64 KiB, or that take more than 3 seconds, are not drawn. Errors never affect saving.
  • Differences from other apps: the file keeps the block unchanged, so other Markdown apps render it their own way. Output can differ slightly from mermaid.js, and the ELK layout is not included, so layout: elk uses the default layout. click links and callbacks are removed, and diagrams cannot load images or other files.

Editing outside Productivity

The notes folder is ordinary files. You can edit, add, rename, or delete notes in other apps, and Browse follows those changes. A clean editor reloads an external change automatically. A dirty editor reports a conflict instead (see Compare above). Productivity checks the file right before replacing it, but it cannot lock files against other editors. Saving in two apps within the same instant can still lose one of the edits. File interoperability is not sync, so do not point two running copies of Productivity at the same database.

Shortcuts

Star or unstar notes from Browse or a preview. Starred notes appear in the sidebar’s Shortcuts section: drag them to change their order, or click one to open it. The star next to the opened note’s edit button removes the shortcut without deleting the file. There is no separate shortcut-management screen. Legacy groups appear as one deduplicated list; unstarring removes a shortcut from every group, including when its note is unavailable.

Settings

Open Settings with the gear at the bottom of the sidebar (Cmd+, / Ctrl+,). Settings never touches an open task draft.

  • Views: show or hide each task view, Insights, and Notes. At least one task view stays shown; Insights and Notes do not count toward it. Hidden views leave the sidebar, menus, and shortcuts; startup opens the first shown view.
  • Appearance:
    • Theme: System follows your computer’s light or dark mode and switches with it; Day and Night always use the light or dark colors.
    • Color scheme: Forest (green) or Ocean (blue), each with day and night colors.
    • Compact design: tighter spacing for small screens.
    • Font: the font for all text. System default uses your computer’s interface font (San Francisco on macOS). Some fonts cannot draw bold text in Productivity: Ubuntu 26.04 installs its Ubuntu font only as a variable font, and bold text would look regular. System default then uses the first installed of Noto Sans, DejaVu Sans, Liberation Sans, or Cantarell, and a note under the setting says so. The list is searchable and offers only installed fonts that have a real bold face. If a chosen font is uninstalled later, System default is used until it returns.
  • Calendar: Week numbers shows ISO week numbers, Work week only hides non-working days, and Working days picks which days count as working days. See Calendar.
  • Day planner: choose Workday start and Workday end in 15-minute steps, defaulting to 06:00–22:00. Start must be before End; 24:00 is allowed as the end. These saved local-time preferences control Today’s visible range, not task dates or calendar working days. Saved out-of-range timeboxes remain visible. See Today.
  • Workspace data: Load example replaces all tasks and projects with a small example workspace dated around today, and Reset to empty removes them. Both need a second click to confirm, are refused while a draft has unsaved changes, and cannot be undone. Settings, the notes folder, and Markdown files are kept.
  • Danger zone → Clear all data returns Productivity to a fresh install. It deletes the database (all tasks, projects, settings, remembered note folders, and note links), the note recovery copies, and the logs, then restarts with an empty workspace and default settings. Check Also delete the notes and images to delete the Markdown notes and the assets/ images of the current notes folder too (off by default). Other files in that folder, such as a Git repository or PDFs, are kept, and only folders left empty are removed. Earlier note folders and exported files are never touched. It needs a second click, is refused while a task, project, or note has unsaved changes, and cannot be undone. The files are deleted after the app has closed its database and log; if anything cannot be deleted, the restarted app says so.

About, below Settings, shows the version, the commit it was built from (with a link to it on GitLab), the repository link, a Report a bug or request a feature button that opens the project’s issues on GitLab, and a Productivity book button. The book opens this online user guide in your default browser and requires an internet connection; it is not bundled offline help. Opening About or following its links preserves unsaved task drafts.

Release notes in About opens this version’s release page on GitLab (the list of releases for a build you made yourself). After a check that finds a newer release, What’s new in … opens that release’s page.

Check for updates in About compares your version with the latest published release and says whether you are up to date, a newer version is available, or your build is not a published release (for example, one you built yourself). It is the app’s only network request and runs only when you press the button. It reads one small public file, release-identity.json, over HTTPS, verified with your system’s certificates. It sends no version, identifier, or other information about your installation; like any web request, the server sees your IP address. It never downloads or installs anything: update through APT or the installation guide.

Keyboard shortcuts

ActionmacOSLinux
New taskCmd+NCtrl+N
Save task or noteCmd+SCtrl+S
Today plannerCmd+1Ctrl+1
ListCmd+2Ctrl+2
Eisenhower matrixCmd+3Ctrl+3
Kanban boardCmd+4Ctrl+4
ProjectsCmd+5Ctrl+5
CalendarCmd+6Ctrl+6
Notes BrowseCmd+7Ctrl+7
InsightsCmd+9Ctrl+9
Note editorCmd+Shift+7Ctrl+8
SettingsCmd+,Ctrl+,
Previous / next note in Browse↑ / ↓↑ / ↓
Find in noteCmd+FCtrl+F
Bold / italic / link in noteCmd+B / Cmd+I / Cmd+KCtrl+B / Ctrl+I / Ctrl+K
Cycle Edit, Split, PreviewCmd+Alt+PCtrl+Alt+P
Narrow / widen Split sourceCmd+Alt+[ / ]Ctrl+Alt+[ / ]
QuitCmd+QCtrl+Q

Line editing

These work as in VS Code in the note editor and in a task’s Notes field. They act on every line the cursor or selection touches, and one Undo reverts each.

ActionmacOSLinux
Move line up / downAlt+↑ / ↓Alt+↑ / ↓
Copy line up / downShift+Alt+↑ / ↓Ctrl+Shift+Alt+↑ / ↓
Delete lineCmd+Shift+KCtrl+Shift+K
Insert line below / aboveCmd+Enter / Cmd+Shift+EnterCtrl+Enter / Ctrl+Shift+Enter
Select line (repeat to extend)Cmd+LCtrl+L
Add cursor above / belowCmd+Alt+↑ / ↓Shift+Alt+↑ / ↓
Indent / outdent lineCmd+] / Cmd+[Ctrl+] / Ctrl+[

GNOME, Ubuntu’s default desktop, reserves Ctrl+Shift+Alt+↑ / ↓ for moving the window to another workspace and receives them first, as it does for VS Code. Free them under Settings → Keyboard → View and Customize Shortcuts → Navigation to copy lines with them.

Enter in a task title saves the task. In Notes, Cmd+S / Ctrl+S saves the note and never a hidden task or project draft. Hidden views ignore their shortcuts.

Data, backups, and logs

Where data lives

PlatformDatabase
macOS~/Library/Application Support/productivity/tasks.sqlite3
Linux$XDG_DATA_HOME/productivity/tasks.sqlite3 (default ~/.local/share/…)

Set PRODUCTIVITY_DATA_DIR to use a separate workspace, for example for testing:

PRODUCTIVITY_DATA_DIR="$HOME/productivity-test" cargo run --locked

Backups

Quit the app, then copy tasks.sqlite3. When Notes is in use, back up the Markdown folder and .productivity-recovery together with the database: the note index can be rebuilt, but links and shortcuts cannot. Recovery copies are kept until you discard them.

Back up the database and the notes folder at the same time, while the app is closed, so links and shortcuts match the notes. Restoring only the Markdown folder brings back note content and IDs, but not links, shortcuts, or sorting. Rebuilding the index never restores them. Export all… in Notes copies Markdown and images only. It does not replace a backup of the database.

To delete everything the app stores, use Settings → Danger zone → Clear all data (Settings).

Run one app instance per database, and do not sync the live database through a file-sync service. If the database cannot be opened, the app exits with an error rather than replacing it.

Schema migrations

The database schema is versioned with SQLite’s user_version and migrated in one transaction at startup; a database from a newer version is refused. Every migration preserves existing tasks, projects, dependencies, and settings except explicitly retired preferences.

VersionChange
2Status replaces the completed flag (open → To do, completed → Done)
3–4Settings; only the task-list completion preference is kept
5–6Projects and dependencies; the abandoned related-link table is removed
7Per-view visibility, all shown
8Optional start dates
9Notes visibility, hidden
10–12Note index, associations, shortcuts, recovery journal, and a constraint repair
13–14Archiving and Today planning
15Compact design preference
16Task type, existing tasks become Task
17Appearance and color scheme preferences
18Calendar week-number preference, hidden by default
19Full/work-week display and configurable working days
20Today view visibility and timeboxes; retires List’s completed-visibility preference
21Saved Today workday start/end times, default 06:00–22:00
22UI font preference, System default unless chosen
23Task status history for Insights (existing tasks get a baseline entry) and Insights visibility, shown
24Today’s part of the day and manual order for planned tasks; existing plans become Anytime
25An optional web link per task, such as a Jira issue or GitLab merge request
26Merge request, Issue, and Jira task types (the task table is rebuilt; all data kept)
27Plans made ahead for tomorrow; existing plans keep counting today
28Kanban column order and hidden columns, defaulting to all four in status order

Logs

Logs go to stderr and to logs/ inside the data directory. Files rotate daily or at 2 MiB, and at most seven are kept. Set RUST_LOG to change verbosity (default warn,productivity=info):

RUST_LOG=warn,productivity=debug cargo run --locked

The log file, stderr, and Insights → Logs receive the same events: Productivity’s own and, so that problems inside libraries such as GPUI are visible too, the warnings and errors of its dependencies. Productivity’s own events contain no task titles, note contents, or paths, but dependency messages may include file paths or other details, and IDs and timings can be sensitive as well, so review logs before sharing them. The files are readable only by you.

Startup and shutdown timing

Each launch logs startup steps with elapsed_ms since the process started: data loaded, platform ready, window created (the window and GPU renderer exist), main window opened, and first frame drawn. Quitting logs quit requested with how it was asked (window close, title bar close, or the Quit action), then shutdown steps with elapsed_ms since that request: closing windows, releasing workspace, and event loop finished. The process still flushes the log and lets the graphics driver clean up after the last line, which no log can show.

To look at a slow start or exit of an installed app (for example from the APT package):

  1. Start it from a terminal, then close it as usual. The second command prints when the process really ended, in UTC like the log:

    productivity; date -u +%H:%M:%S.%N
    

    The gap between the event loop finished line and that time is spent after the log ends. To also log the graphics adapter GPUI chooses, start it with env RUST_LOG=info productivity instead.

  2. Read the newest file in ~/.local/share/productivity/logs/:

    grep -E "startup|shutdown|quit requested" \
      "$(ls -td ~/.local/share/productivity/logs/* | head -1)"
    
  3. When started from the application menu instead, stderr goes to the user journal: journalctl --user -b | grep -i productivity.

On laptops with two GPUs, also note the output of lspci | grep -iE 'vga|3d'.

Building and packaging

Build on the target OS and architecture; nothing here cross-compiles, installs, or launches the app automatically.

cargo build --release --locked          # target/release/productivity
uv run --locked python tools/package.py  # launcher-ready bundle in dist/

The release profile uses whole-program LTO, a single codegen unit, and stripped symbols to keep the executable small (about 40 MB on macOS instead of 63 MB). A clean release build therefore takes several minutes; use cargo run for day-to-day development.

  • macOS: dist/Productivity.app, with icon and bundle metadata, ad-hoc signed and verified after assembly. Copy it to /Applications to install. Ad-hoc signing uses no certificate; public distribution still needs Developer ID signing and notarization.

  • Linux: dist/productivity-linux/, a staged tree with the executable, .desktop file, and icons. Install it for your user with:

    data_dir="${XDG_DATA_HOME:-$HOME/.local/share}"
    install -Dm755 dist/productivity-linux/bin/productivity "$HOME/.local/bin/productivity"
    install -Dm644 dist/productivity-linux/share/applications/dev.productivity.desktop.desktop \
      "$data_dir/applications/dev.productivity.desktop.desktop"
    install -Dm644 assets/branding/app.svg \
      "$data_dir/icons/hicolor/scalable/apps/dev.productivity.desktop.svg"
    

Install uv before running the Python helpers; it manages their environment and interpreter. See Python tooling.

uv run --locked python tools/package.py --profile debug --no-build packages an existing debug build.

Distribution packages

These use pinned Cargo extensions.

# Ubuntu .deb (needs dpkg-dev and xz-utils)
cargo install cargo-deb --version 3.8.0 --locked
cargo build --locked --release --bin productivity
cargo deb --no-build --output target/debian/productivity-local.deb

# macOS .dmg
cargo install cargo-bundle --version 0.12.0 --locked
cargo build --locked --release --bin productivity
cargo bundle --release --format dmg --binary-path target/release/productivity

Generate a matching Cargo dependency SBOM locally:

uv run --locked python tools/supply_chain.py install
uv run --locked python tools/supply_chain.py
cargo build --locked --release --bin productivity --no-default-features --features desktop
uv run --locked python tools/supply_chain.py sbom --binary target/release/productivity

target/sbom/productivity-<target-triple>.cdx.json records the manifest version and executable hash. CI uploads this sidecar with each package; it is not embedded in the .deb/.dmg. Pages publishes the Ubuntu release SBOM alongside the book, coverage report, and APT repository; see SBOM and dependency policy. See Development for policy, target selection, maintenance warnings, and inventory limitations.

Use --format osx for just the .app. These are unsigned, native-architecture builds. The Debian maintainer contact still needs to be chosen before a public release.

GitLab Releases from CI

After all earlier stages (including signed APT/Pages publication) succeed, release-gitlab publishes the same Ubuntu 26.04 amd64 build to GitLab’s Deploy → Releases and Deploy → Package registry. These features are available on GitLab.com Free. The existing scheduled-pipeline restriction remains in effect; setting AUTO_PIPELINES=true also permits default-branch push releases.

The job uses release-identity.json’s rolling version to create v<version> at the exact packaged commit, without committing the CI-only Cargo version stamp. Its download links point to the versioned Generic Package Registry, not expiring job artifacts or the latest-only Pages download. Each release retains the .deb, CycloneDX SBOM, build identity, Grype/RustSec reports, archive public key, and a flat SHA256SUMS file for those downloads. Direct downloads remain unsigned; prefer the signed APT repository. macOS CI remains opt-in and is not attached: it currently produces development-version, unsigned/non-notarized packages.

Each release page ends with release notes generated by tools/release_notes.py from the Conventional Commits since the newest earlier release on the mainline (merge commits are left out; the first release covers the whole history). Commits are grouped by scope, the part in parentheses such as notes in feat(notes): …, sorted by name with unscoped commits last under General. Within a scope they are ordered from most to least significant: Breaking (a ! after the type or a BREAKING CHANGE: footer), Feature, Fix, then Performance, Refactor, Revert, Docs, Style, Tests, Build, CI, Chore, and Other for anything else. Subjects are escaped so they cannot add links, HTML, or @mentions. Preview the notes locally without publishing:

uv run --locked python tools/release_notes.py --commit "$(git rev-parse HEAD)" \
  --since "$(git rev-parse HEAD~10)"

Project setup:

  • Keep the default branch protected. Only push/scheduled pipelines on that branch can publish; the remote tip is checked again before creating a release.
  • Enable the project’s Package registry. For public, login-free downloads, make the project and its package registry publicly accessible.
  • The pipeline/schedule owner needs permission to publish packages and create releases/tags (at least Developer; protected v* tags may require Maintainer). The job authenticates with the built-in CI_JOB_TOKEN: no personal token, Git-push permission, or new signing secret is needed.
  • Exclude release packages from any registry cleanup policy if old downloads must remain available. Registry packages have no job-artifact expiration, but manual deletion/cleanup still removes them. Retained versions consume storage.

Publication shares the APT deployment’s resource lock and refuses stale builds, wrong identities, or a tag belonging to another commit. A repeated schedule for an already-published version leaves the release and its packages untouched, even if a rebuild’s bytes differ. After an interrupted upload, retry the same job to resume identical files; conflicting existing bytes fail rather than being replaced. Do not delete or move release tags/packages to work around a conflict without first investigating it. No release or upload occurs during local tests.

Tools

  • tools/package.py builds and assembles the bundles above.
  • tools/brew_local.py creates the local Homebrew cask and archive.
  • tools/release_identity.py and tools/stamp_release.py assign CI package versions.
  • tools/gitlab_release.py publishes successful CI builds to the registry and Releases.
  • tools/release_notes.py writes the release notes from Conventional Commits.
  • tools/generate_icons.py regenerates committed icons with uv’s optional icons group (Pillow).
  • tools/coverage.py produces the coverage reports.
  • tools/supply_chain.py checks licenses/RustSec and generates CycloneDX SBOMs.

None of them are part of the running app or read task data.

Development

Checks

cargo fmt --all --check
cargo test --locked --no-default-features
cargo test --locked --features ui-tests
cargo check --locked
cargo clippy --locked --all-targets --all-features -- -D warnings
uv run --locked python -m unittest discover -s tools -p 'test_*.py'
uv run --locked python tools/supply_chain.py

Core and storage tests need no graphical environment. The ui-tests feature runs GPUI’s test platform without opening windows.

Optimized local builds

The release profile uses fat LTO and a single code-generation unit for the smallest, fastest packages, so large crates and the final link compile on one core and take minutes. For an optimized build to try locally, use the fast-release profile instead; thin LTO and parallel code generation use every core, at the cost of a slightly larger and marginally slower binary:

cargo run --profile fast-release --locked

Its output is in target/fast-release/. Packaging and CI keep using release. To see which crate is compiling, add -v; cargo build --timings writes a report to target/cargo-timings/.

Python tooling with uv

Install uv 0.11.30 or newer. From the repository root, uv run --locked python … creates .venv/ and uses the Python 3.13 series selected by .python-version, downloading it if needed. No manual environment activation or global pip install is needed. pyproject.toml and the committed uv.lock define the tooling environment; --locked refuses dependency changes rather than rewriting the lockfile.

Normal checks, packaging, and SBOM helpers use only the standard library. The optional icons group contains Pillow (Python 3.11+):

uv sync --locked                         # prepare the standard tooling environment
uv lock --check                          # verify metadata and lockfile agree
uv run --locked --group icons python tools/generate_icons.py

Icon generation rewrites committed branding files; it is not part of ordinary builds. To change Python dependencies intentionally, use uv add --group icons … (or another appropriate group), or uv lock --upgrade-package pillow, and review both pyproject.toml and uv.lock. Rust crates and the pinned Cargo extensions are still managed by Cargo, not uv, and are not Python dependencies. Cargo’s SBOM and RustSec checks do not inventory or audit optional Python packages; their versions and archive hashes are recorded separately in uv.lock.

CI bootstraps uv 0.11.30 into .ci-tools/bin/ without modifying shell profiles, checks the lockfile, and uses the same locked commands. Per-job tool caches retain uv, managed Python, and .uv-cache/; .venv/ is recreated, not cached. The SAST and Secret Detection jobs remain independent of this environment.

Dependency licenses, RustSec, and SBOMs

Install the pinned tools explicitly (into the ignored .ci-tools/ directory), then run the same workflow as CI:

uv run --locked python tools/supply_chain.py install
uv run --locked python tools/supply_chain.py

The runner requires cargo-deny 0.20.2 and cargo-cyclonedx 0.5.10. Normal checks never install tools, build or launch the app, or access task data. They need network access to fetch crate metadata and the current RustSec database.

  • Licenses: dependency_policy.toml checks normal, build, and dev dependencies with all application features across arm64/x86-64 macOS and GNU/Linux. Its explicit allowlist captures the existing dependency baseline: 0BSD, Apache-2.0, BSD-2-Clause, BSD-3-Clause, CC0-1.0, ISC, MIT, Unicode-3.0, and Zlib. Existing MPL-2.0 dependencies have exact-version exceptions, not blanket approval. New licenses, unlicensed dependencies, and MPL upgrades require review. GPL/AGPL/LGPL/EPL are not approved; a crate offering Apache-2.0 OR GPL-2.0-only can still pass using Apache-2.0.
  • RustSec: cargo-deny fetches the community-maintained RustSec advisory database and checks the same dependency graph. Known vulnerabilities, unsoundness, and yanked releases fail the check; unmaintained-crate advisories are visible warnings. The runner passes check --warn unmaintained for this distinction. There are no advisory exemptions. This detects published advisories, not every vulnerability or abandoned crate. Existing maintenance warnings in the GPUI/Mermaid dependency trees need upstream replacements; they are not silently suppressed.
  • SBOM: CycloneDX 1.6 JSON describes the desktop binary’s transitive Cargo dependencies for the host target with exactly --no-default-features --features desktop, not ui-tests or an all-platform lockfile inventory. Build dependencies are retained (CycloneDX marks them excluded, rather than required at runtime). Components include license expressions, package URLs, registry archive checksums, and dependency relationships. Target, features, and the lockfile’s SHA-256 are recorded in metadata properties.

To scan an SBOM for known vulnerabilities as the release pipeline does, install the pinned Grype (0.121.1, checksum-verified, into .ci-tools/bin) and scan:

uv run --locked python tools/vulnerabilities.py install
uv run --locked python tools/vulnerabilities.py scan target/sbom/productivity-x86_64-unknown-linux-gnu.cdx.json

The report is target/vulnerabilities/grype.json; Grype downloads and caches its database in .ci-tools/grype-db. Findings are reported, not fatal. Upgrading Grype means updating GRYPE_VERSION and every pinned archive checksum in tools/vulnerabilities.py together.

The SBOM is generated, not committed: target/sbom/productivity-<target-triple>.cdx.json. Its application version comes from the current manifest, including CI’s stamped Ubuntu release version. Cargo validates locked resolution before generation; because cargo-cyclonedx has no --locked option, the runner also rejects lockfile changes before publishing the output. Basic identity/content checks are not full schema validation.

Individual operations:

uv run --locked python tools/supply_chain.py licenses
uv run --locked python tools/supply_chain.py advisories
uv run --locked python tools/supply_chain.py sbom --target x86_64-unknown-linux-gnu
# After building the matching desktop release, also identify its executable:
uv run --locked python tools/supply_chain.py sbom --binary target/release/productivity
# Inspect the crate/license inventory:
.ci-tools/bin/cargo-deny --locked --config dependency_policy.toml list --layout crate

Cross-target SBOM generation reads metadata; it does not cross-compile or prove that a target builds. --binary records the supplied executable’s SHA-256; the caller must supply the binary built with the documented target/features.

This is a Cargo dependency SBOM, not a complete inventory of bundled C sources, system libraries, the Rust standard library, fonts, icons, or packaging tools. In particular, bundled SQLite is represented by libsqlite3-sys, not as a separately inventoried SQLite component. Assets/native code and required license notices still need review. License checks are based on crate metadata and license files, not a legal determination.

Productivity itself is licensed under the Apache License 2.0. It is marked publish = false (not published to crates.io); the same policy checks its own license like every dependency’s.

Example data

Create a separate database with the example workspace, for screenshots or manual testing:

cargo run --locked --example seed_demo -- /tmp/productivity-demo/tasks.sqlite3
PRODUCTIVITY_DATA_DIR=/tmp/productivity-demo cargo run --locked

seed_demo refuses existing files, so it never touches real data.

Coverage

rustup component add llvm-tools-preview
cargo install cargo-llvm-cov --version 0.9.1 --locked
uv run --locked python tools/coverage.py

This writes an HTML report with function, line, and region coverage per file to target/coverage/html/, plus a Cobertura file. Branch coverage would need nightly Rust, which the project does not use.

Architecture

Workspace coordinates navigation and shared task/project data. Feature-local session state and initialization live in NotesState, TodayState, and CalendarState; shared project/type/status filters remain at workspace scope. These are plain owned structs, not independent stores or competing editor buffers.

Asynchronous results are matched to their request by an explicit identity (a generation counter plus the target note, library, or editor), never by the status text currently shown. Confirmations for destructive actions are their own state; a new status message disarms them but never authorizes them.

Rendering never parses note Markdown. The note editor advances one content generation per edit or source replacement; Live Edit formatting (src/ui/notes/live.rs) and the read-only preview (src/ui/notes/editor_preview.rs) are prepared off the UI thread after typing pauses and are applied only to the generation they were prepared from. Layouts without a preview pane skip preview preparation.

Task, project, planning, and workspace-replacement writes return the collections they committed, read inside the same transaction (for example TodayPlan, ProjectRemoval, WorkspaceData); the UI applies those results instead of reloading separately, so a failed reload can never be reported as a failed write. Immediate task changes (status, priority, project) go through Workspace::change_task, which refuses them over a dirty draft, persists first, and refreshes a clean editor from the saved task.

src/storage/database.rs owns connection settings, schema-version checks, and migrations for the one shared SQLite file. TaskStore and NoteStore each open their connection through it and do not depend on each other.

All screens use src/ui/screen_layout.rs for their date/title header, actions, status toolbar, content spacing/scroll container, errors, and footer. Supply screen-specific content and controls through its slots rather than building another header or toolbar frame. The editor density reduces padding and omits the subtitle; it cannot hide the current local day or title. Keep screen selection and task/note state in Workspace, not in the layout.

When adding a view, extend the cross-screen layout test. It checks shared header alignment, action bounds, and toolbar/content placement in normal and compact mode at 1000×640, 1320×840, and 1920×1200. Existing-note editing has the same coverage. Each screen also declares its ContentFit in Workspace::content_fit. Board-like screens (Today, Matrix, Kanban, Calendar, Notes Browse, Notes Write) Fill the space between toolbar and footer and scroll inside their own regions, so size them with flex_1().min_h_0() rather than fixed heights. Document-like screens Flow and scroll as a page. Either may scroll sideways when its minimum width exceeds the window. Layout tests check that every Fill screen ends above the footer at several sizes and that wide screens scroll horizontally.

src/
  core/          Task and project rules, dependencies, notes, settings types
  application/   TaskService and NoteService: the API used by the UI
  storage/       SQLite persistence, migrations, note indexing
  ui/            GPUI views and UI tests
  desktop/       Startup, menus, window setup, embedded assets
assets/          Icons and branding
packaging/       Platform launcher templates
tools/           Packaging, coverage, and icon helpers
book/            This documentation

Dependencies point UI → application → core/storage. The UI never touches SQLite, and the core builds without GPUI (--no-default-features) for future clients and sync adapters.

GPUI comes from gpui-pre and gpui-pre-platform, pinned to the exact snapshot that GPUI Component requires; upgrade them together.

Continuous integration

Pipelines currently run only when started from a GitLab pipeline schedule, to save compute minutes: create a schedule for main (it can stay inactive) and use its Run button. Pushes and merge requests do not start pipelines. To restore automatic pipelines, set the project CI/CD variable AUTO_PIPELINES to true (or change its default in .gitlab-ci.yml). Scheduled pipelines on main also package and publish Pages.

GitLab CI runs GitLab SAST and Secret Detection, the checks above on Linux, coverage, an Ubuntu 26.04 .deb, and this book. On main, Pages publishes the book together with the signed APT repository, coverage report, and release SBOM. The book’s opening page is the site landing page; existing book and APT URLs are unchanged. The coverage badge links to the latest successfully published HTML report.

macOS jobs are opt-in: set RUN_MACOS_CI=true once a macOS shell runner tagged macos is available (with GnuPG installed for the signing tests). They run the checks and build an unsigned .dmg. CI never signs or notarizes macOS builds and never installs anything.

The pages job signs the APT repository’s Release file with tools/apt_sign.py. The certify-only primary key is kept offline on a hardware token; CI holds only a signing subkey (APT_SIGNING_KEY, base64 of the armored export, and APT_SIGNING_PASSPHRASE), as protected, masked CI/CD variables scoped to the apt-signing environment. The job verifies InRelease and Release.gpg with gpgv against packaging/apt/productivity-archive-keyring.asc and fails without publishing if the variables are missing or the signature is wrong.

The supply-chain job gates both package jobs with license and RustSec checks, and uploads a host-target CycloneDX SBOM as an artifact/report. Each package job generates its own SBOM after building, with the actual release version and executable hash, and uploads it alongside its .deb/.dmg. The SBOM is a sidecar artifact, not embedded in those packages. Pages publishes the Ubuntu package job’s release SBOM, not the unstamped check-job SBOM. GitLab’s display/ingestion of CycloneDX reports depends on the server version and subscription.

tools/pages.py stages the book at the site root, HTML coverage and Cobertura XML under coverage/, the Ubuntu SBOM under sbom/, a current installer page under downloads/, and the package at its existing pool/ path. release-identity.json and SHA256SUMS identify the publication’s inputs. Checksums are not signatures. The staging step refuses an existing output directory, mismatched release/SBOM versions, wrong targets, missing executable hashes or reports, and stale packages. Pages explicitly downloads artifacts from book, coverage, and package-ubuntu in the same pipeline. The existing serialized deployment and latest-main guard remain.

To stage already-generated artifacts locally without installing or publishing:

uv run --locked python tools/pages.py --output target/pages-preview

Inputs default to the CI artifact locations; use --help to select other paths. The output must not exist. This assembles the site and package files; Linux CI then creates the dists/ APT metadata with dpkg-scanpackages and apt-ftparchive. It does not sign the repository or verify graphical installation. Report links will not resolve in a plain mdBook-only build.