Skip to main content

Environment doctor

Kiln leans on tools it doesn't ship: git for diffs and the overview, the GitHub CLI (gh) for to-dos and PRs, the claude and codex binaries for terminal handoffs, an API key for the cloud backends, Apple Intelligence for the on-device assistant. If you already have all of that installed — the way a seasoned developer does — Kiln just works. If you don't, the old failure mode was quiet: features simply didn't appear. There was no explanation or suggested fix.

The environment doctor is the cure. It's a single checklist that probes your machine, says what's missing, and offers the fix right beside it.

The checklist​

Settings ▸ Environment runs every check the moment you open it, in dependency-first order, so the thing you have to fix first sits at the top:

  1. Xcode Command Line Tools — Homebrew and anything that compiles need them.
  2. Homebrew — Kiln installs the rest of your tools through it.
  3. git — diffs, the overview, and the changes surface all shell out to it.
  4. GitHub CLI (gh) — the to-dos, PRs, and failing-CI surfaces read from it.
  5. Claude Code CLI — squad handoffs launch the claude binary.
  6. Codex CLI — Codex handoffs launch the codex binary.
  7. ANTHROPIC_API_KEY — the cloud backend and Claude handoffs read it.
  8. OPENAI_API_KEY — the Codex backend and handoffs read it.
  9. Apple Intelligence — the on-device assistant and the ambient squad need it on.

Each row carries a status badge and, when something's wrong, an action:

  • Fix (amber) — Kiln can install it for you. The button runs the real command (brew install gh, xcode-select --install, the official Homebrew or Claude Code installer) behind a confirm that shows you exactly what will run. Kiln never runs an install unasked.
  • Action (info) — Kiln can't do it for you, but it routes you somewhere useful: the Providers tab to paste an API key into the Keychain, System Settings to turn on Apple Intelligence.
  • OK (green) — found and configured, nothing to do.

A turned-off provider goes quiet: if you've switched Codex off in Providers, its CLI and key stop nagging — they report OK as "not in use" rather than flagging a dependency you opted out of.

The doctor isn't a once-and-done gate. Keys expire, Homebrew breaks, a CLI falls off PATH — so Re-check re-probes any time, and the tab does it automatically every time you open it.

The onboarding nudge​

A brand-new machine shouldn't have to go looking for this. The last step of onboarding quietly probes your setup; if anything's outstanding, it shows a small card — "N things to set up" — with a Review setup button that finishes onboarding and drops you straight onto the checklist. When everything's already there, the card never appears.

How it works​

The environment doctor probes your machine off the main thread, gathers the results, and runs fixes through a login shell when you approve them.

A key you pasted into Settings (stored in the Keychain) counts the same as an exported environment variable — the doctor treats resolved credentials as present, so a stored key doesn't trigger a nag.