himmel guide

The installer, step by step

One command asks you a short series of questions, shows you a summary, and only then changes anything. Pick your path below to see exactly which questions you will meet, what the terminal shows, and what each answer does.

Every step

These are all the questions the installer can ask, in order, each with an example answer; the prompt names the default. Which of the later ones you meet depends on your earlier answers: for example, choosing no companion vault skips every vault question. With scripts enabled, this becomes an interactive stepper for your own path.

1 Prerequisites tools + one command

himmel is a harness for Claude Code, so Claude Code comes first. The installer then checks a handful of tools before it asks anything, and stops with an install hint if one is missing.

# 1. Claude Code itself (Linux/macOS)
$ curl -fsSL https://claude.ai/install.sh | bash
# 2. clone himmel once, then run the installer from the repo you want it in
$ git clone https://github.com/yotamleo-org/Himmel himmel
$ node himmel/scripts/himmelctl/bin.js install --scope project
# no Node yet? run this first, then re-run install:
$ bash himmel/scripts/himmelctl/bootstrap.sh

What you see

  • A hard check for bash, git, jq and python3, plus npm or bun (npm is the one it recommends).
  • A missing tool stops the run before the first question, with the command to install it.

What it does

  • Nothing yet. No question has been answered, and nothing on your machine has changed.
2 Profile how much to set up

The first question picks a starting point. A profile only fills in the default answers for the questions after it; it never skips a question.

? profile [starter|luna|operator|custom] (default: starter)
  1) starter (recommended — press Enter) — core harness: hooks, guardrails, worktrees, statusline, jira CLI
  2) luna — starter + the second-brain surface, nothing else (vault/qmd/cadences/PHI/secrets/bridge questions)
  3) operator — the maintainer machine as a consumable profile (seeds defaults ONLY; lanes and every has-it-or-not feature are still asked)
  4) custom — walk every question from scratch, no seeding
> starter

What you see

  • Four numbered options. Press Enter for starter, or type a number or a name.

What it does

  • The core harness only: hooks, guardrails, worktrees, the status line and the Jira CLI.
3 Scope this repo or every repo

Where the installed config lives. The --scope flag you passed fills in the default.

? scope [project|user] (default: project)
  1) project (recommended — press Enter) — this install's config lives inside this repo's own .claude/ — wire it again separately for another project
  2) user — this install's config lives at ~/.claude/ — applies once, to every project you open
> project

What you see

  • Two options; Enter keeps the value from --scope.

What it does

  • project wires this repo only. user wires your user-level Claude Code config, so every project you open gets the harness.
4 Companion vault with or without notes

himmel can run with a companion vault: an Obsidian folder of notes, clips and daily entries that its scheduled jobs keep indexed. Saying none skips every vault question below.

? vault [none|default-template|existing] (default: none)
  1) none (recommended — press Enter) — no second brain on this machine; every vault question below is skipped
  2) default-template — scaffold a fresh vault from templates/luna-second-brain
  3) existing — point at the Obsidian vault you already have (in-place, STAMPED-gated upgrade)
> none

What you see

  • The vault menu only.

What it does

  • No vault. The privacy and Telegram questions are skipped, and only the general scheduled jobs are offered.
5 Handover notes where sessions save state

Each session can end by writing a handover: what it did and what is next, so the next session picks up the thread. This is where those notes live.

? handover [inline|external] (default: inline)
  1) inline (recommended — press Enter) — no-op — handover state stays in this repo's own handovers/ (adopt.sh/setup.sh default)
  2) external — persists HANDOVER_DIR to an external state repo you point at next
> inline

What you see

  • The menu only.

What it does

  • Notes stay in this repo’s handovers/ folder. Nothing is written for this answer.
6 Extra lanes other model families

A lane is another model family himmel can hand work to. Both are opt-in and need their own tools and logins. They matter mostly for review: a second model family catches what Claude misses.

note: codex and hermes add cross-model review to /pr-check — Claude tiers
  remain the only v1 implementation lanes (select codex/hermes below, or use
  --with-codex / --with-hermes non-interactively). Without one, the /pr-check
  review panel runs Claude-only, and CR_REQUIRE_CROSS_MODEL cannot be satisfied
  (see docs/configuration.md).
? lanes [codex,hermes|none] (default: none)
  1) codex — requires the codex CLI + its own login; skip if you don't have it
  2) hermes — gateway lane; own opt-in, own install profile, own credentials
  (Enter accepts the recommended default; comma-separate multiple numbers)
> none

What you see

  • A note on what lanes change, printed once, then a multi-select. Enter means none.

What it does

  • No extra lanes. Review is Claude-only, which always runs; a policy that demands a second model family cannot be met.
7 Always-on machine unattended runs

Will this machine run work while you are away, such as scheduled jobs or overnight shifts?

? always-on machine (unattended/scheduled runs) [yes|no] (default: no)
  1) yes — print the unattended/scheduled-run hardening checklist (nothing is executed either way)
  2) no (recommended — press Enter) — print a one-line pointer to the checklist instead
> no

What you see

  • Two options.

What it does

  • yes prints a hardening checklist for unattended machines; no prints a one-line pointer to it. Neither runs anything.
8 Test VM where risky steps are proved

Some jobs change your machine on a timer, so himmel wants them proved on a throwaway test VM first. Tell it where that VM is.

? vm.mode — where VM-proof steps run [local|remote|none] (default: local)
  1) local (recommended — press Enter) — the local test VM (ssh localhost:2222) — the default
  2) remote — a VM you reach over ssh (asks for user@host, port, identity)
  3) none — no VM available — VM-proof steps need an operator ack + rollback point
> local

What you see

  • Three options; remote asks three more fields.

What it does

  • VM-proof steps run on the local test VM over ssh on port 2222.
  • Saved as vm in ~/.himmel/config.json.
9 Scheduled jobs what runs on a timer

A menu of recurring jobs you can arm now. Only jobs whose requirement your answers meet are listed, and nothing arms unless you choose it.

? cadences — recurring scheduled jobs to arm now [drift-fix,upstream-watch,doctor|none] (default: none)
  1) drift-fix — nightly /drift-fix (bump auto-bumpable pins, open an ordinary PR)
  2) upstream-watch — daily scan of himmel's open upstream PRs/issues for a delta
  3) doctor — daily himmel-doctor run from the primary checkout
  (Enter accepts the recommended defaults; comma-separate multiple numbers)
> none

What you see

  • 3 jobs on offer for your path.
  • If you decline a job that is already armed from an earlier install, one more question asks whether to disarm it now.

What it does

  • Each chosen job is armed with its own script; the rest are recorded as off. See the loops and graphs guide for what each job does.
10 Health data privacy declaration

If your vault will hold health records, himmel keeps them away from models outside your machine. It asks you to declare that, and prints the checklist you complete by hand.

── PHI checklist — READ ONLY, himmelctl creates none of this ──────────────
  [ ] 1. drop a `.salus` marker file at the vault root (or an ancestor dir)
  [ ] 2. add the vault's absolute path as a line in ~/.config/claude-glm/phi-roots
  [ ] 3. add the relevant path(s)/pattern(s) to ~/.config/claude-glm/egress-denylist
? does this vault handle Protected Health Information (PHI)? [yes|no] (default: no)
> no

What you see

  • A read-only checklist, then a yes/no question you must type in words. A bare number is not accepted here.
  • A second question asks about a separate personal or medical vault.

What it does

  • Records your answer only. The markers themselves are yours to create.
11 Telegram bridge voice and text notes

An optional bridge that turns Telegram voice and text messages into vault notes, transcribed locally with whisper.

? configure the telegram bridge (voice/text ingestion)? [off|on] (default: off)
  1) off (recommended — press Enter) — no telegram bridge configured
  2) on — configure telegram voice/text ingestion (.env path, whisper CLI/model, optional persistence)
> off

What you see

  • Two options; on asks for the bridge’s own .env path, the whisper program, the model and whether to keep it running.

What it does

  • Off writes nothing. The bridge keeps its token in its own .env file.
12 Secrets tokens stay yours

Tokens and API keys stay out of the answers file. The installer can walk you through them: it shows each secret's status, then you keep, set or skip it. A value you type is hidden as you type and goes to a private file only you can read.

? walk through secrets now (status, then keep/set/skip per secret with a masked prompt; the answers file records status only) [run|skip] (default: skip)
  1) run — show each secret status, then keep / set / skip it; a typed value goes to the 0600 store, never the answers file
  2) skip (recommended — press Enter) — skip the walk-through
> run

What you see

  • A menu, then for each secret its status and a keep, set or skip choice. A value you set is typed at a masked prompt.

What it does

  • The answers file records each status only, never the value. Skip it and add what you use to .env by hand; the .env.example file lists every optional secret. Every integration is optional.
13 Commit rules tracker and ticket IDs

The last question sets how commits name their work: which tracker you use and whether every commit must carry a ticket ID. Nothing is written until you say yes.

? tracker [jira|local|none] (default: jira)
  1) jira (recommended — press Enter) — commits name a ticket like ABC-123; the Jira secrets are offered later
  2) local — commits name a ticket from your local ticket files; no Jira secrets asked
  3) none — no ticket tracker; a commit needs no ticket ID
> jira
? ticket ID required [yes|no] (default: yes)
  1) yes (recommended — press Enter) — the commit-msg gate refuses a commit that names no ticket
  2) no — a commit may omit the ticket ID
> yes
? ticket ID pattern (regex; blank = the commit gate's own default)
> 
? write these commit rules to ~/.himmel/himmel.conf now (TRACKER=jira, TICKET_ID_REQUIRED=1; consented, --dry-run shows it) [yes|no] (default: no)
> yes

What you see

  • A tracker menu, a yes/no for required ticket IDs (skipped when the tracker is none), an optional pattern, then a typed yes or no before anything is written.

What it does

  • Yes agrees to the write: once you confirm the plan, TRACKER, TICKET_ID_REQUIRED and any pattern go to ~/.himmel/himmel.conf as KEY=value lines. No leaves the file untouched.
14 Summary nothing is installed before this

Every answer so far, apart from a secret you chose to set, was only collected. Now you see the full plan and the exact command it will run, and you confirm once.

…your answers, one per line…
derived: adopt.sh --scope project …
Proceed? [Y/n]
> 
✓ installed — re-run any time: it converges, it does not duplicate

What you see

  • A summary of your answers, the derived command, and one confirm that defaults to yes.

What it does

  • Add --dry-run to the install command to see the same plan and stop there.
15 Your config file rules you can edit

The commit rules you confirmed land in a plain file you can read and edit: ~/.himmel/himmel.conf. Re-running the installer updates those lines and leaves every other line alone.

himmelctl: wrote TRACKER, TICKET_ID_REQUIRED to ~/.himmel/himmel.conf
# the file
TRACKER=jira
TICKET_ID_REQUIRED=1

What you see

  • One line naming the file and the keys written.

What it does

  • Everyday settings are KEY=value lines in himmel.conf; an environment variable still wins over the file.
16 Your first session the loop starts

The harness only acts inside a Claude Code session. Open one at the repo root and run one change through the loop.

$ claude
> /worktree my-first-change
  …edit, commit, push…
> /pr-check
> /handover
# later, to steer many sessions from one:
> /chief new

What you see

  • Hooks fire on every tool call from here on: editing on main is refused, commits are checked, a review is required before a pull request.

What it does

  • /worktree gives you an isolated branch, /pr-check reviews the diff, /handover saves where you stopped.

Your path

A profile seeds the defaults; you can still change every answer.