Metadata-Version: 2.4
Name: kladde
Version: 0.2.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Programming Language :: Rust
Classifier: Topic :: Text Processing :: Markup :: Markdown
License-File: LICENSE
Summary: CLI for a local markdown notebook, built for coding agents: daily notes, generic notes, and section-aware appends that are safe under concurrent writers
Keywords: markdown,notes,notebook,daily-notes,agent
Home-Page: https://github.com/cluebbehusen/kladde
Author-email: Connor Luebbehusen <connor@luebbehusen.dev>
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/cluebbehusen/kladde
Project-URL: Issues, https://github.com/cluebbehusen/kladde/issues
Project-URL: Source, https://github.com/cluebbehusen/kladde

# 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:

```sh
uvx kladde --help
```

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

```sh
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
powershell -ExecutionPolicy Bypass -c "irm https://github.com/cluebbehusen/kladde/releases/latest/download/kladde-installer.ps1 | iex"
```

or from crates.io or PyPI:

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

## Quickstart

Point Kladde at a folder and write:

```sh
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:

```sh
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).

## Configuration

Kladde is configured through a TOML file, and a notebook can carry its own that
overrides it; see the [configuration reference](docs/config.md).

