Habit Hooks CLI
Habit Hooks runs linters after an agent's edits and turns each violation into a short guide for fixing the code
- 250 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Runs external linters and analyzers over project files and reads source code
- Writes .habit-hooks/config.toml and snooze.json into the repository
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/habit-hooksDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Runs external linters and analyzers over project files and reads source code
- Writes .habit-hooks/config.toml and snooze.json into the repository
This is third-party code. Review the repository files before installing.
What it does
Habit Hooks installs as a Python package and runs from the project root with the habit-hooks command. It is two programs joined by a pipe. habit-sensors runs the project's detectors (ruff, eslint, knip, jscpd, phpmd, PMD, rubocop) and collects findings. habit-mapper groups them by kind of problem and prints a short guide in place of the raw linter rule: what to look for, how to fix it and what to avoid. The agent reads that output and edits the code. The swap matters. In an independent test by Liina Suoniemi on 18 Python functions, Sonnet 4.6 given only the bare metric "function is too complex (11 > 5)" produced a genuine fix in 5.6% of trials and gamed the check in 79 of 90 by splitting branches into helpers, so the number fell while the code stayed as complex. With a coaching guide the genuine share rose to 83.3%. The first run checks the whole project, so on an existing codebase you start with habit-sensors --all | habit-snooze --snooze: current findings are marked accepted and only new ones show from then on. The scope flags --branch, --last, --since and --file narrow a run. Exit code 0 means clean, 1 an enforced finding, 2 a failure of the tool itself.
Who it is for. Teams writing code with Claude Code, Codex or Cursor who are tired of agents working around the linter instead of fixing the code.
Good fit when
- The agent shrinks a function to dodge the complexity limit by splitting it into pieces, and the code is no easier to read
- The project is in Python, TypeScript, PHP, Java or Ruby, linters are already set up, but the agent misreads their messages
- On a legacy codebase you want to catch only new problems and park the backlog with habit-snooze
- CI needs distinct exit codes: 1 for a finding, 2 for a broken tool
- You want your own guidance: a guides/<smell>.md file in .habit-hooks replaces the default hint
Not a fit when
- You need correctness or architecture review: the tool catches structural smells and does not see logic bugs
- The project language is outside the plugin list (Python, TypeScript, PHP, Java, Ruby): only the generic plugin with file length and duplication remains
- You cannot install detectors such as ruff, eslint or jscpd: Habit Hooks does not bundle them
- You cannot get Python 3.11 or newer
Example request
Set up Habit Hooks in this TypeScript project, snooze the existing findings and run habit-hooks after each editLimitations
- Python 3.11 or newer is required. The install brings the core and the generic plugin, and a language plugin is added separately, for example the habit-hooks[typescript] extra.
- A plugin works only once it is listed in .habit-hooks/config.toml. An installed but not enabled plugin checks nothing, and an empty report often means exactly that.
- Detectors (jscpd, ruff, eslint, knip) are installed in the project by you. A second uv tool install with another extra replaces the earlier set, so name all languages in one command.
- The tool catches structural smells and does not check correctness or design.
How to disable. Remove the plugins from the plugins list in .habit-hooks/config.toml or delete the .habit-hooks folder. The package itself is removed with uv tool uninstall habit-hooks (or pip uninstall habit-hooks).
FAQ
How is Habit Hooks different from a regular linter?
A linter prints a rule and a line number, and Habit Hooks replaces them with a fix guide. The checks themselves still come from ruff, eslint, knip and other detectors that the tool runs and translates into hints an agent can use.
How do I enable Habit Hooks in a TypeScript project?
Install the package with an extra: uv tool install "habit-hooks[typescript]", then run habit-hooks init in the project root. It writes .habit-hooks/config.toml with the right plugins and lists the missing detectors, such as eslint, knip and ts-morph.
What if habit-hooks reports nothing?
Most often the plugin is installed but not enabled in .habit-hooks/config.toml. Running habit-hooks init again changes nothing in a configured project and shows what is missing.
Which languages does Habit Hooks support?
There are separate plugins for Python, TypeScript, PHP, Java and Ruby, and the generic plugin counts file length and duplication in any project. A language plugin has to be installed and enabled in the config.
How do I avoid fixing every old violation at once?
Run habit-sensors --all | habit-snooze --snooze and commit .habit-hooks/snooze.json. Existing findings are parked and new ones appear in the report.
Discussion
No questions or reviews yet.
Related
CLI toolsAn adversarial code-audit skill: Hunter finds bugs, Skeptic challenges them, Referee rules, and no source edit happens without your permission
A static linter for agent instructions: finds ambiguous tool descriptions and schema gaps before a run, with no model or network
Hooks for Claude Code and Codex CLI keep a ledger of agent actions and refuse a "done" claim until a check has passed.
Validates Agent Skills packages: structure, links, token weight and instruction quality, with optional LLM-as-judge scoring
Corrections you give your agent turn into rule files in the repository and run with taskless check locally and in CI.
Reviews the git diff and the conversation with the agent: catches bugs and gaps between your request and the agent's result. CLI, skill, GitHub Action
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Habit Hooks (this card) | no | 250 | |
| brooks-lint | no | 1,564 | a ruleset for code review drawn from books, no detectors run and no linter output rewritten |
| TDD Guard | no | 2,373 | stops the agent until a test exists and does not analyze structural smells |
README in short
The page opens with the motivation: agents ignore long rule documents and a bare metric invites gaming. Next come the external test results, a four-step install (package, language plugin, enabling in config, detectors), scope modes and exit codes. It then covers the two-program design, the smell catalogue split into enforced and suggested, plugins, tuning through .habit-hooks and snoozed violations.