Habit

A Claude Code plugin that observes how you work and distills reusable prompts from your sessions. Habits are Markdown files with YAML frontmatter: stored locally, version-controllable, executed with semantic overrides. Relevant habits are automatically surfaced when you ask for suggestions.

Install  ·  Usage  ·  Commands  ·  How It Works  ·  Report a Bug

Install

Requires jq, and either Claude Code or Cursor 2.5+.

Claude Code:

/plugin marketplace add https://github.com/Prog-Jacob/habit.git
/plugin install habit@habit

Cursor (2.5+): install via Cursor's plugin marketplace, using the manifest in .cursor-plugin/. Hook commands in hooks.cursor.json are plugin-root-relative, so a marketplace install wires capture with no path edits. Use the manual install below as a fallback where marketplace install isn't available yet.

Manual (fallback, any version of either tool):

git clone https://github.com/Prog-Jacob/habit.git
cd habit && ./install.sh

For Cursor, merge hooks/hooks.cursor.json into ~/.cursor/hooks.json.

---

Usage

Habit observes every session through hooks. Use Claude Code normally. After enough prompts, skills suggest running /habit:distill to extract reusable patterns.

The /habit:* forms below are Claude Code syntax. On Cursor the same skills are invoked by name or in plain language (for example, ask to run fix-types in the auth module, or say "distill this session").

Create a habit from a description:

/habit:edit fix-types Fix all TypeScript errors, file by file, using tsc --noEmit

Run it with a scoped override:

/habit:run fix-types only in the auth module

Overrides are woven into the instruction semantically ("Fix all TypeScript errors in the auth module"), not appended to the end. If you use the same override 3+ times, distill detects the pattern and either creates a variant (fix-types-auth) or updates the base habit.

Apply relevant habits to a request:

/habit:suggest refactor the auth module

Matches habits by tags and descriptions, merges their instructions, and addresses the request directly.

Browse the inventory:

/habit

Pick by number or name. Add context to narrow a run (e.g., 1 only in auth).

---

Commands

Command	What it does
/habit [query]	Browse and search the inventory. Fuzzy-matches against id, tags, and description.
/habit:run <id> [override]	Execute a habit. Override modifies the instruction for this run and is logged.
/habit:edit <id> [description]	Create or update a habit. Without a description, shows current content.
/habit:suggest <request>	Surface relevant habits for a request, merge their instructions, and address it directly.
/habit:distill	Sweep the current session and any pending prior sessions. Classifies, deduplicates, writes or merges habits.
/habit:distill maintain	Regular sweep plus full inventory restructure: merge convergent habits, normalize tags, archive stale entries.
/habit:distill project	Scan new or modified project sessions and restructure the full inventory.
/habit:watch	Check observation status and prompt count for the current session.
/habit:watch off	Pause observation. Resumes automatically next session.

---

How It Works

Hooks fire on every session. SessionStart registers the session. UserPromptSubmit increments a prompt counter (skips prompts under 5 words) and records the transcript path. SessionEnd saves a breadcrumb for later distill if any prompts were captured.

Distill runs in a forked subagent. It preloads the current transcript, the merged habit index, pending sessions, execution log, and metadata. It classifies each prompt as reusable or one-off, deduplicates against existing habits, and writes new or merged entries. Every sweep also runs self-improvement (below). maintain adds a full restructure pass: merging convergent habits, normalizing tags, and archiving stale entries. project scans new or modified .jsonl session files for the current working directory.

Self-improvement. When a skill hits friction (a misroute, or a missing tool or path), it records an observation. Distill turns each actionable observation into a learning: a short standing note aimed at the skill it concerns, stored in settings.local.json next to your habits. Each skill reads its learnings on the next run and applies them as extra guidance. Because the overlay lives in your data directory rather than the plugin files, it survives updates and behaves identically on Claude Code and Cursor.

Scope. Habits live in ~/.claude/habits/ (global) or .claude/habits/ (project). Project habits shadow global ones with the same id.

Storage. Each habit is a .md file. Session state and indexes live in settings.local.json per scope.

---
id: fix-types
tags: [typescript, linting]
description: Fix TypeScript type errors in the specified scope.
scope: global
created: 2026-04-09T14:30:00Z
updated: 2026-04-09T14:30:00Z
archived: false
last_executed: 2026-04-11T18:14:28Z
---

## Instruction

Run `tsc --noEmit` and fix every reported error, file by file.
Prefer narrowing types over adding `as` casts.

---

Uninstall

/plugin uninstall habit@habit

Habit data in ~/.claude/habits/ is preserved. To delete it:

rm -rf ~/.claude/habits/

---

_{MIT License © 2026 Ahmed Abdelaziz}