himmel guide

Loops and graphs

himmel keeps work moving with a few loops: AFK (unattended) runs and scheduled jobs that keep everything fresh. How one change travels from a supervisor session's dispatch to a merged pull request has its own page, the development graph. Its graphs map the code so sessions can find their way. Change a setting on the right and see which loop it touches.

Where settings live

Settings are moving out of .env into a config file you can read and track. Each setting below carries a tag that names where it lives in this new layout.

himmel.confnew layout

Everyday settings

Plain KEY=value lines in ~/.himmel/himmel.conf. If you run the companion vault, the file is tracked there through a symlink, so your settings follow you between machines. A himmel.conf.local file beside it overrides it for one machine.

policynew layout

Gate policy

Three settings decide how strict the review and merge gates are. They live under policy in ~/.himmel/config.json, a file the agent cannot write. The environment cannot override them, so a session cannot loosen its own gates.

.env

Secrets only

API tokens and credentials, such as JIRA_API_TOKEN. Nothing else belongs here in the new layout. A few runtime switches, like the graph refresh backend, stay plain environment variables.

Who wins, highest first: environment→himmel.conf.local→himmel.conf→.env (older installs)→built-in default

The loop explorer

Pick a loop, then change a setting. Steps that change light up, and the box under the settings says what happened in plain words.

Each loop below shows who does every step at the default settings a fresh install has. With scripts enabled, this becomes an explorer where changing a setting lights up the steps it changes. For how one change travels from dispatch to merge, see the development graph.

AFK modeAn unattended AFK shift

/afk-shift fans a fixed list of well-scoped tickets out to agents inside one session while you sleep. HIMMEL_AFK switches which steps run without asking. source: afk-mode

  1. Queue lock one run per queueon its own

    Taken first, so a second launch on the same queue stops instead of doubling the work.

  2. Ticket start from onegate

    Every commit subject and pull request title carries its ID; the commit-message gate refuses one without it. Extend an existing ticket before filing a new one.

  3. Plan from the briefon its own

    A written plan for the ticket, committed beside the handover.

  4. Implement agentsyou

    HIMMEL_AFK is off: the afk initiative profile is not active.

  5. Review /pr-checkyou

    The free tier runs; with no free critic configured it falls back to the codex critic where that lane is set up, else a Claude review.

  6. Fix and re-review until cleanon its own

    Review rounds repeat until no critical finding is left.

  7. Pull request openedyou

    Waits for you.

  8. CodeRabbit on the pull requestgate

    Reviews the pull request once it opens and posts threads and a commit status. Every thread it posts must be resolved before the merge: fix it, or reply with why and resolve it.

  9. Review gate at the headgate

    Waits until every hard reviewer (codex) passes at the head and no reviewer has an open finding.

  10. CI release ci:go, plannednot running

    Planned, opt-in per repository. Not opted in: CI runs on every push, as today.

  11. Merge private repoyou

    Not enabled: the run stops at the pull request. With ARMAUTOMERGE off, merge-on-green refuses, so a merge is a plain squash merge.

  12. Close ticket trackeryou

    A merge does not close the ticket by itself: if the pull request finishes it, you move it to Done.

  13. Handover next sessionyou

    Writes the next session’s brief and files follow-up tickets.

Scheduled jobs Scheduled jobs

Each job is a crontab entry or scheduled task that you arm on purpose. Nothing arms itself, and the installer only offers the jobs whose requirement holds. source: cadence-registry.json

  1. doctor dailyyou

    Daily health check. Reports only, fixes nothing. Always offered.

  2. upstream-watch dailyyou

    Scans himmel’s open upstream pull requests and issues; notifies only on a change. Always offered.

  3. drift-fix nightlyyou

    Bumps pinned dependencies and opens an ordinary pull request. Never merges. Always offered.

  4. pipeline daily + weeklynot running

    Offered only when you run a companion vault.

  5. qmd dailynot running

    Offered only when you run a companion vault.

  6. graphmap hourlynot running

    Offered only when you run a companion vault.

  7. vault-stall every 15 minnot running

    Offered only when you run a companion vault.

  8. pull-cadence dailynot running

    Offered only once GOOGLE_HEALTH_REFRESH_TOKEN is set.

Graph refresh Keeping the code graph fresh

Part of the graphmap job. A dedicated worktree does the refresh, so the checkout you work in is never switched or dirtied. source: graph-cadence internals

  1. Structural pass hourly :15not running

    graphmap is offered only with a companion vault. Re-parses the code; costs nothing.

  2. Measure every 6 h :35not running

    graphmap is offered only with a companion vault. Counts the commits on main since the graph was built.

  3. 15 behind? else skipnot running

    Below 15 commits it records a skip and stops. The threshold is fixed in the script, not a setting.

  4. Publish PR chore branchnot running

    Opens or refreshes a pull request with the new graph. Never a direct push.

  5. Merge on green merge-on-greennot running

    merge-on-green refuses without ARMAUTOMERGE; the pull request waits for you.

  6. Semantic pass weeklynot running

    graphmap is offered only with a companion vault. With claude-cli (Sonnet): draws on your Claude subscription usage budget and skips itself when the budget is nearly spent. GRAPH_CADENCE_SEMANTIC_BACKEND applies when the refresh runs with its semantic step.

  7. Ledger one line per runnot running

    Every run appends what it did (skipped, refreshed, published, merged or failed); the doctor surfaces failures.

Settings what each one changes
HIMMEL_INITIATIVE
Which steps a session runs without being asked once work is finished and verified. "all" means review, open the pull request, move the ticket and write the handover. Merging is never in the default set.
TICKET_ID_REQUIRED
Whether every commit subject must carry a ticket ID. Set it to 0 if you do not track work in a tracker.
HANDOVER_DIR
Where session handovers are saved. Unset keeps them in the repo’s handovers/ folder; a path points at a separate state repo that outlives any one clone.
HIMMEL_WORKTREE_NUDGE
A gentle reminder to start a worktree before editing. Editing on main is refused either way.
CR_PROFILE
Which critics review your diff in /pr-check. "none" is Claude only and spends nothing outside your plan; "paid" runs the codex panel. A missing critic never means no review: Claude reviews the diff itself.
CR_CLAUDE_AGENTS
Adds a fan-out of Claude reviewer agents inside /pr-check.
CR_REQUIRE_CROSS_MODEL
Gate policy. When on, the review-owed marker clears only after a critic from a different model family has passed the exact commit, so a Claude-only review is not enough.
CR_FLOOR_FALLBACK
Gate policy. With the cross-model rule on, "claude-only" lets a fresh Claude review with no shared context stand in when every other critic is out of quota. It is never counted as cross-model.
codex mode
The codex critic’s row in critics.json. As shipped it is hard and required: it must pass at the head, and absent on a machine it still counts, as unavailable, which holds the merge.
claude mode
The Claude API critic’s row. As shipped it is hard, but absent while the Claude API lane is off, so it leaves the set. Change any mode for one machine in critics.local.json.
coderabbit mode
The CodeRabbit app’s row. As shipped it is best-effort: an open thread holds the merge, but a missing or rate-limited review is relaxed to a NOTE. Absent means the app is not armed here.
review
Set "review": "no_code_review" in critics.json to say on purpose that no reviewer gates this repo, so CI alone decides. Without it, a set with no hard reviewer left is a config error and the gate refuses.
CodeRabbit right now
Not a setting: try what a rate limit does. A best-effort CodeRabbit is relaxed and the head moves on; a hard one holds the merge.
CI release
Planned, opt-in per repository. The heavy CI jobs wait for the ci:go label, which the station adds once the review gate passes at the head. Off, CI runs on every push. It never lets anything merge.
HIMMEL_AFK
Switches sessions to the afk initiative profile, read from HIMMEL_INITIATIVE_AFK instead of HIMMEL_INITIATIVE.
HIMMEL_INITIATIVE_AFK
The afk step list. "all" adds implementing and merging to the daytime set. It has no effect unless HIMMEL_AFK is on.
ARMAUTOMERGE
Gate policy. Arms merge-on-green, the one merge path that waits for green CI and confirmed branch protection. Off, merge-on-green refuses.
companion vault
Your installer answer about a second-brain vault. The vault jobs (pipeline, qmd, graphmap, vault-stall) are offered only with one.
vm.mode
Where steps that need proof on a test VM run: the local VM, a remote one over ssh, or none. With none, arming a VM-gated job needs your explicit pick as an acknowledgement.
graphmap
Arming this job runs the hourly structural refresh, the weekly semantic refresh and the 6-hourly publish of himmel’s own graph.
GRAPH_CADENCE_SEMANTIC_BACKEND
Which model does the graph refresh’s semantic step: claude-cli (default, uses your subscription usage budget) or ollama (local GPU). Any other value is refused before work starts.
See the development graph

    The graphs

    A graph here is a map of a body of text or code: every file, function and idea is a node, and the links between them are edges. Sessions ask the graph how things connect before they search file by file.

    The code graph

    himmel's own map, stored in graphify-out/graph.json. It groups the code into communities and marks its hub nodes, the files many others depend on.

    • Ask it: graphify query "…" or graphify explain "…".
    • A free structural pass reads the code itself. A weekly semantic pass has a model add meaning.
    • A refreshed graph reaches main only through a pull request that merges on green.

    The vault graph

    The same tool run over your companion vault, if you keep one: notes, clips and daily entries linked by topic. This graph stays on your machine and is not committed.

    • Structural pass daily at 00:05; semantic pass weekly, Sunday 13:00.
    • Search finds content; the graph explains how it hangs together.

    The flow diagrams

    Drawn by hand, not generated: how one change travels from your editor to main, what fires on every tool call, and how work is routed to other models.

    One day of graph refresh, once graphmap is armed

    Structural pass
    Every hour at :15. Free: no model, no subscription usage budget.
    Refresh and publish
    Every 6 hours at :35. Publishes only when the graph is 15 or more commits behind main; otherwise it records a skip.
    Semantic pass
    Weekly, Sunday 13:20 for himmel. Uses your Claude subscription usage budget and skips itself when the budget is nearly spent.