kerf 0.1.0

Declarative workflow engine where the LLM is a pluggable, disposable step

Kerf
Declarative workflow engine for Claude CLI

---

Kerf runs deterministic tools first, calls the LLM only when you need reasoning, and logs every result. Pipelines are defined as JSON — no Python required to configure a workflow.

• Deterministic-first — preprocessing runs without the LLM until you actually need it
• JSON workflows — define tool chains, prompt templates, and fallback policies as config
• Per-workflow fallback — retry the LLM, degrade to deterministic output, or flag for review
• Full execution logging — every run gets a UUID-stamped log you can audit and learn from
• Auto-discovered tools — drop a Python file in tools/, it gets picked up

Install

uv tool install kerf

Requires Python 3.10+ and Claude CLI (claude login).

Quick Start

kerf init

Kerf project initialized.

kerf run summarize "Kerf is a workflow engine that wraps Claude CLI..."

{
  "summary": "Kerf is a declarative workflow engine that wraps Claude CLI for structured, deterministic text processing."
}

A workflow is a JSON file in workflows/:

{
  "task_type": "summarization",
  "tool_chain": [{ "tool": "normalize_text", "condition": "always_true" }],
  "fallback": "retry"
}

tool_chain runs deterministic preprocessing. task_type sends the result to Claude. fallback controls what happens when the LLM fails.

Custom tools go in tools/ as Python files with a register(manager) function:

# tools/uppercase.py
def uppercase(input_data, params):
    return input_data.upper()

def register(manager):
    manager.register_tool("uppercase", uppercase)

Documentation

Full docs at derek-yn-zhang.github.io/kerf.

License

MIT