Files

T

naudachu e628ad6fd9 refactor!: rewire the plugin onto the kettle binary, and rename it

BREAKING: the plugin is `kettle`, not `tea`, and its commands are `/kettle:*`.
It also now needs a binary on PATH that it did not need before; the README and
every skill say how to get one and what a missing one looks like.

The plugin was 3800 lines of Python doing what a compiled binary does better,
and the name pointed at a tool that no longer takes part: `tea` is Gitea's CLI,
and since the transport moved into the binary nothing here shells out to it for
issues at all. A plugin named after it was going to keep suggesting otherwise.

Deleted: 19 scripts, the 14-file unittest suite, and the tea-guard hook. The
guard blocked any `tea` invocation that would run under a login the model picked
instead of the operator; the binary holds its own credentials and reads the
pinned login out of the project's own config, so that failure is no longer
expressible and there is nothing left to police. agents-sync stays — it is about
AGENTS.md symlinks and has nothing to do with any of this.

What the plugin keeps is what only a plugin can carry: the rules an operator
states and a binary cannot enforce. `init` still refuses to run inside a linked
worktree and still may not be model-invoked, because which directory is the
project is a statement a person makes. The issue format reference stays here and
stays the source of truth. The runner subagent is still for batches and still
may not decide what an issue says.

The command reference in the issue, sync and project skills is GENERATED from
the binary's own command registry, between markers, so a flag that changed
cannot ship with a skill that recommends the old one. `kettle gen skills
--check` exits non-zero when they drift. The generator owns the region and
nothing outside it: the frontmatter description, which is what decides whether a
skill loads at all, stays hand-written.

`use` survives and is the one place `tea` is still named — for releases,
webhooks and actions, which kettle does not cover. Its instruction to write
`--login "$GITEA_LOGIN"` and let the hook substitute the pin was true until this
commit and is now rewritten: `tea` keeps its own configuration, kettle keeps
its own, and configuring one configures nothing in the other.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-12 00:04:44 +05:00

9.0 KiB

Raw Blame History

kettle — Claude Code plugin for issues as local markdown

Issues are units of work first and tracker rows second. kettle keeps them as flat markdown files in your project, works on them entirely offline, and moves them to and from Gitea when you decide to — never before.

The plugin is a thin wrapper. The work is done by the kettle binary, which lives in this same repository under cli/; the skills carry the rules and procedures a binary cannot state, and their command reference is generated from the binary's own command registry, so the docs cannot drift from the tool.

What it ships

Piece	What it does
`/kettle:init` skill	Makes a directory a project: creates the `.kettle/` marker every command resolves the store from. Once per project, and only you can run it
`/kettle:auth` skill	The credential workflow — what this machine holds, and which login this project runs under
`/kettle:project` skill	Generated flag reference for `init`, `auth`, `config`, `gen`
`/kettle:issue` skill	Issues as units of work — create, read, grep, validate, tick, evict, walk the dependency graph. Entirely offline
`/kettle:sync` skill	Moves issues between the local store and Gitea — pull, push, comment, close, evict
`/kettle:use` skill	`tea` CLI reference for the Gitea entities kettle does not cover: pulls, releases, milestones, webhooks, actions
`kettle-runner` agent	Subagent on Haiku that runs batches of commands and reports back a receipt — the mechanical half, off your main context

Prerequisites

Claude Code — CLI, desktop app, or IDE extension.
The kettle binary, on your PATH. It is not installed for you, and nothing here works without it — see below.
Python 3 — the agents-sync hook is a Python script; python3 must be on $PATH. Nothing else here needs it.
tea (optional) — Gitea's own CLI, only for /kettle:use. brew install tea, or from gitea.com/gitea/tea/releases. It keeps its own logins (tea logins add), separate from kettle's.

Installing the binary

Building it needs Go 1.26 — cli/go.mod says so because the Gitea SDK requires it. vendor/ is committed, so the build itself needs no network.

# from a clone of this repository
cd cli && go build -o ~/.local/bin/kettle ./cmd/kettle

# or, without cloning
go install git.noodles.cam/claude-skills/marketplace/cli/cmd/kettle@latest

Make sure the target directory is on your PATH (go install uses $(go env GOPATH)/bin). Check it with:

kettle help

If a skill ever answers command not found: kettle, that is the whole diagnosis: the binary is missing. Install it and run the command again — the skills say so rather than falling back to something that half-works.

Installation

This is a Claude Code plugin — install it through the plugin marketplace, not by hand-editing settings.json.

/plugin marketplace add https://git.noodles.cam/claude-skills/marketplace.git

Already have a local clone? Point at the directory instead:

/plugin marketplace add /path/to/marketplace

Install the plugin:
```
/plugin install kettle@claude-skills
```

The skills load immediately. Use /plugin to enable, disable, or update it later.

The marketplace registration is written to extraKnownMarketplaces and the plugin to enabledPlugins in your settings automatically — you don't edit those by hand. There is no top-level "plugins" settings key; if you've added one from older instructions, remove it.

First use

Run /kettle:init once per project. It creates the .kettle/ marker that says this directory is the project whose issues live in it — every command resolves the store by walking up to the nearest one, and with no marker anywhere they stop and name the directories they searched rather than picking a plausible one.

/kettle:init

Only you can run it; Claude can't invoke it on its own. Which directory is a project is a statement, and a model guessing at one is the failure the marker exists to prevent. It is idempotent, adds .kettle/ to .gitignore, and moves an older store in if it finds one.

Don't run it inside a git worktree: the marker is gitignored, so a worktree has none by design and reaches the main checkout's store on its own.

That is all /kettle:issue needs — no login, no network, no tracker.

For the Gitea side, give this machine a credential and pin it to the project:

/kettle:auth

Claude will list what kettle auth already holds and ask you to pick. Adding a login is yours to do — the token is read from standard input so it never lands in shell history, and never in a transcript:

kettle auth add --name noodles --url https://git.example.com < token.txt
kettle init --login noodles --repo owner/name

Tokens live in ~/.config/kettle/logins.yaml, mode 0600, outside every working tree. What goes in the repository is the login's name, in .kettle/config.yaml — worth nothing on its own, which is what makes it safe there. kettle config prints everything a directory resolved to and never prints a token.

After that, just ask Claude to do something with issues — it loads the right skill on its own.

The kettle-runner agent

The skills carry meaning; the binary carries work. kettle-runner is a subagent on Haiku that does the second half in its own context and hands back a receipt — what ran, what it touched, what failed, verbatim.

Delegate a batch: pull a milestone and rebuild the index, push the three issues you just wrote, bootstrap the label set, post a comment from a file you prepared. Spawning it for a single kettle pull 42 costs more than running the command yourself; the saving is in the loop, the retry, and reading somebody else's stderr.

It cannot decide anything. No Edit, no Write, no --force, no widening the set it was handed, no raw tea. A missing type, a failed validation, an unpushed dependency come back as a question, not as a guess.

Project layout

.claude-plugin/
  plugin.json                plugin manifest
                             (the marketplace catalog lives one level up, in
                              the repo root's .claude-plugin/marketplace.json)
agents/
  kettle-runner.md           subagent (Haiku) that runs the commands
hooks/
  hooks.json                 registers the PreToolUse hooks
  agents-sync.sh             keeps AGENTS.md real and CLAUDE.md a symlink to it
skills/
  init/                      /kettle:init — make a directory a project
  auth/                      /kettle:auth — the credential a project runs under
  project/                   generated flag reference: init, auth, config, gen
  issue/                     /kettle:issue — the issue domain, offline
    references/format.md       canonical issue format (identity, types, templates)
  sync/                      /kettle:sync — the bridge to Gitea
  use/                       /kettle:use — tea CLI reference
    references/tea/            command docs

AGENTS.md carries the same layout with the reasoning behind it, and the binary's own design is in cli/AGENTS.md. If any two disagree, the binary is right and the prose is stale.

Local issue store

Issues live in <project>/.kettle/issues/ as flat markdown with one metadata field per line — so grep -l 'labels:.*type/bug' .kettle/issues/*.md works without a parser. The directory is gitignored by kettle init; drop that line if your team decides otherwise.

It holds two kinds of file and only one of them is a store:

An origin: local file is the issue — the only copy of that work. It is a complete state, not a draft, and nothing evicts it, in any state.
Anything with a tracker origin is a working copy. A successful push deletes it — --update too, one rule with no exception — and only after the tracker confirms the write. Get it back with kettle pull <n>: same slug, same depends:, even after a rename in the web UI.
Identity is a slug (wire-sqlc-appclick.md), never a tracker number. Numbers live in a gitea: field.
A closed issue is evicted, not archived. The store is a working set.
Pulling overwrites the body: a fetch, not a merge. Checkbox state is the one exception, because a tick is monotone.
Nothing tracks drift, and there is nothing to track: a file that is still here has not been pushed.

Development

cd cli && go test ./...                                    # the binary's suite
cd cli && go build -o /tmp/kettle ./cmd/kettle
/tmp/kettle gen skills --out plugins/kettle/skills --check  # docs vs binary

The second command is the plugin's only mechanical invariant: what the skills say about a command matches the command. Run gen skills without --check to rewrite the generated regions after changing the CLI, and never edit inside the  markers by hand.

9.0 KiB Raw Blame History