kiln

Claude Code's workshop

Start every new project, and rescue every old one, like a senior engineer would — even if you're not one.

Make Claude Code build production-grade repos, bring yours up to that grade, and keep them that way.

Reference · Changelog · Contributing · Français

A real run, played at 1.5× with the waits cut: kiln new, then kiln check in the new repo.

Claude Code writes code fast. A repo needs more than that to stay healthy: a current stack, rules an agent cannot argue its way around, a git workflow that survives a bad afternoon, and someone to stop it going stale on day ninety. kiln brings all four to a new repo in three questions, and to the one you already have, however old and messy: it lays down the rules, lists what falls short, and Claude Code works it off. Then it keeps every repo current, release after release. kiln itself calls no AI and needs no API key.

Highlights

• A new repo in three questions (what you build, how big, the team's language): code, tests, linters, CI, pre-commit hooks, containers and the instructions Claude reads first.
• A repo you already have, however old: kiln adopt brings it under kiln on a work branch, without touching an existing file. The rules are checked after each edit Claude makes, the debt they find is listed for Claude to work off, and kiln check, kiln dev and kiln status serve it like a repo kiln created.
• kiln update replays the template, takes compatible dependency upgrades, converts what a release renamed and runs your checks before you commit. --rehearse tries it on a throwaway clone first, --all updates every repo in your code folder.
• charter, kiln's rule checker, checks each file Claude edits in about 0.15 s: banned tools, names, file sizes, personal data in logs. Counts that may only go down (ratchets) and coverage floors hold at each commit and in CI. A waiver needs a reason and an end date.
• kiln grid lists the practices kiln stands behind, each with its reason, its sources (checked and dated) and how it is detected. kiln score measures any repo against them in about a second, without a token: a score out of 100, one per pillar, and the gaps to close first.
• Skills for worktrees, merges, releases and reviews; hooks that keep Claude off main and develop; a status line that shows CI, tickets and production.
• A private repo's CI runs on your machine (kiln ci, its verdict kept as a git note) and spends no GitHub minutes; a public repo's runs on GitHub, where it is free.

Install

uv tool install kiln-cli     # the command is kiln; uv fetches Python 3.14 if needed

Or try it without installing anything: uvx kiln-cli new my-app for a new repo, uvx kiln-cli adopt in one you already have. macOS, Linux and Windows through WSL; pnpm for JavaScript fronts, podman for containers.

Quick start

A new repo:

$ kiln new my-app            # three questions, then a private GitHub repo (--no-github: local)
$ cd my-app && kiln dev      # the stack's dev servers, output prefixed by service
$ kiln check                 # ruff, mypy, pytest, ESLint, type checks, then charter
$ claude                     # Claude Code, with kiln's rules, skills and hooks loaded

A repo you already have, on a work branch:

$ git switch -c chore/kiln-adopt
$ kiln adopt                 # the rules and a backlog, no file touched; then what falls short
$ claude                     # Claude Code works it off, with kiln's rules, skills and hooks

What you get

Next.js, Dash and Java 25 + Maven are there too, and kiln's tests generate and check every combination. Django and Nuxt are complete; the other stacks are frozen but maintained: new grid rules go to Django and Nuxt first.

Every repo also gets uv, pnpm and podman (never pip, npm or docker), CI that calls kiln's reusable workflows, protected main and develop branches, a docs/backlog/ of typed tickets, and a size (spark, ember, flame or blaze) that sets how much process it carries. A Django app can ship to a hardened VPS (Caddy, read-only containers, automatic rollback, tested backups), a Nuxt front to Vercel.

Kept current

A kiln release first ships as a candidate, tagged only once its CI is green on Linux and macOS, including an update from every release since v0.3.0 through an installed tool. It is promoted when the next candidate is ready, then rehearsed on a clone of each repo before kiln update --all merges it, one worktree per repo. Repos quote kiln's workflows at the exact release they follow, so nothing reaches them between releases, and kiln update shows what is new in each release it crosses. A repo brought in by kiln adopt follows kiln's workflows at the latest release, moved forward by kiln update too.

The grid

kiln grid <ID>: one rule in full, with its reason, a source checked on a date, and how a repo can waive it.

One small TOML file per rule, on two axes: its theme (supply chain, containers, tests…) and its scope (universal, a language, a framework, a tool). Each says why, cites sources weighed in a fixed order (official docs, security advisories, measured studies, adoption data, blogs) and carries a level from Thoughtworks' Technology Radar: adopt, trial, assess, hold. Only adopted rules count: 40 of them (supply chain, CI, containers, tests, code standards, Django and Vue security), each run on two real repos for false positives; 95 drafts wait behind kiln grid --level assess. Each scored rule ships with a repo that passes it and one that fails it.

Compared with Copier and cookiecutter

kiln is Copier underneath: every project keeps its .copier-answers.yml, and plain Copier still works on it. kiln adds what comes after day one, and gives up some breadth for it.

kiln is opinionated on purpose. For a neutral templating engine, use Copier; for a workflow that stays maintained, use kiln, or fork it and make the opinions yours.

Reference

Every command and option, every kiln set key, the reusable workflows and the Claude Code plugins: docs/reference.md. In a terminal, kiln <command> --help.

Status

kiln runs a handful of real repos every day, one of them in production. One maintainer writes it with Claude Code, under the same rules it gives your repos. Releases are numbered like Claude Code's: in 0.x, each release bumps the patch, breaking changes come first in the changelog and kiln update converts them; the minor marks a milestone. Strict semver starts at 1.0. What comes next is for the repos you already have: any Django or Nuxt repo scored against the grid in seconds, then brought up to it by script wherever a script can (v0.5.0).

Contributing

Issues and pull requests are welcome: see CONTRIBUTING.md, the code of conduct, and the good first issue label to start. In a kiln repo, /kiln:report turns a kiln defect into a ready-to-post issue or pull request, posted only once you approve. If kiln saves you time, a star helps others find it.

License

MIT