OKF-Todo

# OKF-Todo > **Version 0.1 alpha - work in progress.** Expect incomplete features and changes to the user interface. Database will be migrated to newest version if necessary. An open-source, offline To-Do application for developers and supporters built with SQLite supporting Open Knowledge Format and MCP. [](docs/images/okf-todo-task-workspace.png) _{Data was created by Codex directly.} ## AI-First Data OKF-Todo is designed to help an AI coding harness turn unstructured work into practical artifacts. Give Codex, Claude Code, or another compatible harness 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. For AI-assisted work, the recommended workflow is **draft, review, save, verify**: ask the harness 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](docs/help/okf-layer.md) and [MCP user guide](docs/help/mcp-server.md) provide complete examples and reusable prompts. An AI harness can work with OKF-Todo in several ways: - **[OKF-guided access](docs/help/okf-layer.md):** give the harness 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](docs/help/mcp-server.md):** let an MCP-compatible harness list, read, create, and update tasks and inspect their timelines through structured tools. - **[CLI commands](docs/okf/todo-database/references/application-command-interface.md):** let people, scripts, and agents execute application commands from a terminal. - **Direct SQLite access:** let a user, script, or harness read or write the local database directly when it has permission to access the file. - **Desktop interface:** use every task-management feature manually without an AI harness. 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 [OKF](docs/help/okf-layer.md) and [MCP](docs/help/mcp-server.md) 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. - Installers for Mac and Linux. 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 - Fast task capture with only a title and task type required. - Active, 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. - 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 using the OKF layer and optional MCP server. ## Windows Installer Windows users can install the self-contained application with the [OKF-Todo 0.1 installer for Windows x64](https://github.com/dalby-md/OKF-Todo/releases/latest/download/Okf-Todo-0.1-win-x64-setup.exe). The installer includes the desktop application and OKF context layer. Installing the MCP server is offered as a user choice and is selected by default. **You don't need to be a local administrator to install this.** ## Screenshots [Browse the OKF-Todo screenshot gallery](docs/images/promotional/README.md) to see the workspace, task workflow, offline Help, Preferences, backup, and dark mode. All screenshots use fictional demonstration data. # Section for IT professionals ### Database file The database is stored under the operating system's local application-data directory: | Platform | Typical database path | | --- | --- | | Windows | `%LOCALAPPDATA%\Okf-Todo\okf-todo.db` | | macOS | `~/Library/Application Support/Okf-Todo/okf-todo.db` | | Linux | `$XDG_DATA_HOME/Okf-Todo/okf-todo.db`, or `~/.local/share/Okf-Todo/okf-todo.db` when `XDG_DATA_HOME` is unset or relative | Do not delete this file unless you intentionally want to remove all application data. ### Requirements The current alpha is run from source. You need. - Windows 10 or later, macOS 10.15 or later, or a current Linux desktop distribution. - If you want to use dotnet builder and runner. You should use [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0). - The platform webview used by Photino: WebView2 on Windows, the system WebKit view on macOS, or GTK/WebKit on Linux. Windows is the primary tested platform for version 0.1. The application architecture and Photino shell are cross-platform, but macOS and Linux packaging and 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: ```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: ```cmd 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 MCP server in the repository root: ```powershell dotnet build .\Okf-Todo.Mcp\Okf-Todo.Mcp.csproj -c Release ``` Then configure an MCP client to start the built stdio server. For example: ```json { "mcpServers": { "okf-todo": { "command": "dotnet", "args": [ "C:\\git\\Okf-Todo\\Okf-Todo.Mcp\\bin\\Release\\net8.0\\Okf-Todo.Mcp.dll" ] } } } ``` 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: | Tool | Purpose | | --- | --- | | `task_list` | List tasks by view. | | `task_get` | Read one task. | | `task_create` | Create a task through the shared application command service. | | `task_update` | Replace a task's editable fields through the shared application command service. | | `task_get_timeline` | Read comments and automatic task history. | `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: ```powershell dotnet run --project .\Okf-Todo.Mcp\Okf-Todo.Mcp.csproj -- --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 tasks, body images, attachments, lookups, tags, relationships, comments, checklists, and history. Interface preferences such as layout and color scheme are stored separately and are not included. Restore is manual in version 0.1: 1. Close OKF-Todo. 2. Keep a copy of the current database if needed. 3. Replace the platform-specific `Okf-Todo/okf-todo.db` file listed under Getting Started with the backup file. 4. Start OKF-Todo again. Never replace the active database 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 0.1 is an alpha release intended for evaluation and personal use: - Windows, macOS, and Linux can run from source; Windows currently receives the most testing. - A Windows installer can be built from the repository. Automatic updates and macOS/Linux packages are not available yet. - There is no cloud sync or multi-user collaboration. - Database downgrades are not supported; back up the database before installing an older application version. - Restore is a manual file-replacement operation. - Deep integrations with email, ServiceDesk, Teams, and Azure DevOps are not included. Use the in-application backup command regularly while evaluating the alpha. ## Development Build the solution: ```powershell dotnet build -c Release ``` Run the test suite: ```powershell 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: ```powershell 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`](docs/). ### Build the Windows installer The Windows installer is a self-contained `win-x64` Inno Setup package. It always installs the GUI and OKF context graph. **Install MCP server** is presented as an installer component and is selected by default. Install Inno Setup 7 (or compatible Inno Setup 6), then run from the repository root: ```powershell .\installer\build-installer.ps1 -Version 0.1.0 ``` Or from Windows cmd: ```cmd installer\build-installer.cmd -Version 0.1.0 ``` The installer is written to: ```text artifacts\installer\Okf-Todo-0.1.0-win-x64-setup.exe ``` To publish, merge, and validate the staging payload without compiling the setup executable: ```powershell .\installer\build-installer.ps1 -Version 0.1.0 -SkipInstallerCompile ``` The mandatory payload is staged under `artifacts\installer\staging\core`; the optional MCP server and its isolated runtime are staged under `artifacts\installer\staging\mcp`; and 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: ```powershell .\installer\build-installer.ps1 -Version 0.1.0 ` -SignToolPath 'C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64\signtool.exe' ` -CertificateThumbprint '<certificate-thumbprint>' ``` The build signs the GUI executable and MCP 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: ```powershell 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: ```powershell .\installer\update_release_exe.ps1 -Tag v0.1.8-alpha ``` Preview the derived version, asset name, and stable URL without building or contacting GitHub when an explicit tag is supplied: ```powershell .\installer\update_release_exe.ps1 -Tag v0.1.8-alpha -WhatIf ``` Use `publish-github-release.ps1` only for the alternative versioned, non-alpha release workflow. Do not run both publishing scripts for the same installer. ## AI harness OKF-Todo is built using Codex but is not tied to Codex. It uses AGENTS.md and skills and other crosss platform designs.