🧝 Heinzelmännchen

Heinzelmännchen are helpers accelerating product teams. They draft the busywork of running a team — status, tracker updates, agendas, reports — in the background, and people approve it. Like the Heinzelmännchen of Cologne, who finished the town's work at night. Why it exists and where it is going: INTENT.md. It is built on open source, and we are grateful: thank you to everyone in ATTRIBUTIONS.md.

Meet the Heinzelmännchen. In the web app each one shows what it is up to: working on a draft, thinking it over, waiting for you to approve, asleep when there is nothing to do, blocked until you fix something, done with a happy smile. In hz a small one greets you, walks along during long work and marks a finished line. They are garnish, never a replacement for words: hz system config set hz.playful false (or Settings → General) turns them all off, and they stay away from JSON, pipes, CI and NO_COLOR anyway.

This release is the foundation — kernel, heads, plugins and release automation; the first team workflows arrive in 0.x (roadmap).

Video · Still

What you can do today:

• Write an operation once, use it everywhere. A typed Python function is a hz command, an MCP tool for coding agents and a REST endpoint at once — with help text, validation and --json.
• Extend it with plugins. hz system plugin add github --confirm adds a first-party plugin; hz system plugin new scaffolds your own heinzel-* repository with tests, CI/CD and agent setup.
• Run it with confidence. hz system doctor checks every module's health, hz system config manages layered settings, hz system update updates in place and keeps your plugins.

You talk to them with hz, a small modulith: the kernel discovers modules and the lets they advertise — typed declarations of operations, services, settings and health checks — and heads expose them.

Get started

Two task-first guides take you top to bottom: Bootstrap your team for the manager who installs hz, creates the team repository, gets the first weekly report drafted and invites the team, and Join your team for the engineer or product manager with the line from their manager.

Install

You need uv (brew install uv). Then:

uv tool install heinzel

Install a specific release with uv tool install heinzel==X.Y.Z; hz system update then moves to the latest PyPI release in place, keeping plugins (--source <spec> moves to another source or ref). It follows releases (--channel main or setting update_channel for the newest commit of main); pinned to another branch or a commit, it says which --source moves it. Shell completion: hz --install-completion.

From Claude Code, add the plugin and let /hz-init do everything — install, plugins, configuration, agent skills:

/plugin marketplace add helmut-hoffer-von-ankershoffen/heinzel
/plugin install heinzel@heinzel
/hz-init

Other agents: hz system agent install copies the skills into the directories set in [system.agent] skill_dirs.

Uninstall with /hz-uninstall from Claude Code, or:

hz system agent uninstall             # remove the skills from your agents
uv tool uninstall heinzel      # remove Heinzelmännchen and its plugins

Your configuration files stay; hz system config show lists them before you uninstall.

Use

On a colour terminal hz greets you with a small Heinzelmännchen and a walking one keeps you company during long work. hz system config set hz.playful false (see Configure), NO_COLOR, CI, a pipe or --json keep the output plain.

hz --version
hz system info                 # versions, settings, modules, what plugins report
hz system doctor               # every module's health checks; exits 1 if anything is down
hz system modules              # every module and submodule with the lets it advertises
hz system changelog            # release notes of the installed version
hz system changelog --newer    # what the releases newer than yours bring, before you update
hz system config show          # configuration files, settings in effect, their environment variables
hz system config set hz.log_level INFO
hz system release              # is there a newer release? (asks GitHub now; hz checks hourly on its own)
hz system update               # update, keeping plugins
hz system plugin add clock --confirm     # a first-party plugin
hz clock                       # its command: the time for everyone on the team
hz system agent install               # install the skills for coding agents

Every operation takes --json (or --format json; HZ_OUTPUT_FORMAT=json makes it the default) for scripts and agents; the long-running serve commands are the exception. Exit codes: 0 success, 1 an error with a readable message, 2 a usage error, 78 invalid configuration; hz ui exits 0 when Ctrl-C stops it, an interrupted hz setup 130. All commands: docs/CLI_REFERENCE.md.

hz --help lists the everyday commands; hz system expert on lists every command in help, shell completion and the web app, and hz system expert off goes back. Commands for experts run either way, and MCP and REST always offer them all (ADR 0041).

How the pieces fit — more in ARCHITECTURE.md:

flowchart TB
    People(["People"]) --> CLI
    Scripts(["Scripts"]) -- "--json" --> CLI
    Agents(["Coding agents"]) -- "--json" --> CLI
    Agents --> MCP
    subgraph Heads["Heads: views on the same operations"]
        CLI["CLI<br/>hz …"]
        MCP["MCP server"]
        REST["REST API"]
        Web["Web app<br/>hz ui"]
        Daemon["Daemon<br/>local jobs"]
    end
    subgraph Kernel["Kernel"]
        Core["discovery · lets<br/>injection · config"]
    end
    subgraph Modules["Modules and plugins"]
        System["system<br/>(built-in)"]
        Clock["clock · github · atlassian · google · zoom<br/>(first-party)"]
        Ext["heinzel-*<br/>(external)"]
    end
    CLI & MCP & REST & Web & Daemon --> Core
    System & Clock & Ext -- "advertise lets" --> Core

What's inside

Every module is a set of operations, and every operation is a hz command, an MCP tool (hz system serve mcp) and a REST endpoint (hz system serve api) at once. Coding agents use whichever suits them: the CLI with --json, or the MCP tools. People who'd rather click run hz ui: a web app on localhost, for this session only, with a navigation tree of settings, contracts, your team, inventory and the doctor's fixes, and a chat with your agent runner that says what it may cost before it runs. Modules can also advertise jobs that hz system daemon install runs in the background on a schedule, under launchd or systemd, unattended and with your rights; hz system daemon pause and uninstall stop them (see SECURITY.md). Built in today:

• ai — How hz reaches AI, and what it spends: tokens and cost per run.
• ai.access — Pick how hz reaches AI: Claude Code, your company's gateway, or an option a plugin adds.
• atlassian — Read Jira issues and Confluence pages through acli: the tracker and documents capabilities. First-party plugin: hz system plugin add atlassian --confirm.
• clock — World clock: what time it is for everyone on the team. First-party plugin: hz system plugin add clock --confirm.
• github — Read pull requests and issues from GitHub: the code-host and tracker capabilities. First-party plugin: hz system plugin add github --confirm.
• google — Google Docs, Sheets, Drive, Calendar and Gmail: the documents, calendar and mail capabilities. First-party plugin: hz system plugin add google --confirm.
• graph — Are your team's promises kept? Artifacts and Heinzelmännchen, and where the flow waits.
• heinzel — Your Heinzelmännchen: durable agents that keep your team's documents true.
• org — Your profile, and the team, org and company you work with.
• report — Telemetry: log what a Heinzelmännchen did, for your team's graph (hz report published <id> <url>).
• system — Inspect, configure, diagnose and update Heinzelmännchen itself.
• system.agent — Install the Heinzelmännchen skills for coding agents.
• system.capability — Show which adapters serve which capabilities, and who reads and writes what.
• system.changelog — Release notes of the installed version and of newer releases.
• system.claude — See the MCP servers and skills you already set up for Claude, without using any of them.
• system.config — Show, get, set and initialize configuration.
• system.connector — Show whether each connector is signed in and serves something, and test one live.
• system.credential — Store and check the credentials modules need, in the OS keychain.
• system.daemon — Run modules' jobs in the background, supervised by launchd or systemd.
• system.directory — Guess reporting lines from recurring 1:1s in your calendar, for setup to confirm.
• system.doctor — Check that Heinzelmännchen and its modules are healthy.
• system.expert — Expert mode: list every command, or just the everyday ones.
• system.layer — Show the layer plugins installed and the stack you are in, general to specific.
• system.notify — Pop up what deserves your attention: in the web app while it is open, else natively.
• system.plugin — Find, add, remove, enable, disable, list and scaffold plugins.
• system.plugin.docs — Document installed plugins: what each brings, as a model and as Markdown pages.
• system.resource — Show this computer's CPU, memory and load.
• system.runner — Run bounded agent sessions with Claude Code or a configured command.
• system.runner.chat — Chat with the agent runner about where you are; it acts through hz once you confirm.
• system.skill — List the skills plugins ship for AI, and hand chosen ones to Claude Code.
• system.sound — Pick the web app's soundscape: off, a built-in one or one a plugin offers.
• system.state — Note how hz is used on this machine and push it to your own state repository.
• system.theme — Pick how the web app looks: the built-in theme or one a plugin offers.
• system.ui — List what modules add to the web app: status items, header actions and Today widgets.
• tailscale — Private web sharing through Tailscale Serve. First-party plugin: hz system plugin add tailscale --confirm.
• team — Your team's repository: create one (hz team new), join one by its URL (hz team join), add people to it.
• zoom — Read meetings from Zoom's meeting-summary emails: the meetings capability. First-party plugin: hz system plugin add zoom --confirm.

Details for each, in every head: docs/MODULES.md. Plugins add their own modules.

First-party plugins

Maintained and released with the core, from plugins/, at the same version; none is installed by default, so you only get the integrations you use. hz system plugin add <name> shows the one matching your hz and --confirm installs it, and hz system plugin search lists them first.

Slack adapters are planned as first-party plugins too.

Community plugins

Plugins useful to many but not to everyone live in heinzel-contrib, one distribution per plugin in plugins/heinzel-<name>/, built to the core's standards and tested against it:

Company plugins live in their own heinzel-* repositories, scaffolded with hz system plugin new.

Workflows are Markdown files, not code: a <name>.prose.md contract in your workflows directory (or your team's state repository) names the capabilities it reads, the inputs to fetch and the agent's limits, and its body says what the draft must achieve. Drafts are saved locally; nothing is published by itself.

hz heinzel new weekly-digest             # a starter contract, valid as written, with comments; creates the directory
hz heinzel check                         # every problem by file and line
hz heinzel show weekly-digest            # what it requires, what is bound, whether it is ready, what to run next
hz heinzel wake weekly-digest --dry-run   # the packet the agent would get; nothing is spent
hz heinzel wake weekly-digest             # draft it now; then `hz heinzel drafts`

Give it a schedule: and the daemon runs it. The journey from nothing to a scheduled team contract, and the contract reference: docs/HEINZELMAENNCHEN.md. Decisions: ADR 0021.

Configure

Settings come from, lowest precedence first: defaults, the site file, your user file (~/Library/Application Support/hz/config.toml on macOS, ~/.config/hz/config.toml on Linux; HZ_CONFIG_HOME moves it), the nearest hz.toml in the working directory or above (share it in a team repository), the file in $HZ_CONFIG, and environment variables.

[hz]
log_level = "INFO"
disabled_modules = []

[example]               # each module has its own table
greeting = "Moin"

Joining a team is one line, the same for everyone, posted in its chat. It finds out who you are from your gh and gws logins, joins the team and sets up what is missing (hz join prints the line for the next person):

uvx --from heinzel heinzel join <team repository>
# from a coding agent, without a terminal:
uvx --from heinzel heinzel join <team repository> \
  --role engineer --yes --json

hz setup asks for whatever is still missing, wizard style, and continues where the last run stopped: hz setup clock for one module, --restart to go through every step again, --answers answers.toml without a terminal, and hz setup --print-answers > answers.toml to write that file from a finished setup.

hz system config set example.greeting Moin edits your user file (--scope project the project's hz.toml), hz system config init writes a commented starter file, hz system config reveal user shows that file in Finder, Explorer or your desktop's file manager (site, project for the others). Environment variables: HZ_<SETTING> for the kernel (HZ_LOG_LEVEL=DEBUG), HZ_<MODULE>__<SETTING> for modules (HZ_EXAMPLE__GREETING=Hi). Every setting: docs/CONFIGURATION.md.

Extend

A module is a package that declares module = Module(name, summary); operations are typed functions; services and settings are injected by type (put injected parameters first):

from typing import Annotated

from pydantic import Field

from heinzel import Module, ModuleSettings

module = Module("greet", "Greet people.")


@module.settings
class GreetSettings(ModuleSettings):
    greeting: str = Field(default="Hello", description="How to greet.")


@module.operation
def hello(settings: GreetSettings, name: Annotated[str, Field(description="Who to greet.")] = "world") -> str:
    """Greet someone."""
    return f"{settings.greeting}, {name}!"

A module can also declare a setup step, @module.setup, that asks its questions through an injected Prompter and runs as hz setup greet and as part of hz setup (ADR 0032).

That is hz greet hello --name Ada in the CLI, with --json, help text, argument validation and HZ_GREET__GREETING — and the same operation is an MCP tool and a REST endpoint. Scaffold a plugin repository with all the tooling, CI/CD and agent setup: hz system plugin new ../heinzel-mine. A complete plugin to copy from: plugins/heinzel-clock (one module, settings, an operation, a health check and a setup step). See ARCHITECTURE.md.

Standing on the shoulders of giants

hz is a thin layer on a lot of brilliant open-source work, and we are deeply grateful to everyone who writes, maintains and shares it. Thank you. Among many others: Typer and Rich for the CLI; FastAPI, Starlette and Uvicorn for the API; Pydantic for every typed model; the MCP Python SDK for the MCP head; pluggy for plugins and uv for installing them. The web app runs on React, React Flow, xterm.js and TanStack Query, built with Vite and styled with Tailwind CSS.

ATTRIBUTIONS.md lists every package hz ships, with its license, homepage and license text.

Contribute

You need git, make and uv; make setup installs everything else. CONTRIBUTING.md takes you from a clone to a merged pull request; AGENTS.md is the guide for coding agents; docs/CODING_STANDARDS.md the rules; docs/adr/ the decisions. Bugs and ideas: open an issue; security issues privately, as SECURITY.md describes.

License

Heinzelmännchen is free and open-source software under the MIT license. The packages it ships keep their own licenses, listed in ATTRIBUTIONS.md.

Presence and adoption stay local by default. Opt in to a personal state repository with hz system config set system.state.personal <repository>, then inspect hz system state status (state repository design).