rogerchappel/toolhutch

toolhutch

Local-first permission auditor for agent tool manifests. Point toolhutch at MCP configs, OpenClaw-style tool manifests, or JSON/YAML fixtures and get a practical risk brief before an agent gets sharp tools.

Install

npm install
npm run build

For local CLI use from this repository:

node dist/cli.js --help

Use

toolhutch scan ./fixtures/risky-openclaw-tools.json
toolhutch scan ./fixtures/risky-openclaw-tools.json --fail-on high
toolhutch scan ./fixtures/mcp-mixed.yaml --format json
toolhutch explain ./fixtures/risky-openclaw-tools.json --json
toolhutch policy ./fixtures/risky-openclaw-tools.json --policy ./examples/toolhutch.policy.json

--fail-on and --format are scan-only options. policy always requires a nonempty --policy <path operand; explain and policy accept --json for structured output. Unsupported command-option combinations fail with usage exit 64.

Example output includes capability labels, risk levels, evidence paths, mitigations, and an approval plan for the risky capabilities found.

Approval plans

Every report includes local review gates derived from the highest detected risks:

• critical findings block until an owner approves the tool surface
• high-risk findings require maintainer approval
• medium and low findings are documented for later review
• policy denies are listed first and cause toolhutch policy to exit 3

Approval plans are deterministic and are not external approval workflow automation. They are meant to be copied into an issue, pull request, or run log before enabling new agent tools.

Capabilities detected

• shell execution
• filesystem read and write access
• browser automation and logged-in browser contexts
• network access
• messaging or external posting
• secrets and credential surfaces

• database access
• package manager execution

Policy files