Vibehabit — the vibecoding habit coach for Claude Code

Great AI-assisted developers share a set of habits: they reset stale context, commit in small steps, test as they go (and write the test alongside the code), read every diff before it lands, vet what they install, and never let a credential touch the code. vibehabit coaches every one of them — until you don't need it anymore.

vibehabit installs as a set of Claude Code hooks — isolated child processes that observe your session without wrapping or touching Claude Code's display. It watches for the moments a best practice was missed, surfaces a one-line nudge, and — the actual product — measures whether you're starting to catch those moments yourself. A rising self-catch rate means the habit is forming.

Everything is 100% local: 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-hygiene coach sending your prompt to Anthropic under your own API key (BYOK) — that's you calling Anthropic directly, not us. License checks are an offline signature verification.

The eight 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 | A package manager installs named packages (npm/pip/cargo/…); a bare lockfile install never fires | ⚡ vibehabit: 2 packages were just installed (left-pad, foo) — vet before you build on it: real repo, healthy downloads, exact name (AI-suggested names get typosquatted). | | Secret safety | A well-known credential pattern (Anthropic/OpenAI/AWS/GitHub/Slack/Google/Stripe key, private-key PEM) 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. |

Each nudge fires once per streak — vibehabit reminds, it never nags. Seven of the eight coaches are fully local (no API needed); only the context-hygiene coach uses your Anthropic API key (BYOK), for a ~1-second Haiku evaluation per prompt. (A ninth, low-key reminder tells you when a newer vibehabit is on npm.)

Install

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. Requires Node 18+. For the context coach, add your API key via vibehabit config (or ANTHROPIC_API_KEY).

See it in ~10 seconds: run vibehabit demo — it replays every coach's nudge through the real coaching code, without touching your files or needing a key.

From source: npm install && npm run build && node dist/index.js install-hook. No native modules — the install is pure JavaScript and never needs a compiler.

Upgrading

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

(vibehabit update --check just tells you whether a newer version exists.)

Usually that is all. 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 with no further action. 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 all eight coaches' nudges look like (~10s), driven through the real coaches. No API key needed; touches none of your files. | | vibehabit doctor | Health-checks the install: hooks registered, API key present, ledger writable, build current. --api adds a live drift evaluation. | | vibehabit stats | Terminal dashboard: self-catch rate, commit + test hygiene, week-over-week trends. | | 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 | Interactive 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. Each prompt shows the recommended default. | | 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) — 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: all eight coaches 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. Licenses are available at vibehabit.io.

Troubleshooting

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.