Skip to main content
plugin CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install debt-ops@awesome-codex-plugins
Open on GitHub

What 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-plugins

Step 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

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

From the same set391

The whole set →
design-helper The design-helper plugin puts CSS, layout, and motion options side by side in a browser, then applies your choice to the project. Use it before committing to a UI change. CX Codex ★ 1,596repo stars delx-recovery delx-recovery — a plugin that reopens an agent's earlier sessions, records where the work stands and turns failures into a recovery plan. Session memory sits on a hosted MCP server. CX Codex ★ 1,596repo stars dejavu-gates dejavu-gates catches repeating tool failures across sessions and turns them into automatic reminders followed by hard execution blocks. CX Codex ★ 1,596repo stars deepseek-minimal-anchor The deepseek-minimal-anchor plugin tunes DeepSeek sessions in Codex: Pro keeps a one-line anchor, while Flash follows a task-aware decide-and-verify contract. CX Codex ★ 1,596repo stars core-learning core-learning structures study sessions around Socratic questioning, Feynman teach-back, and spaced recall to deliver working projects. CX Codex ★ 1,596repo stars context-guard context-guard is a Claude Code and Codex plugin that preserves requirements and verification evidence in long Codex tasks. It restores open items after context compaction and checks evidence before marking work complete. CX Codex ★ 1,596repo stars codex-attachment-manager codex-attachment-manager is a Claude Code plugin that manages image history in Codex tasks. It selects attachments for the next message and searches them by description. CX Codex ★ 1,596repo stars codex-claude-council codex-claude-council asks Claude and ChatGPT the same question, then lets them debate across multiple rounds until both reach agreement. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open