notch

Schema-less CLI state machine for LLM agents.
No schema. No database. Just append and go.

Quick Start · Commands · Examples

---

A CLI-first, file-persistent state machine with no predefined schema. Define your state structure on the fly with `--field key=value`. Every entry is appended to an append-only JSON log.

Built for LLM agents that need to track state across tool invocations — but works for anything.

$ notch --field phase=planning --field step=1
{"entryIndex":0,"historyLength":1,"entry":{"phase":"planning","step":1}}

$ notch --field step=2 --field done=true
{"entryIndex":1,"historyLength":2,"entry":{"step":2,"done":true}}

$ notch --status --group-by phase
{"historyLength":2,"groups":{"planning":[{"phase":"planning","step":1}]},"ungrouped":[{"step":2,"done":true}]}

Quick Start

Requires [Bun](https://bun.sh).

# Clone and use directly
git clone https://github.com/thedotmack/notch.git
bun notch/src/notch.ts --field hello=world

# Or link globally
cd notch && npm link
notch --field hello=world

Commands

Command	Description
--field key=value	Append an entry with one or more fields (repeatable)
--status	Dump full state log as JSON
--status --group-by	Group log entries by a field's value
--reset	Delete state file, start fresh
--state-file	Use a