OKF Todo

Version 1.0.0. The first stable release is packaged for Windows. The application applies pending database migrations at startup when necessary.

Turn existing work notes into a task plan with your AI assistant, then manage the tasks in OKF Todo—a free, open-source desktop application for development and support work.

Start with an Excel spreadsheet, a screenshot of existing tasks, or other material your assistant can read. Ask it to propose tasks and checklists, review the plan, then approve saving it to OKF Todo. The assistant interprets the source; OKF Todo stores the resulting work in a local SQLite database.

AI-assisted planning requires a separate assistant with access to local tools and the ability to read your chosen input. OKF Todo does not include an AI model or an automatic spreadsheet/email importer. The desktop app also works offline without an assistant; an external AI service has its own account, pricing, and data-handling rules.

Watch: Excel notes to an OKF Todo plan — 83 seconds

Watch on YouTube · Read the worked example and transcript

Fictional data; planning and approval replayed; actual application captures through a browser test host. Captioned, with no audio. Capture details and current limitations.

• Download OKF Todo for Windows
• Try the sample spreadsheet — workbook, setup, and prompts.
• Give feedback — tell us what you tried and where the workflow helped or got in the way.

From source material to saved tasks

Open Help → OKF layer → Copy prompt in the running app. The prompt includes the actual instruction-file and active database paths for your installation, including a custom database. Give your assistant access to those locations, then provide the source material. See the setup guide.

The Open Knowledge Format (OKF) instructions describe how to work with the task data. The optional MCP server and CLI commands let the assistant act through application services.

OKF Todo is designed to help an AI assistant with access to local tools turn unstructured work into practical artifacts. Give Codex, Claude Code, or another compatible assistant a customer email thread, support transcript, meeting notes, diagnostic output, or similar source material and ask it to prepare an internal task, investigation plan, customer reply, handover, status update, or another useful artifact.

The application is not dependent on AI. It also works as a traditional desktop To-Do application where you can create, organize, update, and complete tasks entirely through the user interface. No hosted account is required, and your data remains local. See Using OKF Todo day to day for the complete end-user workflow.

For AI-assisted work, the recommended workflow is draft, review, save, verify: ask the assistant to analyze the source without changing anything, review its proposal, explicitly approve any task creation or update, and then read the saved result back. The OKF user guide and MCP user guide provide complete examples and reusable prompts.

An AI assistant can work with OKF Todo in several ways:

• OKF knowledge layer: give the assistant structured context about OKF Todo's concepts, schema, relationships, integrity rules, and lifecycle conventions. OKF provides knowledge and navigation; it does not itself grant access to task data or perform updates.
• MCP server: let an MCP-compatible client list, read, create, and update tasks and inspect their timelines through structured tools.
• CLI commands: let people, scripts, and agents execute application commands from a terminal.
• Direct SQLite access: let a user, script, or assistant read or write the local database directly when it has permission to access the file and a SQLite-capable tool.
• Desktop interface: use every task-management feature manually without an AI assistant.

The desktop interface, CLI, and MCP server use the same application services, so their changes consistently apply validation, lifecycle rules, and automatic task history. Direct SQLite writes are also possible, but they bypass those services; the caller is therefore responsible for preserving data integrity and recording any required history.

The desktop application, OKF, and MCP Markdown guides are also the source for the offline in-app Help. The desktop build copies and renders them locally so repository and application guidance stay synchronized.

Coming Next

Planned improvements:

• Calculation of initial editor height based on screen resolution.
• Possible inspiration points from MS To Do: Lists, flags and stars.
• Packaged installers for macOS and Linux. Version 1.0 remains Windows-only.

It is designed for the work that often falls between formal systems: production errors, support cases, deployment checks, investigations, ideas, notes, requests, and follow-up tasks. The application runs locally, requires no account or cloud service, and keeps tasks, history, images, and attachments together in one SQLite database.

Product Highlights

Explore the screenshot gallery — task views, Markdown editing, checklists, dark mode, and backups.

• Fast task capture with only a title and task type required.
• Active, ready, urgent, waiting, overdue, completed, and all-task views.
• HTML and Markdown-capable rich-text editors.
• Paste, drop, or select images for task bodies.
• Priorities, deadlines, waiting targets, tags, and optional source references.
• Checklists with progress shown in the task list.
• User-managed task lists with a persistent list switcher, global All lists scope, safe deletion, and bulk moves with Undo.
• File attachments stored inside the SQLite database.
• Typed relationships between tasks.
• A combined timeline of comments and automatic change history.
• Editable task types, priorities, and statuses.
• Light and dark color schemes with flexible desktop layouts.
• Complete database backup from inside the application.
• Offline in-app Help for the desktop application, OKF layer, and optional MCP server.

Install on Windows

Windows users can get OKF Todo from Microsoft Store or download the signed Inno Setup installer from the latest GitHub release.

The GitHub-hosted installer is Authenticode signed by Open Source Developer Søren Dalby. The Microsoft Store package is signed by Microsoft after certification. Packaged installers are not yet available for macOS or Linux; those platforms remain source-build targets.

Database file

The database is stored under the operating system's local application-data directory:

Do not delete this file unless you intentionally want to remove all application data.

Installing, updating, or removing OKF Todo never overwrites or removes the database. Database replacement is available only through the application's explicit restore and reset workflows.

Requirements

Packaged installation is available for Windows. Source builds require:

• Windows 10 or later, macOS 10.15 or later, or a current Linux desktop distribution.
• The .NET 8 SDK.
• The platform webview used by Photino: WebView2 on Windows, the system WebKit view on macOS, or GTK/WebKit on Linux.

Windows is the packaged and tested platform for version 1.0. The application architecture and Photino shell are cross-platform, but macOS and Linux packaging and release verification are still in progress.

Run the application

Clone the repository, change to its root directory, and run the application using your shell.

For Bash:

git clone https://github.com/dalby-md/OKF-Todo.git
cd OKF-Todo
dotnet restore
dotnet run --project ./Okf-Todo/Okf-Todo.csproj

For Windows Command Prompt:

git clone https://github.com/dalby-md/OKF-Todo.git
cd OKF-Todo
dotnet restore
dotnet run --project .\Okf-Todo\Okf-Todo.csproj

All following dotnet commands in this README assume the current directory is the repository root.

On first launch, OKF Todo creates its database and initial lookup values automatically. No setup wizard or account is required.

On later releases, pending EF Core migrations are applied automatically before the application reads or writes task data.

Connect an MCP client

Build the OKF Todo executable in the repository root:

dotnet build .\Okf-Todo\Okf-Todo.csproj -c Release

Then configure an MCP client to start the built stdio server. For example:

{
  "mcpServers": {
    "okf-todo": {
      "command": "dotnet",
      "args": [
        "C:\\git\\Okf-Todo\\Okf-Todo\\bin\\Release\\net8.0\\Okf-Todo.dll",
        "--mcp"
      ]
    }
  }
}

Adjust the absolute DLL path for your checkout. By default, the server uses the same platform-specific database as the desktop application. It exposes these tools:

task_update has full-replacement semantics for editable fields. Call task_get first and include every value that must be preserved; omitted optional fields are cleared.

For development or isolated tests, start the server with a different database:

dotnet run --project .\Okf-Todo\Okf-Todo.csproj -- --mcp --database-path C:\temp\okf-todo-mcp.db

The MCP protocol uses standard output. Server and framework logs are written to standard error so they do not corrupt the protocol stream.

Back up and restore data

Open Setup, then select Back up database. Choose a destination in the native save dialog. The application creates and validates a complete SQLite backup before replacing the selected destination.

The backup includes task lists, tasks, body images, attachments, lookups, tags, relationships, comments, checklists, and history. Interface preferences such as layout, selected list scope, and color scheme are stored separately and are not included.

Use Settings → Data → Restore from a file to validate a backup, create a safety copy, and prepare the restore. Close and restart OKF Todo when prompted. Never replace the active database manually while the application is running.

Data and Privacy

OKF Todo is a single-user, local-first application. It has no authentication, cloud synchronization, application telemetry, or external task-system integration. Application data stays in the local SQLite database unless you create a backup or save an attachment copy yourself.

Current Limitations

Version 1.0 is the first stable Windows release:

• Windows is packaged and release-tested. macOS and Linux remain source-build targets without packaged installers.
• The direct Windows installer does not provide automatic updates; Microsoft Store installations use Store updates.
• There is no cloud sync or multi-user collaboration.
• Database downgrades are not supported; back up the database before installing an older application version.
• Deep integrations with email, ServiceDesk, Teams, and Azure DevOps are not included.

Use the in-application backup command regularly.

Development

Build the solution:

dotnet build -c Release

Run the test suite:

dotnet test .\Okf-Todo.Tests\Okf-Todo.Tests.csproj -c Release

Restore the repository-local EF Core tool and add a migration after changing the physical model:

dotnet tool restore
dotnet tool run dotnet-ef migrations add <MigrationName> --project .\Okf-Todo\Okf-Todo.csproj --startup-project .\Okf-Todo\Okf-Todo.csproj --output-dir Migrations

Commit the generated migration and model snapshot with the model change. The application applies pending migrations automatically at startup.

Product and architecture documentation is available in docs.

Build the Windows installer

The Windows installer is a self-contained win-x64 Inno Setup package. It installs the unified desktop/command/MCP executable and the OKF context graph.

Install Inno Setup 7 (or compatible Inno Setup 6), then run from the repository root:

.\installer\build-installer.ps1 -Version 1.0.0

Or from Windows cmd:

installer\build-installer.cmd -Version 1.0.0

The installer is written to:

artifacts\installer\Okf-Todo-1.0.0-win-x64-setup.exe

Build the local MSIX feasibility prototype

The experimental MSIX path is independent of Inno Setup and never publishes to Microsoft Store. It reuses the same self-contained win-x64 payload, signs it with a local-only development certificate, and launches against an isolated prototype database.

Both installer builds fail if a database file enters their staged payload. The MSIX and Inno installers contain application files only and never install over the user's database.

Install Microsoft's lightweight Windows App Development CLI, then build and install the package:

winget install -e --id Microsoft.WinAppCli --source winget
.\packaging\msix\build-msix-prototype.ps1 -Version 1.0.0.0 -Install
.\packaging\msix\start-msix-prototype.ps1

See the MSIX prototype guide for upgrade, sample-data, and cleanup commands. The Inno installer remains the direct-download packaging path.

Build the Microsoft Store package

The Store build is separate from the local MSIX prototype and uses the immutable identity reserved in Partner Center. It produces an unsigned .msix; Microsoft signs the package after Store certification, so this path does not require a purchased code-signing certificate.

.\packaging\msix\build-msix-store.ps1 -Version 1.0.0.0

The artifact is written under artifacts\msix-store\output. See the Microsoft Store package guide for the exact identity, validation, versioning, data-safety, MCP-alias, and Partner Center handoff rules.

To publish, merge, and validate the staging payload without compiling the setup executable:

.\installer\build-installer.ps1 -Version 1.0.0 -SkipInstallerCompile

The desktop application, OKF command adapter, and MCP server are provided by the single payload staged under artifacts\installer\staging\core; the installed OKF bundle is staged under artifacts\installer\staging\okf.

For a signed production build, provide the Windows SDK signtool.exe, certificate thumbprint, and optional RFC 3161 timestamp URL:

.\installer\build-installer.ps1 -Version 1.0.0 `
  -SignToolPath 'C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64\signtool.exe' `
  -CertificateThumbprint '<certificate-thumbprint>'

The build signs the unified OKF Todo executable before packaging, then signs the resulting setup executable. Ordinary development builds remain unsigned.

To build and publish the next alpha release in one operation, install and authenticate the GitHub CLI, then run:

gh auth login
.\installer\update_release_exe.ps1

With no parameters, the script finds the highest existing v<major>.<minor>.<patch>-alpha release, increments its patch number, builds that installer version, copies it to the stable <major>.<minor> asset name, creates the new release, and marks it as GitHub's latest release. For example, v0.1.4-alpha produces v0.1.5-alpha, builds Okf-Todo-0.1.5-win-x64-setup.exe, and uploads it as Okf-Todo-0.1-win-x64-setup.exe.

The tag and title identify the build as alpha, but the GitHub release is intentionally not flagged as a prerelease. GitHub excludes prereleases from /releases/latest, so marking it as a prerelease would break the stable installer URL used near the top of this README.

Override the calculated tag when necessary:

.\installer\update_release_exe.ps1 -Tag v0.2.0-alpha

Preview the derived version, asset name, and stable URL without building or contacting GitHub when an explicit tag is supplied:

.\installer\update_release_exe.ps1 -Tag v0.2.0-alpha -WhatIf

For a coordinated Store and GitHub launch, build the tested installer once and create a GitHub draft for the exact release commit:

.\installer\build-installer.ps1 -Version 1.0.0
.\installer\publish-github-release.ps1 `
  -Version 1.0.0 `
  -Tag v1.0.0 `
  -Title 'OKF Todo 1.0.0' `
  -NotesFile docs\release-notes\v1.0.0.md `
  -Draft

The publisher refuses a dirty working tree, targets the current commit, uploads the versioned installer and its SHA-256 checksum, and leaves the release as a draft while Store certification runs. After Partner Center certifies and holds the Store submission, publish that tested draft as GitHub's latest release:

.\installer\publish-github-release.ps1 `
  -Tag v1.0.0 `
  -PublishDraft `
  -Latest

Do not run update_release_exe.ps1 and the coordinated draft workflow for the same release.

AI harness

OKF Todo is built using Codex but is not tied to Codex. It uses AGENTS.md, skills, and other cross-platform designs.

Testing the installed Windows application

See Installed contract tests for the command and requirements for testing the installed GUI, MCP server, OKF bundle, and isolated SQLite databases.