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, with no hint why or how to fix it.

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.

Where it lives​

The split is the project's usual pure/impure seam. Doctor (Config/Doctor.swift) is the pure half: it turns a DoctorProbe snapshot of the machine into ordered DoctorReport rows, each with a status and an offered fix, as a plain function with no side effects — so every check drops straight into a test (DoctorTests). DoctorModel (Config/DoctorModel.swift) is the live half: it gathers the probe off the main thread (shelling out for which/xcode-select, asking FoundationProvider whether Apple Intelligence is ready, folding in the resolved cloud credentials and the provider toggles) and runs the approved fixes through a login shell. DoctorView is the Settings tab. AppState.openEnvironmentDoctor() is the seam the onboarding nudge opens it through.

A key you pasted into Settings (stored in the Keychain) counts the same as an exported environment variable — the doctor folds the resolved credential into the probe, so a stored key reads as present and the row doesn't nag.