kladde

Kladde (KLAH-duh) - German: a rough notebook for quick first jottings, where a merchant recorded transactions before posting them to the ledger.

A concurrency-safe markdown notebook CLI, intended predominantly for use by AI agents. When agents generate code, it's easy to lose the reasoning behind a decision in a compaction or a lost session. Some coding agents use memory, but this generally isn't portable between Claude, Codex, Cursor, and the myriad other coding agents on the market. Kladde is a simple CLI over a notebook made of markdown files. Via skills or other directives, a coding agent can be instructed to record decisions made during a coding session.

Kladde manages daily notes created from a template, generic notes in any folder, and section-aware appends that stay correct when several processes write to the same note at once.

Because Kladde writes pure markdown files, it is compatible with any markdown editor. For example, Kladde can be used to write to your Obsidian vault simply by pointing Kladde at the vault folder.

Installation

Kladde can be used through uv without durably installing it:

uvx kladde --help

Or it can be installed durably, with the shell installer:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/cluebbehusen/kladde/releases/latest/download/kladde-installer.sh | sh

with the PowerShell installer on Windows:

powershell -ExecutionPolicy Bypass -c "irm https://github.com/cluebbehusen/kladde/releases/latest/download/kladde-installer.ps1 | iex"

or from crates.io or PyPI:

cargo install kladde
uv tool install kladde # or: pipx install kladde

Quickstart

Point Kladde at a folder and write:

kladde config set default-notebook ~/notes
kladde append "## Decisions"
kladde append "- Chose blue-green deploys: instant rollback" --under Decisions
kladde read

The first append creates today's daily note; the second lands under the heading it just wrote. kladde --help lists every command.

But Kladde's main audience is coding agents. Install the skill:

npx skills add cluebbehusen/kladde

Then ask your coding agent what Kladde can do and how it can be configured.

Frontmatter

Kladde reads and edits a note's frontmatter, the YAML properties block at the top of a note. kladde frontmatter set, get, unset, add, and remove can be used to interact with both text and list values in the frontmatter.

By default, every write also stamps the note: a created property is added when Kladde creates a note's frontmatter block, and an updated property is refreshed on every change. The property names and timestamp format are configurable, folders can be excluded, and stamping can be turned off entirely; see Configuration.

Configuration

Kladde is configured through a TOML file, and a notebook can carry its own that overrides it; see the configuration reference.