When you code with Claude, the model does the typing — so the habits that keep AI-assisted work fast and safe are the ones easiest to skip: resetting stale context, committing in small steps, testing as you go, reading the diff before it lands, vetting what you install, and keeping credentials out of the code. vibehabit watches for the moment each one slips, drops one line, and then tracks whether you're starting to catch it yourself.

⚡ vibehabit: context is at 43% of your window (~85k tokens) — quality degrades past 40%; /compact to stay sharp.
⚡ vibehabit: 8 uncommitted edits across 3 files — commit a checkpoint before the next big change.
⚡ vibehabit: that commit went in without a git diff — read AI-written changes before you checkpoint them.

Why it's worth running

• Stop paying for context you don't need. Working past ~40% of your window degrades answers and burns money re-reading a context that went stale forty prompts ago. The context coach reads your session's real token usage and nudges you to /compact right at the line — measured from your own transcript, not a guess.
• Ship changes you've actually read. Smaller commits, tests run while the diff is still small, diffs read before they land, dependencies vetted, secrets kept out of the code. Honest process improvements — the ones the ledger can actually show — not an unfalsifiable "better code" claim.
• The actual product is needing it less. Every nudge fires once per streak — it reminds, it never nags — and the dashboard tracks your self-catch rate climbing week over week. Success is the nudge count going to zero.

Everything stays on your machine

Config, ledger, and reports live in ~/.vibehabit/ and are never uploaded. No accounts, no cloud storage, no telemetry, no analytics — and no vibehabit server anywhere in the loop. The one network call the coaching makes is the context coach sending your prompt to Anthropic under your own API key (BYOK) — you calling Anthropic directly, not us. License checks are an offline signature verification, so even paying never phones home.

The only thing that sends code anywhere is vibehabit audit, and only when you ask: a separate opt-in command that reviews diffs you've already accepted. It prints what it would upload and what it can cost, and waits for a yes. Only a finding's file, category, and severity are stored — never your code.

Try it in ~10 seconds

npm install -g vibehabit
vibehabit demo          # replays every coach's nudge — no API key, touches nothing
vibehabit install-hook  # registers the hooks in ~/.claude/settings.json

Then start a new Claude Code session for the hooks to take effect. vibehabit demo runs your nudges through the real coaching code, so what you see is exactly what fires in a session.

The coaches

| Coach | Signal | Nudge | |---|---|---| | Context hygiene | Your new prompt pivots away from the session's current work (scored by claude-haiku-4-5; coupling-aware — follow-ups, questions, docs, and coupled files are never flagged, and short context-dependent prompts like "done" or "what next" skip evaluation entirely) | ⚡ vibehabit: topic shift (auth middleware → tax calculation) — consider /compact to drop stale context. | | Context size | Measured context (read from the session transcript's real usage data) crosses default_target_pct of your window — the ~40% line where answer quality degrades; re-nudges only after size doubles | ⚡ vibehabit: context is at 43% of your window (~85k tokens) — quality degrades past 40%; /compact to stay sharp. | | Commit hygiene | Uncommitted edits pile past commit_edit_threshold (default 8); a git commit resets the streak | ⚡ vibehabit: 8 uncommitted edits across 3 files — commit a checkpoint before the next big change. | | Review hygiene | A git commit runs with no git diff/status/show since the previous commit that session | ⚡ vibehabit: that commit went in without a git diff — read AI-written changes before you checkpoint them. | | Test hygiene | Edits since the last test run pass test_edit_threshold (default 10); never nudges a project with no test setup | ⚡ vibehabit: 10 edits without a test run — run your tests now while the diff is small. | | Test-first (TDD) | Logic edits pile past tdd_edit_threshold (default 15) without a single test file being touched — running tests isn't enough | ⚡ vibehabit: 15 logic edits without touching a test file — pair new logic with a test while it's fresh. | | Dependency safety | An installed package name trips an offline risk check — one keystroke off a real package, whether a slipped letter (expres → express) or a swapped pair (lodahs → lodash). A plain install of a real package is normal work and never fires | ⚡ vibehabit: "expres" looks one keystroke off "express" — check the exact package name before building on it; typosquats run code on install. | | Secret safety | A well-known credential pattern (Anthropic/OpenAI/AWS/GitHub/Slack/Google/Stripe key, private-key PEM, JWT, connection string…) lands in any file that isn't .env*. Only the file and pattern kind are ever logged — never the secret | ⚡ vibehabit: possible Anthropic API key hardcoded in app.js — move it to an env var. | | Prompt secret hygiene | A credential is pasted into the prompt itself — the leak surface the file scans can't see. The match is redacted from your local history, not just flagged | ⚡ vibehabit: that prompt contains what looks like an Anthropic API key — reference the variable name instead of pasting the value; it was redacted from your local session history. | | Remediation follow-through | A flagged secret is still in the file after another edit — the first nudge didn't land | ⚡ vibehabit: the Anthropic API key in config.js is still there after another edit — remove it now, before it reaches a commit. | | Privilege scoping | A risky action (install, rollback, destructive command) runs while permissions are bypassed. Once per session — a mode set on purpose shouldn't nag | ⚡ vibehabit: a risky action ran while permissions are bypassed (bypassPermissions) — drop back to default mode for installs and history rewrites. | | Suite integrity | A committed test file carries a .only/.skip/xit. Dropping one while debugging is normal and never fires — checkpointing it is the deviation | ⚡ vibehabit: that commit includes a focus/skip marker (.only/.skip) in auth.test.js — it silently disables the rest of the suite. | | Work-loss protection | Local commits pile up against a remote (push_ahead_threshold). A repo with no remote never fires | ⚡ vibehabit: 7 commits are sitting unpushed — push to back them up, so a dead machine can't cost you the work. |

Every coach above is fully local (no API needed) except context hygiene, which uses your Anthropic API key (BYOK) for a ~1-second Haiku evaluation per prompt. A separate low-key reminder tells you when a newer vibehabit is on npm. Run vibehabit demo to see every one fire in about ten seconds — it's driven through the real coaches, so it can't drift from this table.

Install & upgrade

npm install -g vibehabit
vibehabit install-hook   # registers the hooks in ~/.claude/settings.json

Start a new Claude Code session for the hooks to take effect. That session opens with one line confirming vibehabit is live — how many coaches are running, whether the context coach found a key, and what will trip first. It's said once per install, and nothing after it speaks until you've actually earned a nudge. Requires Node 18+. For the context coach, add your API key via vibehabit config (or ANTHROPIC_API_KEY). No native modules — the install is pure JavaScript and never needs a compiler.

From source: npm install && npm run build && node dist/index.js install-hook.

To upgrade:

vibehabit update                    # checks npm and updates in place
# or, equivalently:
npm install -g vibehabit@latest

The hooks are registered as an absolute path to dist/index.js, which npm overwrites in place, so new coaching logic takes effect on your next session. The one exception is a release that changes which hooks vibehabit registers (a new event or matcher) — re-run vibehabit install-hook for those. You don't have to track which releases they are: vibehabit notices a stale registration and tells you (see Troubleshooting).

Commands

| Command | What it does | |---|---| | vibehabit install-hook | Registers vibehabit's four Claude Code hooks (UserPromptSubmit, PreCompact, PostToolUse, SessionStart). Non-invasive; vibehabit uninstall-hook removes them cleanly. | | vibehabit demo | Prints what every coach's nudge looks like (~10s), driven through the real coaches. No API key needed; touches none of your files. | | vibehabit audit | Opt-in LLM review of diffs you have already accepted — the one command that sends code anywhere. Prices the run and asks first (--dry-run to see the price and send nothing; --since <ref> to narrow; --yes to skip the prompt). Needs your Anthropic API key and bills you directly. Only a finding's file, category and severity are stored — never your code. | | vibehabit doctor | Health-checks the install: hooks registered, API key present, ledger writable, build current. --api adds a live drift evaluation. | | vibehabit feedback | Opens a pre-filled GitHub issue to report a wrong nudge or a bug. Nothing is auto-sent — it opens your browser and you submit. Optional redacted diagnostics (version/platform/config + counts; never a key, path, code, or prompt); opt-in, shown before it's attached. | | vibehabit stats | Terminal dashboard: self-catch rate, commit + test hygiene, week-over-week trends. Free forever. | | vibehabit report | The full coaching report as a local HTML page (~/.vibehabit/report.html). Paid, fully available on the 14-day trial; stats stays free forever. | | vibehabit config | Settings — where reminders appear, which habits are on, topic-drift handling, sensitivity, context window + degradation line, the commit/test/TDD thresholds, and your API key. Guided when run bare (each prompt shows the recommended default); add set <key> <value>, get <key> or --list to change one setting without the walkthrough. | | vibehabit activate <key> | Validates and stores a license (offline Ed25519 check — no phone-home). Unlocks the full vibehabit report. vibehabit deactivate removes it. | | vibehabit export [path] | Backs up your local state (config + ledger) to one JSON file. --no-config omits key/license; --stdout pipes it. | | vibehabit import <file> | Restores an export bundle onto this machine (--force to overwrite existing state). | | vibehabit reset [--all] | Wipes your coaching history; --all also clears config/license. Previews first — pass --yes to confirm. | | vibehabit update | Updates to the latest release via npm. --check only reports availability; --dry-run prints the command. | | vibehabit completion <shell> | Prints a shell completion script (bash, zsh, or fish) to source from your shell rc. | | vibehabit --version | Prints the installed vibehabit version. |

Configuration — ~/.vibehabit/config.json

Run vibehabit config for a guided walkthrough (every prompt shows the recommended default), or change one setting in place with vibehabit config set <key> <value> — vibehabit config --list prints every key. You rarely need to edit the file by hand. The main fields:

{
  "anthropic_api_key": "sk-ant-...",
  "hook_mode": "notify",
  "nudge_delivery": "both",
  "sensitivity_threshold": 0.75,
  "commit_edit_threshold": 8,
  "test_edit_threshold": 10,
  "tdd_edit_threshold": 15,
  "context_window_tokens": 1000000,
  "default_target_pct": 0.4
}

• hook_mode — how the context coach handles a topic pivot: notify ("remind me" — a visible one-liner, non-blocking; default) · advise ("refocus only" — silently steers Claude's focus) · block (stops the prompt with a suggestion) · off (log only). The habit coaches are always non-blocking.
• nudge_delivery — where a visible reminder appears (applies to every coach): both (a terminal notice and echoed in Claude's reply — default) · system (terminal notice only) · inline (in Claude's reply only).
• sensitivity_threshold (0.1–1.0) — drift score needed to flag a pivot; lower = more aggressive.
• commit_edit_threshold / test_edit_threshold / tdd_edit_threshold — edits allowed to pile up before each respective nudge.
• context_window_tokens — your model's context window (default 1000000; set 200000 for a 200k-window model). A starting assumption: per session vibehabit overrides it with whatever the transcript proves — a [1m] model marker, measured context exceeding the configured value, or an auto-compaction firing under 500k (a 200k ceiling).
• default_target_pct — the degradation line as a fraction of the window (default 0.4): the context-size coach nudges past it and the dashboard reports how often you work above it.

How the coaching loop works

1. Observe — a PostToolUse hook logs every Edit/Write, git commit, and test command to the local ledger (~/.vibehabit/session_history.jsonl); a PreCompact hook records every context reset you perform.
2. Detect — on each prompt submit, a UserPromptSubmit hook checks the habit counters and (with an API key) scores topic drift against your recent prompts + git status, with a structured-output Haiku call.
3. Nudge — a single visible line, surfaced as a terminal notice and/or echoed in Claude's reply (your nudge_delivery choice). Fires once per streak; fails open on any error (it can never block your work).
4. Measure — vibehabit stats / vibehabit report track nudges vs. self-catches week-over-week. The goal is the nudge count going to zero: the product working means you needing it less.

Free vs. paid

Free forever: every coach and vibehabit stats — the terminal dashboard never checks a license. Paid: the full vibehabit report (conductivity tiers, achievements, graduation curves) as a local HTML page. It's live during the automatic 14-day trial — counted from your first ledger event, no signup, no account. After that, a one-time license (vibehabit activate <key>) unlocks it; your ledger stays intact and renders in full the moment you activate. The license is verified offline against a baked-in public key — even paying never phones home. Get a licence at vibehabit.io.

Troubleshooting

For day-to-day use — tuning a coach that's nagging, turning one off, what to do when a nudge is wrong, and reading the dashboard — see the usage guide.

Run vibehabit doctor first — it checks that the hooks are registered, your API key is present, the ledger is writable, and the build is current.

A coach never fires. When a release adds a new hook event or matcher, an older registration can go stale, and an unregistered coach fails silently — it doesn't error, it just never runs, and the metric it feeds reads zero. Every prompt, vibehabit compares the hooks on disk against the ones this build expects and says so once if they've diverged:

⚡ vibehabit: hook registration is stale (missing SessionStart) — /clear
   self-catches aren't recorded. Run `vibehabit install-hook`.

Re-running vibehabit install-hook fixes it (nothing else may write to ~/.claude/settings.json).

Coaching feels out of date. The stale-registration check compares which hooks are registered, so it can't see a stale build: if a global upgrade half-failed or a hook still points at an old source checkout, the events match and vibehabit keeps running old logic. vibehabit --version confirms what you're actually running.

Notes & limitations

• Hooks fail open everywhere: an evaluator error, unreadable payload, or missing key can never block a prompt or a compaction.
• The context coach needs prompt history — it never fires on the first prompt of a session, and slash commands are never scored.
• Claude Code offers no pre-Enter interception, so nudges arrive with the reply to the prompt that crossed the line — which is exactly what makes vibehabit a trainer rather than an autopilot: you act on the next one yourself.