debt-ops — Claude Code plugin: what it does, how to install
The debt-ops plugin for Claude Code and Codex records deferred agent decisions in a repo registry; its review skill ranks debt by file churn.
MIT ★ 1,596 updated 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install debt-ops@awesome-codex-pluginsWhat debt-ops does
Four hooks carry the load. SessionStart injects the disciplines and caches your quality commands along with the ADR and registry directories. After each apply_patch, Edit or Write, PostToolUse runs those commands against the changed files under a 3s per-command budget. Stop sniffs for TODOs and nudges you when a deferral never reached the registry.
Entries stay in the repo. $add files one and hands it a batch letter; $review audits the registry and orders the debt by how often each file changes; $metrics prints a read-only summary from the log. $init is explicit-only and writes the ## Tech debt operations charter into AGENTS.md, which is where the hooks pick up quality commands. That is AGENTS.md rather than CLAUDE.md, so a project charter in the older file goes unread.
A git repository and Python 3.10+ are required, standard library only. The cache sits at ~/.cache/debt-ops/cache/<repo-hash>/ and DEBT_OPS_CACHE moves it. In Codex you can type drop A, drop A,C or drop all straight into a prompt, and DEBT_OPS_DEBUG=1 logs every hook fire to a file in the cache.
What it helps with
- catch a deferred fix as the agent writes it
- keep every shortcut in one registry inside the repo
- rank what to pay down first by file churn
- stop TODOs from piling up unregistered
- pull a health summary before a refactor
Example prompts for the agent
- Register this one: the stub in
billing/tax.py, revisit after the release.$add - What should I pay down first?
$review drop A,C— both are done
How to install debt-ops
Plugin marketplace
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install debt-ops@awesome-codex-pluginsStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about debt-ops
How do I install debt-ops in Claude Code?
Run /plugin marketplace add hashgraph-online/awesome-codex-plugins, then /plugin install debt-ops@awesome-codex-plugins.
What does debt-ops do?
It records the technical debt your coding agent creates, in a registry kept in the repository. Later $review ranks those entries by file churn so you know where paydown pays off.
How is the Codex version different?
The charter lands in AGENTS.md instead of CLAUDE.md, and hooks read quality commands from that section. Edits arrive as apply_patch, and the skills are called as $add, $review, $init and $metrics.
Source text
agentic-tech-debt · MIT
# debt-ops — Codex adapter
The [debt-ops](../README.md) disciplines, packaged as a [Codex](https://developers.openai.com/codex) plugin. Behavior matches the [Claude Code adapter](../claude-code); this README covers only what's Codex-specific.
## Install
Register the marketplace from your shell, then install from the plugin browser:
```bash
codex plugin marketplace add bcanfield/agentic-tech-debt
```
Open `/plugins` inside Codex and install **debt-ops**. Working *inside* this repo, Codex auto-discovers the bundled marketplace at `.agents/plugins/marketplace.json` once the project is trusted — no add step needed. Requires a git repo and Python 3.10+ (stdlib only).
## What's wired
Layout follows Codex's plugin conventions: hooks bundle their scripts under `hooks/` (referenced via `${PLUGIN_ROOT}/hooks/…`), and each skill bundles its helper under its own `scripts/` (referenced by a relative path, the documented skill convention).
| Codex primitive | File | Role |
| --- | --- | --- |
| `SessionStart` hook | `hooks/session-start.py` | Injects the disciplines + detects/caches quality commands and ADR/registry dirs |
| `PostToolUse` hook (`apply_patch\|Edit\|Write`) | `hooks/feedback.py` | Runs quality commands on edited files under a 3s/command budget |
| `Stop` hook | `hooks/stop.py` | TODO-sniff safety net — nudges when deferrals went unregistered |
| `UserPromptSubmit` hook | `hooks/drop.py` | Handles `drop A` / `drop A,C` / `drop all` shorthand |
| `$add` skill | `skills/add/` (+ `scripts/register.py`) | Registers a debt entry, assigns a batch letter |
| `$review` skill | `skills/review/` (+ `scripts/review.py`) | Audits + ranks the registry; walks paydown |
| `$init` skill *(explicit-only)* | `skills/init/` | Writes the `## Tech debt operations` charter into `AGENTS.md` |
| `$metrics` skill | `skills/metrics/` | Read-only health summary from the metrics log |
## Codex-specific notes
- **Charter file is `AGENTS.md`**, not `CLAUDE.md` — `$init` writes the managed `## Tech debt operations` section there, and the hooks read quality commands from it.
- **Edits are `apply_patch`.** The feedback hook parses the V4A patch envelope (`*** Add/Update File:`, `*** Move to:`) to learn which files changed, since there's no `tool_input.file_path`.
- **Cache** lives at `~/.cache/debt-ops/cache/<repo-hash>/` (override with `DEBT_OPS_CACHE`) so the hooks and skill Bash always agree on one path ([ADR 0012](../docs/adr/0012-codex-deterministic-cache-base.md)).
- **Skill invocation** is `$add` / `$review` / `$init` / `$metrics` (or the `/skills` picker). `$init` is explicit-only (`skills/init/agents/openai.yaml`).
- **Debug:** set `DEBT_OPS_DEBUG=1` to log every hook fire to `<cache>/debug.log`.
## Research
Disciplines map to the [nine tool-agnostic pillars](../docs/tech-debt-pillars.md); the [Claude Code mapping](../docs/tech-debt-plugin-plan.md) explains why each hook exists. Same evidence base, different agent.
© Brandin Canfield · MIT · hashgraph-online/awesome-codex-plugins