CLI reference

Bug Hunter has separate interfaces:

• bug-hunter in a terminal installs/verifies the skill;
• /bug-hunter ... represents public arguments interpreted by the installed skill inside a coding agent;
• scripts/run-bug-hunter.cjs is an internal/integration runner with additional measurable-protocol controls.

There is no bug-hunter scan shell command.

Installer commands

bug-hunter install [--agent <name>] [--path <dir>] [--skip-doctor]
bug-hunter doctor [--agent <name>] [--path <dir>]
bug-hunter info
bug-hunter --version
bug-hunter --help

install

Copies the managed runtime into an agent skill directory using an atomic staged swap. Normal upgrades preserve files not owned by the previous manifest.

Option	Meaning
--agent <name>	Use a known agent target
--path <dir>	Use an exact custom target and override --agent
--skip-doctor	Skip the post-install environment/target check

Without --agent or --path, the CLI searches known agent directories and falls back to ~/.agents/skills/bug-hunter. Explicit selection is preferred.

doctor

Without a target, checks core environment dependencies such as Node.js, Git, Context Hub, and the bundled Context7 fallback. With --agent or --path, it also validates the installed managed runtime against the CLI package performing the check.

info

Prints skill metadata and installation guidance.

Public skill arguments

These are interpreted by the installed SKILL.md:

Argument	Behavior
no arguments	Single-pass scan of the current repository without edits
<path>	Scan one file or directory
-b <branch>	Scan a branch diff
--base <branch>	Select the branch-diff base
--staged	Scan staged source files
--pr [current|recent|N]	Review a pull request
--pr-security	Review pull-request security context
--scan-only	Request report-only behavior
--review	Alias for --scan-only
--loop	Continue until queued coverage is complete
--no-loop	Explicitly keep single-pass behavior
--plan-only	Build strategy/plan, then stop
--plan	Alias for --plan-only
--fix	Permit the reviewed fix phase
--approve	Request the host's reviewed/default permission mode
--safe	Alias for --fix --approve
--dry-run	Build remediation output without source edits
--preview	Alias for --fix --dry-run
--autonomous	Permit unattended fixing
--auto-commit	Separately grant commit permission for authorized fixes
--deps	Add supported Node.js dependency auditing
--threat-model	Generate or load a STRIDE threat model
--security-review	Run the bundled repository security workflow
--validate-security	Add focused security-finding validation

Examples:

/bug-hunter
/bug-hunter --loop src/
/bug-hunter --pr-security
/bug-hunter --deps --threat-model src/
/bug-hunter --plan src/
/bug-hunter --fix --approve src/auth
/bug-hunter --autonomous --auto-commit src/

Do not combine report-only intent with mutation intent. The skill should keep read-only and mutation authority explicit rather than resolving contradictory requests silently.

Internal measurable runner controls

Integrations that invoke scripts/run-bug-hunter.cjs directly can provide additional controls such as:

--max-source-tokens <n>
--confidence-threshold <n>
--triage-path <triage.json>
--benchmark-report <benchmark-report.json>
--adaptive-profile <auto|fast|balanced|assurance>
--adaptive-plan-path <adaptive-plan.json>
--verification-plan <verification-plan.json>
--verification-report <verification-report.json>
--verification-required <true|false>
--verification-total-budget-ms <milliseconds>
--evidence-cache <directory>

These are not automatically public /bug-hunter flags. They belong to the runner/integration surface and are persisted in run identity where relevant. Explicit limits override adaptive defaults.

Canonical runner outputs

The measurable layers introduce these schema-backed artifacts in addition to the role/report/fix contracts:

• adaptive-plan.json;
• retrieval-plan.json;
• verification-report.json;
• benchmark-report.json.

See how it works and world-class protocol for semantics.

The canonical public argument parser and permission contract live in SKILL.md.