kiln 🔥

Start every project like a senior engineer would — even if you're not one.

Three questions, and Claude Code gets a modern repo: stack chosen for you, tests, CI, guardrails, a GitHub repo — kept up to date for as long as the project lives.

English · Français

Claude Code writes code fast, but a real repo needs more than a prompt: an up-to-date stack, rules the agent cannot talk its way around, a sane git workflow, and someone to stop the repo from going stale on day ninety. kiln brings all four. Built on Copier, it generates the repo, wires Claude Code into it, and keeps every repo you own current:

• 🧱 kiln new — three questions (what you are building, its size, your language), then a complete repo: code, tests, linters, CI, pre-commit, containers, a CLAUDE.md for AI agents, a GitHub repo with protected branches.
• 🎛️ kiln set — change your mind later. kiln set frontend=nuxt podman=true re-renders the repo; a removed framework takes its files with it.
• 🔄 kiln update — pull template improvements and dependency upgrades into an existing repo, then run the checks before anything is committed. Local edits are kept; real conflicts are marked inline.
• 🚚 kiln update --all — do it for every kiln repo in ~/code at once: one worktree per repo, small commits, merge only when the checks pass.
• 📏 charter — a rule engine for things linters don't catch (no pip/docker, file-size ratchets, Django locks, personal-data patterns, coverage floors…), declared per repo in charter.toml. Disagree with a rule? kiln waive it in kiln-waivers.toml, with a reason and an expiry that grows with each renewal (a week, a month, three months, six months).
• 🤖 Claude Code native — every generated repo ships agent instructions and enables kiln's Claude Code plugins (branch guards, worktree/merge/release skills, status line).

Quick start

# 1. Install (needs uv and git; Python 3.14 is fetched by uv if missing).
#    macOS, Linux, and Windows through WSL. The PyPI package is kiln-cli, the command is kiln.
uv tool install kiln-cli
#    …or try it without installing anything: uvx kiln-cli new my-app
#    Tab completion in bash: add  eval "$(kiln completion bash)"  to ~/.bashrc

# 2. Create a project — answer a few questions, or pass them as flags
kiln new my-app
kiln new my-api --size ember --type api --backend fastapi --no-github

# 3. Work in it
cd my-app
kiln dev       # start the dev servers of the stack
kiln check     # ruff, mypy, pytest, ESLint, type checks, then charter

# 4. Months later
kiln update            # template changes + compatible dependency upgrades + checks
kiln update --major    # major versions too

kiln new creates a private GitHub repo by default (via gh); --no-github skips it. Optional tools: pnpm for JavaScript fronts, a JDK 25 for Java, podman for containers.

What you get

Backends: django, fastapi, data, cli, java (Java 25 + Maven, no framework). Frontends: nuxt, next, astro, streamlit, dash. Every combination is generated and validated by the test suite.

Each generated repo comes with:

• Opinionated tooling, no pip, no docker: uv for Python, pnpm for JavaScript, podman for containers; ruff, mypy (strict), pytest + coverage floor, ESLint, pre-commit (which also refuses commits on main/develop).
• CI on GitHub Actions that calls kiln's reusable workflows — so fixing CI once in kiln fixes it everywhere.
• A project size (spark → ember → flame → blaze) that tunes defaults: a weekend script doesn't get the same ceremony as a multi-team service.
• Agent-ready instructions: kiln's rules for Claude in .claude/rules/kiln/, with stable rule IDs the charter engine can check; each stack's rules load only when Claude touches its files. The root CLAUDE.md belongs to the project.
• Optional production setups: a hardened VPS deployment for Django (Caddy with automatic TLS, read-only containers, one image per commit, automatic rollback, daily backups with restore tests) and Vercel deployment for Nuxt fronts.
• A backlog (docs/backlog/: typed T-NN tickets by priority) that Claude Code's status line counts.

Why not just Copier / cookiecutter?

kiln is Copier underneath — every project keeps its .copier-answers.yml, so you can always fall back to plain Copier. What kiln adds is everything around the template:

kiln is opinionated on purpose. If you want a neutral templating engine, use Copier directly; if you want a batteries-included workflow that stays maintained, use kiln — or fork it and make the opinions yours.

Commands

Full reference (in French): README.fr.md.

Reusable GitHub workflows

kiln's workflows work from any repository, kiln-generated or not:

jobs:
  backend:
    uses: antoine-tena/kiln/.github/workflows/django.yml@v0.3.0   # a kiln release tag

django.yml, python.yml, maven.yml, pnpm.yml, charter.yml, security.yml (uv audit, pnpm audit), secrets.yml (gitleaks), api-contract.yml, infra.yml (podman build, actionlint, shellcheck), sbom.yml (CycloneDX), mutation.yml (mutmut), vercel.yml. Databases for tests run in podman. See .github/workflows/.

Claude Code plugins

kiln is also a Claude Code plugin marketplace:

claude plugin marketplace add antoine-tena/kiln
claude plugin install kiln@kiln

Generated repos enable the right plugins for their stack automatically.

Status

kiln is used daily on a handful of real repos, including one in production. It is young, so it numbers releases like Claude Code does: in 0.x, every release bumps the patch, breaking changes included (0.3.4 → 0.3.5), listed first in the release notes and migrated by kiln update; the minor only moves for a milestone. Strict semver starts at 1.0. Each release is first a candidate (v0.3.5-rc.1) used on the author's own repos; it is promoted to main (v0.3.5) only once the next candidate is ready, so a release never needs an emergency fix. Projects are generated and updated from the latest release, pin kiln's workflows to that exact tag, and kiln update shows what changed in each release it applies (see CHANGELOG.md). Linux, WSL and macOS are supported.

Contributing

Issues and pull requests are very welcome — see CONTRIBUTING.md. Small fixes can go straight to a PR; for bigger changes, open an issue first so we agree on the approach. Good places to start: the good first issue label. Using Claude Code in a kiln repo? /kiln:report turns a kiln defect into a ready-to-post issue or PR: checked against the latest release and the existing issues, scrubbed of anything private, posted only once you approve.

If kiln saves you time, a ⭐ helps other people find it.

License

MIT