Installation

Run installation commands in your terminal from the project directory. Run Sheriff skills or commands in your AI tool's chat prompt.

These instructions cover Sheriff 0.2.0. The commands install the latest published version; use @dagim_codes/sheriff@0.2.0 instead of @dagim_codes/sheriff@latest to pin this release. For an existing installation, see Update and uninstall.

Install in one commandCopy Anchor Link

npx @dagim_codes/sheriff@latest

Use ↑/↓ and Enter to choose Claude Code, Codex, or both, then this project (local) or all your projects (global). Press Ctrl+C to cancel. The terminal wizard shows one question at a time, with a gold selection highlight and responsive Western artwork.

Choosing local scope automatically installs Sheriff as a development dependency and registers the selected integrations. No separate dependency-install command is needed.

Project installationCopy Anchor Link

Run the wizard and choose your AI tool, then This project (local):

npx @dagim_codes/sheriff@latest

Select Claude Code, Codex, or both in the wizard. Sheriff uses the project's packageManager field first, then detects npm, pnpm, Yarn, or Bun from lockfiles and installed-layout markers. It can discover the manager in parent directories for workspace projects. A project with no detected manager defaults to npm; conflicting manager markers require an explicit packageManager.

New declarations go in devDependencies. Existing declarations and installed versions are preserved; missing declared packages are restored with the selected manager. Running the installer alone does not upgrade an existing dependency—see Update and uninstall.

The selected package manager must be installed and available in your terminal. Sheriff validates the installed runtime before writing integration files. Package-manager failures stop setup without writing adapters or silently switching to npm.

Yarn Plug’n’Play is not supported for local installs because Sheriff needs a node_modules runtime. Use a node_modules linker or a global installation. Sheriff does not change your Yarn configuration automatically.

Terminal requirementsCopy Anchor Link

Use Node.js 18 or newer and an interactive terminal with ANSI cursor movement and alternate-screen support for the wizard. Unicode font support displays the artwork; small windows use a compact layout, and NO_COLOR disables colors. No special terminal app is required. Interactive behavior has been checked on macOS; Linux and Windows remain unverified.

For CI, redirected input, or other non-interactive use, explicit --tool claude|codex|both and --local or --global flags are required. Add --silent to suppress progress output. Passing only --local or --global without --tool retains the legacy Claude Code default. The installer configures integrations; it does not start a test workflow. Runner choices such as Vitest or Playwright still happen in your AI tool's chat.

Start in Claude CodeCopy Anchor Link

Open Claude Code in the project, restarting it if needed:

/sheriff:run

Claude Code gets small command, role, and hook adapters, settings, and an ownership inventory. The runtime and full instructions stay in the dependency.

Start in CodexCopy Anchor Link

Restart Codex in the project, then type this in its chat prompt:

$sheriff-run

The six direct skills are $sheriff-run, $sheriff-audit, $sheriff-sync, $sheriff-status, $sheriff-configure, and $sheriff-help. They share the same runtime. Existing syntax such as $sheriff run still works.

Submit $sheriff alone to see Run, Audit, Sync, and Status, then reply with a number or action name. This is a conversational menu after submission, not nested terminal autocomplete. Codex does not receive Claude hooks or a statusline.

What to commitCopy Anchor Link

Commit package.json, your lockfile, and the generated integration files:

• Codex: .agents/skills/sheriff/SKILL.md and the six sibling sheriff-* action skill files.
• Claude Code: command and role adapters, hook adapters, .claude/settings.json, and .claude/sheriff/.install-manifest.json.

Keep node_modules/ ignored. Full instructions, workflows, templates, and runtime code live under node_modules/@dagim_codes/sheriff/dist/claude/ and dist/codex/. Teammates restore them through the project's normal dependency install, including development dependencies. Rerun Claude registration after cloning or moving the project to refresh its statusline path.

Project .sheriff/ state and generated tests are separate from the installed runtime.

Personal installation across projectsCopy Anchor Link

Choose All your projects (global) in the wizard to copy the runtime into your home directory without a project dependency:

npx @dagim_codes/sheriff@latest

Claude uses ~/.claude/; Codex uses ~/.agents/skills/sheriff/ with sibling action skills.

Test an unpublished packageCopy Anchor Link

In the Sheriff source checkout, run npm pack --pack-destination /tmp. The prepack step builds hooks and runtime bundles. In a separate test project, install the resulting tarball using your project's package manager:

pnpm add -D /tmp/dagim_codes-sheriff-VERSION.tgz
pnpm exec sheriff

Replace VERSION with the filename printed by npm pack. For npm projects, use npm install --save-dev /tmp/dagim_codes-sheriff-VERSION.tgz, then npx sheriff. Repack and reinstall after source changes. A temporary tarball reference is for local testing; replace it with a published dependency before sharing the project.

If registration reports a missing declaration, check that the dependency-install command completed successfully and saved Sheriff in package.json. A runnable binary in node_modules alone is not enough. Resolve any package-manager or project lifecycle-script failure before retrying.

Continue to Basic Usage to run your first tests.