- Category
- AI Agents
- Rank
- No. 1800Tools index
- Pricing
- Open Source
- Type
- TOOL
- Builder
- thedotmack
- GitHub
- 5 stars
- Date
About
Schema-less CLI state machine for LLM agents.
What it does
Notch records arbitrary key-value snapshots from command-line flags into a local JSON history. Each invocation can add fields without defining a model first. It can print the complete history, show the latest entry, group records by a chosen field, or clear the state file.
Why it's ranked here
The appeal is narrow but credible: one small command gives agents persistent, inspectable history without a database or fixed data model. Typed value parsing and custom state files make it more useful than raw text logging. Its simplicity also leaves reliability and querying concerns to the caller.
What's good
Every write adds a new record instead of silently changing earlier records. Boolean, numeric, null, and string values are inferred from command-line input. Output is JSON, which suits tool-driven workflows. Separate state files can isolate concurrent tasks, while grouping offers a lightweight status summary.
Tradeoffs
Persistence is a whole-file JSON rewrite, with no documented locking or coordination for simultaneous writers. Input has no schema validation beyond requiring keyed fields, so inconsistent names and types remain possible. Queries only dump or group history. Reset deletes the entire selected state file, and operation requires Bun.
How to use it well
Use it for small agent runs, thinking traces, deployment progress, or task histories where transparent local state matters more than strict structure. Give each independent workflow its own state file and keep field conventions stable. Choose a database or fuller workflow system when you need concurrent writes, validation, richer queries, or record updates.
Technical notes+
package.json defines an ES module package, exposes the notch binary through src/notch.ts, includes only src/, and declares MIT licensing without dependency entries. src/notch.ts uses Bun’s executable shebang and Node-compatible fs, path, and util modules. It parses strict CLI options, resolves the selected state path, reads and rewrites a { log: Entry[] } JSON document, coerces scalar field values, groups status output by stringified values, and deletes the file on reset. README.md documents direct Bun execution and global linking with npm.
Observed
- License
- MIT
- Primary language
- TypeScript
- Runtime
- Bun is required
- Interface
- Command-line interface with JSON output
- Packaging
- ES module package exposing a notch binary; global linking via npm is documented
- Dependencies
- No package dependencies are declared
- Persistence
- Local JSON file containing a single append-only log array
Read from README.md, package.json, src/notch.ts, LICENSE.
What it can do
Execute state machine workflows for LLM agents
State machine configuration and agent instructions → Executed workflow results and state transitions
Define dynamic state transitions without fixed schema
State definitions and transition rules → Flexible state machine structure
Manage LLM agent state persistence
Agent state data and context → Persisted state information
Orchestrate multi-step LLM agent processes
Process definitions and agent tasks → Coordinated agent execution flow
Handle conditional branching in agent workflows
Conditional logic and decision criteria → Dynamically routed execution paths
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.