Contributing to Kiln

April 24, 2026 · View on GitHub

Issues and Bug Tracking

We use GitHub issues for tracking issues, bugs, and feature requests.

Contributing

New contributors must agree to the contributor license agreement.

Development Environment Setup

We use uv to manage the Python environment and dependencies, and npm to manage the web UI.

# First install uv: https://github.com/astral-sh/uv
uv sync
cd app/web_ui
# install Node if you don't have it already
npm install

Environment Variables

The web UI has optional dev-only environment variables. See app/web_ui/.env.example for details.

Running Development Servers

Running the web-UI and Python servers separately is useful for development, as both can hot-reload.

To run the API server, Studio server, and Studio Web UI with auto-reload for development:

  1. In your first terminal, navigate to the base Kiln directory:

    uv run python -m app.desktop.dev_server

  2. In a second terminal, start the web UI dev server:

    make ui

  3. Open the app: http://localhost:5173/run

Makefile

The root Makefile provides convenient shortcuts for commonly used scripts (make dev, make ui, make package, ...).

Running and Building the Desktop App

See the desktop README instructions for running the desktop app locally.

Tests, Formatting, and Linting

We have a large test suite, and use ruff for linting and formatting.

Please ensure any new code has test coverage, and that all code is formatted and linted. CI will block merging if tests fail or your code is not formatted and linted correctly.

To confirm everything works locally, run:

uv run ./checks.sh
  1. Setup pre-commit hook.

In your base Kiln directory, run the following command to setup a pre-commit hook which will run the Kiln checks locally before each commit.

cp .config/utils/pre-commit-hook .git/hooks/pre-commit
  1. Spec Skill

We use the spec from this project for planning: https://github.com/scosman/vibe-crafting

To install (adapt to your tooling):

# Outside of the project
git clone git@github.com:scosman/vibe-crafting.git

# Claude Code
mkdir -p ~/.claude/skills
ln -s "$(pwd)/vibe-crafting/skill" ~/.claude/skills/spec
# Optional: add Read access to your skills path to ~/.claude/settings.yaml

# Cursor
mkdir -p ~/.cursor/skills
ln -s "$(pwd)/vibe-crafting/skill" ~/.cursor/skills/spec

Optional Setup

IDE Extensions

We suggest the following extensions for VSCode/Cursor. With them, you'll get compliant formatting and linting in your IDE.

  • Prettier
  • Python
  • Python Debugger
  • Ty - language server and type checker for Python
  • Ruff
  • Svelte for VS Code
  • Vitest
  • ESLint

HooksMCP

We have a hooks_mcp.yaml file, which defines how coding agents can interact with our developer tools (formatting, linting, etc).

To use it, setup HooksMCP for your agents.

llms.txt

Vibing? Here are some llms.txt you may want to add.

Usage: @docs Svelte in cursor lets the LLM read the docs of the specified library. Most popular libraries added by Cursor automatically, but here are some to add manually: