merging-claude-settingslisted
Install: claude install-skill ontech7/ollama-usage
# Merging Claude settings
## Overview
`ollama-usage setup` writes into a file the user owns and shares with every
other tool: `~/.claude/settings.json` (or the project's with `--project`). The
governing rule is **never clobber what you did not write.**
File: `src/ollama_usage/setup.py`.
## The four invariants
1. **Read defensively.** `read_settings` returns `{}` for a missing file, a
corrupt file, or valid JSON that is not an object. It never raises — a
broken settings file must not break `setup`.
2. **Merge, don't replace.** `merge_status_line` / `merge_update_hook` mutate
the dict in place and return `True` only if something changed. Every
unrelated key, and every unrelated `SessionStart` hook, survives untouched.
3. **Idempotent.** Running `setup` twice writes once. If the value already
equals what we'd write, the merge returns `False` — even with `--force`.
4. **Atomic write.** `write_settings` writes to a `tempfile.mkstemp` in the
*same directory* then `shutil.move`s it into place, so a crash never leaves a
truncated settings file. It returns `False` on `OSError`; the CLI turns that
into exit `1`.
## What `--force` means here
`--force` is narrower than "overwrite the file":
- `statusLine`: replaces an existing one (any command).
- update hook: replaces **only the managed hook** — the entry whose command
contains `ollama-usage update-check`. Other `SessionStart` hooks are never
touched, never reordered, never removed. If no managed hook