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

ClearHead Specifications

This is intended to be a space where key specifications can live, separated by the implementation details of the underlying projects.

This enables those who wish to build upon the specifications, but avoid the tooling to do such without needing to carve out the relevant pieces from the implementation products.

Scope and Source of Truth

The specifications/ directory is implementation agnostic. It defines behavior and contracts that any conforming implementation can follow, regardless of language, runtime, storage engine, or framework.

To avoid duplication and drift:

  • ontology/ is the source of truth for ontology artifacts (terms, shapes, JSON-LD context/schema, and ontology-out contracts).
  • specifications/ is the source of truth for platform-level interpretation and conformance guidance (how downstream tools should apply those ontology artifacts).
  • Implementation repositories (for example CLI or core libraries) are expected to document only implementation mechanics, and should reference these specifications for normative behavior.

Releases

The specifications are released together under one semantic version, tagged vMAJOR.MINOR.PATCH; CHANGELOG.md records what each release changed. While the major version is 0, any release may change the contract.

An implementation conforms to a release, never to a branch. Every schema’s $id names the release it belongs to:

https://clearhead.dev/schemas/<tag>/<name>.schema.json

and a document declares the schema it follows with that URL as its $schema. A release is one commit that moves every $id to the new tag and gives the changelog’s pending entries that version; the tag points at that commit.

clearhead.dev is this specification as a site, published from the release branch (platform Decision 49): a release is tagged on main, release is fast-forwarded to it, and the site, the application vocabulary (https://clearhead.dev/vocab/app/v1#) and the schemas update together. Releases before v0.2.0 named their schemas by their raw.githubusercontent.com URL, which still resolves.

ClearHead Platform Overview

Many of these other specifications cover rather precise technical details, but i want to take a bit of time to cover the overarch process that is guiding much of these specifications as a way to bring meaning to the disperate parts.

The Problem Being Solved

At its core, ClearHead is an attempt to express intention in a clean, straightforward manner.

This starts as a simple text file on your machine, your replacement for todo.txt. However, as your needs grow, the tools will grow with you at the pace you need, rather than forcing you into a complex system from the start.

When you do start integrating these into your systems, it is important that these intentions become just as much data as they are text, and we will have access to the tools that power users are used to, rather than reinventing the wheel again.

We have demanding lives, and making these intentions useful takes more work than one might think when they start their todo.txt, and the goal is to allow people to use these intentions in whatever way makes sense within their system to:

  • Keep track of what they need to do
    • both at home and while travelling
    • with or without internet access
    • on or off their home devices
  • Pass intentions to other agents
    • coworkers
    • family members
    • hired professionals
    • LLM agents
  • Analyze and reflect on their intentions
    • Capture data on how they spend their time
    • Reflect on what they have accomplished
    • find the dependencies between intentions
  • Integrate this with other data
    • Calendar events to track intentions
    • Links to appropriate resources
    • Automations to help accomplish intentions
    • using the intentions themselves as a workflow engine for both humans and machines

Values and Principles

With this platform, my goal is to create a system with a few core values:

  • local-first: Users should be able to use the system fully offline, with optional cloud sync.

    • Adherence to Standards: In particular, i believe we achieve local-first software through the coordination of standards and data rather than bespoke implementations.
    • Interoperability: Different tools and implementations should be able to work together seamlessly.
      • This is why these specifications exist as a separate repo, so that other implementors can build their own tools that interoperate with the ecosystem.
  • Incremental Adoption: Users should be able to start small and gradually integrate more features as they see fit, or not! A core usecase is the single person, writing a plaintext file in the woods are their phone without internet.

    • This is why the string file format is the core of the system, and everything else builds on top of that.
    • Power users will also need to extend the system beyond the core and this needs to be possible without breaking the core usecases.
  • Opinionated Defaults: Everything from the file format to the tools is built with intention. We want to leverage best practices to make a nice experience out-of-the-box rather than making people build their workflow from scratch.

    • While we want to make customizability core, preferrably, for most this is a rare occasion and they can be productive with the system before they need to adopt the entire workflow

    These values are some of the big reasons i have not used one of the leading task frameworks as i didnt feel that any of them held to all of these values even if they stuck to one or two.

Design principles

Three rules that kept deciding designs (the agent sandbox, Decisions 36, 55 and the template binding) before anyone wrote them down:

  • Standards at the boundary, our model at the core. Adopt a standard inside the core when it models the same concept the domain does (RFC 5545’s reading of local time, ISO 8601 intervals). When it models a neighbouring concept (VTODO’s assignable task beside an action’s intent), project the subset it can carry and say what is lost; never let it share authority over the model.
  • Ownership is not storage. Who may change a fact and where its bytes live are separate questions. A fact ClearHead owns can travel inside another format (an X-CLEARHEAD-* property) when that keeps it with the thing it describes.
  • Proposals are evidence; only the human’s act makes them authority. An inference, a planner’s output, a title that matches a template or a change made on another device may be surfaced for acceptance. None becomes durable intent until a person accepts it.

Philisophical Inspirations

This has been a topic of research of mine for many years and it would be rude of me not to credit many of these authors for guiding and shaping my thinking on the topic:

  • Getting Things Done by David Allen - The foundational text on modern task management and productivity.
    • Ive been practicing GTD personally for over a decade now and it shapes much of my thinking on these topics. In terms of clear, pragmatic systems for intentions I believe David does the best at creating a system that is empathetic to how humans actually work.
  • Deep Work by Cal Newport - A deep dive into the importance of focused work and how to achieve it in a distracted world.
    • While GTD is a brillient set of systems, it has relatively little to say on WHAT actions you should take and WHEN and how to go about them. Deep work answers this question by arguing that we should be trying to do as much deep work as possible, minimizing and automating shallow work.
    • Cal has done a great job of outlining how professions like programming need to work and serves as a good guide to finding focus in a world of distractions.
  • The Agile Manifesto by Kent Beck et al. - A set of principles for software development that emphasizes collaboration, flexibility, and customer satisfaction.
    • While mostly focused on software, i believe the core insight of agile is a sense of humility and pragmatism when it comes to delivering work. Whereas the first two are about optimizations, agile is this funny instance of a more humanistic perspective peaking out from a very corporate mindset.
  • Marie Kondo’s life-changing magic of tidying up by Marie Kondo - A guide to decluttering and organizing your physical space to create a more joyful life.
    • Marie does a good job of making a cleaning book not about cleaning, a productivity book not about productivity. Instead, or in addition to her wonderful cleaning tips, she subtly influences the reader with zen buddhist principles of mindfulness and intentionality, and serves as one of the more subtle pieces in this list but no doubt one of the most sophisticated in terms of the topics she covers
  • Atomic Habits by James Clear - A comprehensive guide to building good habits and breaking bad ones through small, incremental changes.
    • Another area that GTD doesnt cover as throughly is the idea of habits. or put another way, habits can be seen as a higher level system for managing actions that recur frequently. James does a great job of breaking down the science of habits and giving practical advice on how to build and maintain them.
    • I see it as using the systems of GTD to create the habits we want to see for ourselves, first with technical tools, until they become second nature.

Technical Inspirations

Over the years of research I have seen many implementations that have inspired this work:

  • todoist - A powerful task management system with a strong focus on user experience and cross-platform support.
    • My current personal task system while this system is built and while it adheres to most of the web 2.0 principles, it does a good job of being a solid, reliable task manager that just works and any system that replaces it will need to meet this high bar for both usability and reliability.
  • (Neo)vim - An extensible and highly customizable text editor that serves as the foundation for many ClearHead tools.
    • as my personal editor, neovim is a constant source of inspiration from both a technical perspective, as well as a user experience perspective. this tool will in many ways try to bring some of the same principles of extensibility and customizability to task management that neovim brings to text editing.
  • todo.txt - A simple, plaintext-based task management system that emphasizes simplicity and portability.
    • has always been the standard bearer of simplicity in task management and while it lacks many of the advanced features of modern systems, its simplicity and portability are unmatched. ClearHead aims to aknowledge this core insight that one should always be able to go back to editing a file to list out intentions even if we grow from there.
  • taskwarrior - A command-line task management tool that offers advanced features and flexibility for power users.
    • taskwarrior shows in many ways the opposite virtue of todo.txt, in that it wants to leverage the power of data to do really cool things with relatively little effort. This is another very good virtue that clearhead will seek to embody.
  • org-mode - An Emacs-based system for organizing tasks, notes, and projects with a focus on plain text and extensibility.
    • org-mode is another very powerful system that has a strong focus on plain text and shows that there is no reason a plain-text based system cant be as powerful as a database-backed system. While i personally dont use emacs, i do admire the power and flexibility of org-mode and its community.

While all of these systems have their strengths and weaknesses, none of them fully embody the values and principles that ClearHead aims to achieve, and thus i felt there was a need for a new system that could bring these ideas together in a cohesive manner.

Index

Here is the index of specifications and their purpose within the whole:

  1. Process Overview - The most abstract overview of the process which outlines the key steps in a way that is implementation agnostic.
    1. This document serves as the high-level guide for how different tools should approach the handling of action files and user intentions, ensuring a consistent experience across the ecosystem.
  2. Action File Format - The format for .actions files that represent actions (execution records). If you read nothing else, start here to understand how actions are defined.
    1. For Example, while tree-sitter-actions implements this specification using tree-sitter, it could just as easily be implemented using PEGS or any other parsing technology.
  3. iCalendar VTODO Projection Specification - Defines recurring Plan VTODOs, standalone Action VTODOs, expansion, identity, and bidirectional vdir synchronization.
  4. Workspace - The structure, discovery, and identity conventions for workspaces within the ClearHead ecosystem. This allows different tools to interoperate without confusion as they can leverage shared configuration, naming semantics, and structure to build more interesting systems
    1. Both clearhead-cli and clearhead.nvim implement these conventions to manage collections of actions, wether they be plaintext files, json data, or full databases.
  5. Configuration - Defines how ClearHead implementations handle configuration, including XDG directory structure, JSON configuration format, layered configuration (defaults → file → env → args), and extension mechanisms for implementation-specific settings. This ensures all tools share a common configuration approach while allowing for tool-specific extensions.
    1. Implementations like clearhead-cli and clearhead.nvim can share configuration via ~/.config/clearhead/config.json while maintaining their own sections for tool-specific settings.
  6. Action JSON Schema - The canonical JSON projection shape for action data. It supports interchange and validation without replacing the plaintext workspace as durable authority.
    1. Implementations may export this projection for pipelines and external analysis; synchronization back into workspace source requires an explicit mutation contract rather than treating JSON as a second write model.
  7. Charter JSON Schema - The canonical JSON projection shape for charter documents, following the same projection rules as actions. It carries charter facts only; Actions and Plans join back through their charter reference.
  8. Ontology & Linked Data - How a workspace is published as RDF: the application graph (app:) queries read, field by field, and its meaning in the ClearHead ontology’s standard terms (CCO and IAO); graph identity, conformance and determinism.
    1. This specification ensures that while tools typically interact with simple JSON, the data remains semantically rigorous and interoperable with the broader Semantic Web (RDF/JSON-LD).

License

Released under the MIT License: use it, implement it, build on it, commercially or not. The ontology imports keep their own licenses: ontology/imports/cco-v2.2.ttl is the Common Core Ontologies, BSD 3-Clause, © CUBRC, Inc.; ontology/imports/iao-2026-03-30-module.owl is a module of the Information Artifact Ontology, CC BY 4.0.