vibetidy

vibetidy

Two checks that make an AI-generated repo look maintained.
Generates a README from what your code actually contains, and warns when a feature-sized commit has no issue behind it.

You shipped something from v0, Bolt, Lovable, or a long Claude session. It works. The README still says Getting Started with Create React App, there is no record of why anything was built, and the changelog does not exist. vibetidy fixes those two things and stops.

npx vibetidy readme                      # generate README.md, review the diff, confirm
npx vibetidy issue-check --install-hook  # nag on feature commits with no issue

What it does

• readme — scans the repository (manifest, scripts, dependencies, .env.example, entry points, folder tree, existing README), sends only those verified facts to an LLM, and writes a README in a fixed structure: What it does / Requirements / Setup / Run / Reference / Tech stack / Repository layout / Notes. Shows a diff and waits for confirmation before touching the file.
• issue-check — classifies your staged changes. New source files or a substantial diff means "feature"; lockfiles, build output, docs and tests are excluded. If it is a feature and no issue number appears in the branch name or the commits, it says so. Offers to create the issue with gh and writes a changelog/unreleased/ fragment.
• Zero runtime dependencies. npx vibetidy downloads one package, not three hundred.
• Any OpenAI-compatible endpoint. OpenAI, OpenRouter, Anthropic, Groq, DeepSeek, Together, or a local Ollama / LM Studio.

The grounding rule

The scanner is the product; the model is a formatter. Everything the README is allowed to claim comes from the scan, and the prompt says so explicitly: never invent a feature, a flag, an environment variable, a dependency, or a version. When the facts are thin, you get a short accurate README instead of a long plausible one.

You can see exactly what would be sent, with no API key:

npx vibetidy readme --print-context

Requirements

• Node.js 20.10 or newer.
• An API key for one LLM provider — only for readme, and only when actually generating. --print-context needs nothing.
• git, for issue-check.
• The GitHub CLI (gh), optional — only for the offer-to-create-an-issue path. Everything else works without it.

Setup

No install step: npx vibetidy <command> runs the latest version. To install it permanently:

npm install -g vibetidy

Point it at a provider with one environment variable:

export OPENAI_API_KEY=sk-...          # default provider
# or
export OPENROUTER_API_KEY=sk-or-...   # then: --provider openrouter

Each provider also reads its own key variable (ANTHROPIC_API_KEY, GROQ_API_KEY, DEEPSEEK_API_KEY, TOGETHER_API_KEY). Local providers need no key at all:

npx vibetidy readme --provider ollama --model llama3.1

Run

npx vibetidy readme                        # current directory
npx vibetidy readme ./packages/api         # somewhere else
npx vibetidy issue-check                   # check what is staged
npx vibetidy --help

Commands

vibetidy readme [path]

Scans a repository and writes a README grounded in what it finds. Nothing is written until you confirm.

npx vibetidy readme --print-context     # inspect the facts and prompt, no key needed
npx vibetidy readme --dry-run           # generate and diff, never write
npx vibetidy readme --yes               # write without the prompt (for CI)

When a README already exists, accurate prose is preserved and stale claims are rewritten. A README that is still the untouched scaffolding default is detected and replaced outright.

Without a TTY (CI, a pipe) the confirmation cannot be answered, so nothing is written and the command exits 1 — pass --yes for non-interactive runs.

vibetidy issue-check [path]

Checks the staged changes — or, with nothing staged, the branch against its base — and looks for an issue number.

npx vibetidy issue-check                     # warn (exit 0)
npx vibetidy issue-check --strict            # block (exit 1)
npx vibetidy issue-check --against main      # check a whole branch, e.g. in CI
npx vibetidy issue-check --install-hook      # install the pre-commit hook

What counts as a feature. A new source file, or more than --threshold inserted lines. Lockfiles, dist/, build/, node_modules/, generated directories, minified files, docs and tests are all excluded from the count — a 4000-line lockfile churn is not a feature.

Where it looks for the issue. The branch name (feat/42-add-oauth, 42-add-oauth, issue-42, gh-42) first, then the commit messages on the branch (#42, Closes #42, GH-42). A version number in a branch name (feat/add-oauth2-login) is not mistaken for an issue.

It warns; it does not block. A hook that blocks on day one gets --no-verify'd on day two. Add --strict to the installed hook when the habit has stuck.

The pre-commit hook

npx vibetidy issue-check --install-hook

Writes .git/hooks/pre-commit, honouring core.hooksPath. If a hook already exists, vibetidy asks before appending its block and never overwrites what is there. The block is delimited by markers, so --uninstall-hook removes exactly it and leaves the rest.

If vibetidy is not installed when the hook runs, the block does nothing. A missing tool is never the reason a commit fails.

Bypass one commit with SKIP_ISSUE_CHECK=1 git commit ..., or all hooks with git commit --no-verify.

Creating the issue

When gh is installed and authenticated, issue-check offers to file the issue for you. It searches open and closed issues first so you do not file a duplicate, creates the feature / bug / chore labels if missing, and writes the body in a fixed shape:

## Need
Why this is needed.

## Proposal
The shape of the solution.

## Done when
- [ ] Acceptance criteria

It then writes changelog/unreleased/<branch-slug>.md and stages it:

### Added
- Add loyalty banner to checkout (#42)

One fragment file per branch, never a direct edit to CHANGELOG.md. Two pull requests appending a line to the same file on the same day collide on merge; two files named after different branches cannot. Fold the fragments into CHANGELOG.md whenever you cut a release.

Tech stack

Repository layout

.
├── bin/
│   └── vibetidy.js        # executable entry point
├── src/
│   ├── cli.js             # argument parsing and command dispatch
│   ├── index.js           # programmatic API
│   ├── commands/
│   │   ├── readme.js      # scan -> generate -> diff -> write
│   │   └── issue-check.js # classify -> find refs -> warn/create
│   └── lib/
│       ├── scan.js        # repository facts (the grounding layer)
│       ├── issues.js      # feature heuristic and issue-ref parsing
│       ├── template.js    # README structure and the prompt
│       ├── llm.js         # OpenAI-compatible client
│       ├── gh.js          # optional GitHub CLI integration
│       ├── hook.js        # pre-commit hook install/uninstall
│       ├── diff.js        # diff preview
│       └── git.js         # git wrappers
└── test/                  # node:test suite, no network

Notes

• Nothing is written without your say-so. readme shows a diff and waits; issue-check only writes when it creates an issue for you, and then only a changelog fragment.
• Read the generated README before committing it. It is grounded in a real scan, but you know things about the project that the code does not say — --hint is there for exactly that.
• readme sends repository metadata to your chosen provider: manifest contents, dependency names, script names, environment variable names (never values — it reads .env.example, never .env), the folder tree, and the existing README. It never sends your source code. Use --print-context to see the payload, or --provider ollama to keep it on your machine.
• The scanner and the classifier are importable if you want to build something else on them:

  import { scan, classifyChange, findIssueRefs } from 'vibetidy';
  

• The test suite never touches the network. The one function that would is injected and stubbed.

Contributing

See CONTRIBUTING.md. Issues and pull requests are welcome.

License

MIT — see LICENSE.