sheriff.GitHub (8)

A deputy for your codebase

Big ideas.
Fewer blind spots.

Sheriff is an open-source testing orchestration layer that finds gaps, writes and runs tests,
and keeps them aligned with your changes—in Claude Code or Codex.

npx @dagim_codes/sheriff@latest

For Claude Code & Codex · JavaScript & TypeScript · MIT licensed

Read the field guide
TEST COVERAGE. ON THE FRONTIER.Meet your Sheriff OPEN SOURCE, ALWAYS.

A lot can hide between “it works” and “it’s tested.”

Sheriff finds the gaps, makes a plan,
and guides your AI tool through specialized testing roles.

  • React
  • Next.js
  • Vue
  • Svelte
  • Nuxt
  • Node.js
  • Vitest
  • Jest
  • Playwright
  • Cypress

FAMILIAR TERRITORY

Your stack.
Your test runner.

Keep the framework you know and the runner you trust. Sheriff follows your project’s testing setup.

HOW SHERIFF WORKS

From your first test
to every change after.

Run

COVER THE UNKNOWN

Turn blind spots into real tests.

Sheriff maps your untested code, plans the work by risk, and writes and runs tests with your project’s runner. Review the results and authorize any commits. Unresolved work stays visible.

/sheriff:run
$sheriff-run
For your first coverage passStart a run

Audit

LOOK A LITTLE CLOSER

Find the issue. Choose the fix.

Review source defects, apply authorized fixes, and update tests to check the corrected behavior. By default, Sheriff flags findings without changing source, with an audit report you can review.

/sheriff:audit
$sheriff-audit
Before the next releaseExplore audit

Sync

KEEP IT COVERED

Keep your tests on the same trail.

Sheriff selects current staged, unstaged, and untracked source changes, reviews them by default, and updates affected tests. It checks for missing assertions even when existing tests pass.

/sheriff:sync
$sheriff-sync
After your code changesStay in sync
+ 02 / THE SHERIFF’S CODE

Good coverage is no accident.

A few principles that keep Sheriff on the right trail.

BUILT TO STAY

New code. Tests that keep up.

Ship the feature. Refactor the old bit. Sheriff reviews your current source changes and adds missing assertions—even when existing tests pass. Your tests should move with you.

/sheriff:sync
$sheriff-sync

Know the gaps.

A file-by-file inventory of tests and known gaps. A plan ordered by risk. Coverage percentages come from your test runner’s coverage report.

01 / LOOK CLOSER

Find the issue. Choose the fix.

Audit mode reviews bugs and security issues. Authorize a fix, then check it with tests. Unresolved findings stay visible, and failing tests are never weakened to hide a bug.

02 / FAMILIAR GROUND

Your tools. Your conventions.

Keep your configured runner and mocking patterns. Sheriff reuses existing suites. Browser and service tests need a working environment before they can run.

A rider keeping watch from horseback
Steady hands.
Sharp eyes.

A whole posse.

Seven specialized roles. One coordinated workflow.

You set the scope.

Unit tests, E2E tests, or both. Your project, your call.

Pick up the trail.

Saved handoffs and resumable phases keep work moving.

THE WORK HAPPENS IN YOUR PROJECT. THE TRAIL STAYS THERE, TOO.Explore the commands
+ 03 / SADDLE UP

A small install.
A better habit.

From your terminal to your next commit.
Here’s where the trail starts.

  1. Invite Sheriff into town

    Run the installer, then choose Claude Code and your installation scope. Sheriff detects npm, pnpm, Yarn, or Bun and adds the project dependency automatically.

    npx @dagim_codes/sheriff@latest

  2. Point it at your project

    Open Claude Code in your project and start the workflow. Restart it if Sheriff isn’t visible yet.

    /sheriff:run

  3. Keep building. Keep it in sync.

    Review your current source changes and update the affected tests.

    /sheriff:sync
The full getting-started guide

Every sheriff needs a deputy.

Find Sheriff useful? Give it a star to support the project and help other developers discover it.

Star Sheriff on GitHub
+ A FEW THINGS TO KNOW

Before you
hit the trail.

More detail in the field guide .

What is Sheriff?

Sheriff is an open-source testing orchestration tool for Claude Code and Codex. It finds gaps in JavaScript and TypeScript tests, plans coverage work, writes and runs tests, and keeps them aligned with source changes.

How do I install Sheriff?

Run npx @dagim_codes/sheriff@latest from your project directory, then choose Claude Code, Codex, or both. Open your AI tool and run /sheriff:run in Claude Code or $sheriff run in Codex.

Is Sheriff a test runner?

No. Sheriff orchestrates the work around your test runner: discovering gaps, planning coverage, writing tests, running them, and reporting results. It uses the tools already in your project.

What do I need to get started?

Node.js 18 or newer, Claude Code or Codex, and a JavaScript or TypeScript project. If you don’t have a test runner, Sheriff can help configure one within your project’s permissions.

Will it change my source code?

Sheriff writes tests and flags source defects by default. Source fixes require your authorization and the appropriate onTestFailure policy, or explicit permission for that fix. Commits require your authorization too; Sheriff does not commit automatically.

Is it free to use?

Sheriff is open source under the MIT license. There’s no Sheriff subscription. It uses your existing Claude Code or Codex session, so model usage follows your chosen tool’s plan and billing.

A NOTE FROM THE BUILDER

Hi, I’m Dagim.

I’m a frontend developer based in Addis Ababa. I build tools that make everyday work a little easier.

Dwight Prompt Assistant helps you write better prompts. TriggerNote brings your notes into view on the websites where you need them. And Sheriff helps keep your code covered as it grows.

Different tools, same idea: less busywork, more room for the work you care about.

More about me
Dagim working at his desk

Dagim Shimelis

Independent developer & maker
DwightPrompt AssistantTriggerNoteNotes in contextsheriff.Tests that keep up
A few things I’ve put into the world.