debt-ops — Claude Code hook: what it does and how to install
The debt-ops hook records deferred tech-debt items in a repository registry, while a review skill ranks them by file churn. Use it to keep postponed cleanup visible during coding.
MIT ★ 1,596 updated 2026-10-29
.claude/settings.jsonWhat debt-ops does
debt-ops logs each deferred tech-debt item in a registry inside the repository. Its review skill ranks items according to how often the affected files change, helping teams decide what to address first.
Hooks run at session start and end, when a user submits a prompt, and after apply_patch, Edit, or Write. They invoke session-start.py, drop.py, feedback.py, and stop.py with python3. Python 3 is required for these commands to run.
For Claude Code, place the hook settings in .claude/settings.json. Codex is also listed as a supported platform, but the installation instruction provided is for Claude Code.
What it helps with
- record a deferred tech-debt item in the repository registry
- rank pending debt items by how often their files change
- track deferred work after
EditandWriteoperations - run feedback handling after
apply_patch
Example prompts for the agent
- Record this deferred tech-debt item in the repository registry.
- Review the registry and rank items by file churn.
- After the
Editchanges, check for newly logged tech-debt items.
How to install debt-ops
Manually: put the files in place
.claude/settings.jsonThe hooks block: event (PreToolUse, PostToolUse, Stop…) → command. Personal ones go to ~/.claude/settings.json
Step by step, with commands for each platform: Claude Code hooks: what they are, where to configure them, how to block a risky command
Questions about debt-ops
How do I install debt-ops in Claude Code?
Add the hook settings to .claude/settings.json.
What does debt-ops do?
Its hooks log deferred tech-debt items in a repository registry. A review skill ranks them by how often the affected files change.
What does debt-ops run?
Python 3 scripts run at session start and end, on prompt submission, and after apply_patch, Edit, or Write.
Source text
hooks.json · MIT
Hooks bundle shipped with the debt-ops plugin for Claude Code.
Catches AI-introduced tech debt at write-time: hooks log every deferral to a registry in your repo and a review skill ranks paydown by file churn.
Triggers on: PostToolUse, UserPromptSubmit, SessionStart, Stop.
```json
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "python3 ${PLUGIN_ROOT}/hooks/session-start.py"
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "python3 ${PLUGIN_ROOT}/hooks/drop.py",
"timeout": 3
}
]
}
],
"PostToolUse": [
{
"matcher": "apply_patch|Edit|Write",
"hooks": [
{
"type": "command",
"command": "python3 ${PLUGIN_ROOT}/hooks/feedback.py",
"timeout": 5
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "python3 ${PLUGIN_ROOT}/hooks/stop.py",
"timeout": 5
}
]
}
]
}
}
```
© Brandin Canfield · MIT · hashgraph-online/awesome-codex-plugins