Offcut

Catches the code your agent should not have written.

A deterministic check for over-engineering in a diff. No model call, no network, no dependencies.

Try it on your last change

git diff | npx --yes github:skelvar/offcut scan --diff -

The same command from npm: git diff | npx --yes @skelvar/offcut scan --diff -. Pin a version with npx --yes @skelvar/[email protected] scan --diff - or npx --yes github:skelvar/offcut#v0.4.2 scan --diff -; marketplace installs accept the same tag as --ref v0.4.2.

src/phone.js (1)
  [new-dependency] Offcut: new dependency — what does this replace that four lines could not do?

Six checks, each phrased as a question: a new dependency, one implementation behind an interface, a parameter with a default that is never read, a configuration surface nobody asked for, an exported symbol nothing references, a large first write. They apply to JavaScript and TypeScript. They never block anything. exported-unused runs in repository audits only; relative to the paths scanned.

On pull requests

# .github/workflows/offcut.yml
on: pull_request
permissions:
  contents: read
jobs:
  offcut:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: skelvar/offcut@main

Findings appear as file annotations on the pull request and in the job summary. The step always exits 0; findings are questions for the reviewer, not a gate.

Evidence

• False positives: 0 of 95 clean files across all six checks (bench/fp.mjs; the 95-run negative corpus lives in skelvar/offcut-evidence, cloned as a sibling directory).
• Recall on 27 real agent-authored pull requests: 4 of 10 labeled over-builds caught, 0 of 17 clean diffs flagged (bench/recall/RESULTS.md). Labels were written by one rater before scanning; treat this as an estimate, and read the list of misses before relying on it.

No token, cost, or lines-of-code reduction is claimed. A protocol we tested for post-implementation self-review lost to one ordinary host review and was removed (docs/development/CLOSE-RESULTS.md).

Also: construction rules for your agent

npx --yes github:skelvar/offcut

Installs a short rule set into Codex, Claude Code, Cursor, and Grok Build (only the ones already on your machine). Before writing, the agent asks what breaks if this is skipped, whether the codebase or platform already does it, what the smallest correct change is, and which boundary should own it. If you already use Ponytail for that, keep it; the scan works on any diff regardless of who wrote it.

| Command | Effect | |---|---| | /offcut full | Apply the construction rules every turn | | /offcut lite | Remind the agent every third turn | | /offcut strict | Challenge new dependencies before writing | | /offcut off | Disable Offcut for this session | | /offcut default <mode> | Choose the mode for future sessions | | /offcut-review | Scan the current diff from inside the agent | | /offcut-audit | Scan a repository and rank findings | | /offcut-help | Show commands and the active mode |

Concise responses are the default while Offcut is active. Change only the response style with /offcut concise on or /offcut concise off; the construction rules stay active either way.

Marketplace installs:

| Agent | Commands | |---|---| | Codex | codex plugin marketplace add skelvar/offcut --ref maincodex plugin add offcut@skelvar | | Claude Code | /plugin marketplace add skelvar/offcut/plugin install offcut@skelvar | | Cursor | Public listing pending review (cursor.com/marketplace/publish); use the universal installer today. | | Grok Build | Use the universal installer. |

Uninstall with npx --yes github:skelvar/offcut -- --uninstall. Existing instruction and hook files are preserved; the first change to each gets a *.offcut-backup. Offcut never denies a tool call, never changes model or provider settings, and never sends source code anywhere. Cursor subagent inheritance uses an input-only rewrite and casts no permission vote.

Support

The full automated suite runs on Windows, Ubuntu Linux, and macOS. Real-harness E2E is Windows only today; see the dated host matrix.

Development

node --test tests/*.test.js
node bench/fp.mjs
node bench/recall.mjs
node scripts/build-agents-md.js   # AGENTS.md is generated from rules/offcut.md

Harness notes and benchmark receipts: docs/development.

Release

1. Bump every version field (package.json, plugin.json, the three plugin manifests, the two marketplace.json files, scripts/build-agents-md.js, skills/offcut-{review,audit,help}/SKILL.md), then run:

   node scripts/build-agents-md.js
   node scripts/build-plugin-package.mjs

2. Merge the bump to main through a pull request (CI checks version parity and the generated files).

3. gh release create vX.Y.Z --target main --title "Offcut vX.Y.Z" --notes-file notes.md --latest

   The Releases page is not updated by the version fields; this step is what updates it.

4. Publishing the release triggers .github/workflows/publish.yml, which publishes @skelvar/offcut to npmjs with provenance. Authentication is npm's trusted publisher for this repository and workflow file (configured once with npm trust github @skelvar/offcut --repo skelvar/offcut --file publish.yml --allow-publish); no token is stored. If the version is already on the registry, the workflow exits without publishing.

License

MIT — see LICENSE.