HoldTheGoblin

Stops unsafe coding agents before they call it done.

HoldTheGoblin is a local-first verification layer for AI coding agents. It blocks dangerous tool calls where the host agent supports hard hooks, runs tests and security scans before completion, writes evidence reports, and gives the agent concrete feedback to fix the work.

It is not a prompt checklist. It runs commands and fails closed when the configured gate fails.

30 Second Start

Current local checkout:

npm ci
npm run build
npm install -g .
cd your-project
holdthegoblin wrap --agent all .
holdthegoblin verify

After the public npm package is published, the install step becomes npm install -g holdthegoblin.

After wrapping a project:

• Claude Code gets hard hook blocking for dangerous Bash calls and sensitive file reads.
• Cursor gets project rules that require verification before completion.
• Codex gets AGENTS.md, .agents/skills, and .codex/skills guidance.
• Warp gets AGENTS.md, WARP.md, .agents/skills, and .warp/skills guidance.
• Any agent can use holdthegoblin verify, checkpoint, handoff validate, deploy run, tests generate, and MCP tools.

Demo: Block A Production DB Delete

cd holdthegoblin
npm ci
npm run demo:db-delete

The demo sends a Claude Code PreToolUse payload containing:

dropdb production

Expected output includes:

{"permissionDecision":"deny"}

The demo uses the real holdthegoblin hook claude entrypoint, not a mocked decision.

What It Checks

Layer	Behavior
Tool-call guard	Blocks destructive shell commands, literal credential arguments, and sensitive file reads through Claude Code hooks.
Test verifier	Detects JS/TS, Python, Go, Rust, and Java test/lint/typecheck commands.
Security scanner	Runs built-in secret scan; uses Semgrep and Trivy when installed.
CI hardening audit	Reports external GitHub Actions refs that are not pinned to full commit SHAs, with opt-in blocking policy and pinning remediation guidance.
Readiness score	Scores latest verification evidence, CI gates, hard/advisory agent setup, scanner availability, policy posture, and runtime evidence hygiene.
Test generation	Flags risky code paths and writes deterministic or LLM-assisted test plans through local/cloud providers.
Handoff proof	Validates multi-agent JSON handoffs against a schema.
Deploy guard	Runs verify, checkpoint, shadow/canary commands, health checks, rollback command, and checkpoint restore from a deploy plan.
Rollback	Creates local file checkpoints and restores them on demand or during failed deploy phases.
Observability	Writes evidence reports, redacted policy decision events, JSONL event logs, and Langfuse/AgentOps-compatible export payloads under .holdthegoblin/.
MCP	Exposes verifier, readiness scoring, read-only config validation, policy evaluation, risk assessment, checkpoint, handoff, deploy, test generation, and observability tools over stdio or Streamable HTTP.

Commands

holdthegoblin --version
holdthegoblin wrap --agent claude-code|cursor|codex|warp|all [path]
holdthegoblin init --agent claude-code|cursor|codex|warp|all [--mode relaxed|balanced|strict]
holdthegoblin verify [--format text|json|markdown|html] [--github-step-summary] [--github-annotations]
holdthegoblin readiness [--format text|json] [--verify]
holdthegoblin hook claude
holdthegoblin checkpoint create|list|rollback [--id latest] [--delete-new]
holdthegoblin handoff validate --schema schema.json --input payload.json
holdthegoblin risk assess --command "rm -rf /" [--format json]
holdthegoblin risk assess --tool Read --path .env [--format json]
holdthegoblin config validate [--path .holdthegoblin/config.json] [--format json]
holdthegoblin config schema
holdthegoblin events [--limit 20] [--format text|json]
holdthegoblin doctor
holdthegoblin mcp
holdthegoblin mcp-http [--host 127.0.0.1] [--port 3333] [--allowed-host localhost] [--auth-token token]
holdthegoblin deploy init [--output holdthegoblin.deploy.json]
holdthegoblin deploy run --plan holdthegoblin.deploy.json [--dry-run] [--allow-dangerous] [--format json]
holdthegoblin observability export --provider langfuse|agentops|all [--send] [--timeout-ms 15000]
holdthegoblin tests generate [--provider deterministic|ollama|ollama-cloud|openai-compatible|openai|groq|openrouter|anthropic|minimax|zai|kimi|deepseek] [--model model] [--base-url url] [--timeout-ms 60000]
holdthegoblin models providers [--format json]
holdthegoblin demo

verify --format changes stdout only. Verification reports are still written under .holdthegoblin/.

readiness is advisory scoring, not a new enforcement boundary. It returns release-ready, guarded, partial, or at-risk from local evidence, and non-passing checks include a concrete remediation. --verify runs verification first and writes fresh .holdthegoblin/ reports before scoring.

verify --github-step-summary appends a concise Markdown job summary to the GitHub Actions GITHUB_STEP_SUMMARY file. This is report-only output; the CI gate still passes or fails from the verify exit code.

verify --github-annotations emits redacted GitHub Actions workflow command annotations for failed checks, failed commands, warnings/skips, and scanner findings. It is log-only report output and cannot be combined with --format json or --format html.

Agent Integrations

Claude Code

holdthegoblin wrap --agent claude-code . writes project hooks to .claude/settings.json.

Hard blocking is available for:

• PreToolUse: dangerous Bash commands, literal credential arguments, and sensitive reads.
• PostToolBatch: quick security verification after file mutations.
• Stop: full verification before Claude finishes.

Claude Code hook behavior is based on the official hooks contract: https://code.claude.com/docs/en/hooks

Cursor

holdthegoblin wrap --agent cursor . writes .cursor/rules/holdthegoblin.mdc.

Cursor rules are guidance, not a hard sandbox. They are still useful because they keep verification visible in the coding loop, but production enforcement should happen through Claude hooks, CLI verification, or CI.

Cursor project rules live in .cursor/rules: https://docs.cursor.com/en/context

Codex

holdthegoblin wrap --agent codex . writes AGENTS.md, .agents/skills/holdthegoblin/SKILL.md, and .codex/skills/holdthegoblin/SKILL.md.

This is project guidance for Codex: run holdthegoblin verify, use checkpoints before risky changes, avoid credential reads, and cite .holdthegoblin/latest.md as evidence. It is not a hard runtime sandbox.

Agents without hard hook support can run holdthegoblin risk assess before risky tool calls. This is advisory preflight output; enforcement still depends on the host agent, CLI exit code handling, or CI.

Every Claude PreToolUse decision is also written as a redacted holdthegoblin.policy_event.v1 / holdthegoblin.policy_decision.v1 audit event under .holdthegoblin/events.jsonl.

Warp

holdthegoblin wrap --agent warp . writes AGENTS.md, WARP.md, .agents/skills/holdthegoblin/SKILL.md, and .warp/skills/holdthegoblin/SKILL.md.

Warp uses project rules from AGENTS.md by default and supports WARP.md for compatibility: https://docs.warp.dev/agent-platform/capabilities/rules

Because Warp project rules are advisory, the generated rules steer agents to use holdthegoblin risk assess for command/path preflight checks and holdthegoblin verify for completion evidence.

Generic Agents And Frameworks

Use the CLI directly:

holdthegoblin verify --format json
npm exec -- holdthegoblin verify --format json
holdthegoblin handoff validate --schema examples/handoff/schema.json --input examples/handoff/payload.json

The npm exec fallback is for projects that install HoldTheGoblin as a dependency. For unpublished local development, use npm install -g . or npm link from this repository.

The TypeScript SDK is exported from holdthegoblin. It includes dependency-light LangGraph node helpers and CrewAI guard helpers. Python CrewAI projects can use integrations/crewai/holdthegoblin_guard.py.

GitHub Actions Gate

Copy examples/github-action/holdthegoblin-verify.yml into .github/workflows/holdthegoblin.yml in a downstream repository to run HoldTheGoblin on pull requests.

The workflow validates config first, then runs holdthegoblin verify, publishes a concise GitHub Actions job summary, and uploads local evidence reports as an artifact. It is a CI gate, not an agent sandbox: failures are enforced by the pull request check result.

Semgrep and Trivy are optional external scanners. See docs/SCANNERS.md for setup recipes and current supply-chain cautions.

Test Generation

holdthegoblin tests generate
holdthegoblin tests generate --provider ollama --model glm-5.1:cloud
holdthegoblin tests generate --provider ollama-cloud --model gpt-oss:120b
holdthegoblin tests generate --provider openrouter --model openrouter/auto
holdthegoblin tests generate --provider kimi --model kimi-k2.6
holdthegoblin tests generate --provider zai --model glm-5.1
holdthegoblin tests generate --provider minimax --model MiniMax-M2.7
holdthegoblin tests generate --provider deepseek --model deepseek-v4-flash

The default deterministic provider writes .holdthegoblin/generated-tests.md from risky changed code paths. LLM providers expand that into richer test drafts and fall back to the deterministic plan if the provider fails. It does not silently modify your test suite.

Supported providers:

• ollama: local Ollama daemon, including signed-in :cloud models through ollama run/pull.
• ollama-cloud: direct Ollama Cloud API with OLLAMA_API_KEY.
• openai-compatible: any OpenAI-compatible endpoint through OPENAI_COMPATIBLE_BASE_URL, OPENAI_COMPATIBLE_API_KEY, and OPENAI_COMPATIBLE_MODEL.
• openai, groq, openrouter, anthropic: user-supplied API keys and model names.
• minimax: MiniMax native subscriptions through MINIMAX_API_KEY, with MINIMAX_BASE_URL available for regional or legacy endpoints.
• zai: z.ai / GLM native subscriptions through ZAI_API_KEY or GLM_API_KEY.
• kimi: Kimi / Moonshot native subscriptions through KIMI_API_KEY or MOONSHOT_API_KEY.
• deepseek: DeepSeek native subscriptions through DEEPSEEK_API_KEY.

Use:

holdthegoblin models providers

to print the current provider registry and required environment variables.

Deploy Guard

holdthegoblin deploy init --output holdthegoblin.deploy.json
holdthegoblin deploy run --plan holdthegoblin.deploy.json

A deploy plan can define shadow, shadowHealth, canary, canaryHealth, promote, and rollback commands. HoldTheGoblin runs verification first, creates a local checkpoint by default, and restores checkpoint-tracked files if a guarded deploy phase fails.

Commands that match destructive or human-approval risk rules are blocked by default. Hard-deny rules cannot be bypassed by deploy-plan JSON. Human-approval ask rules require both allowDangerous: true in the reviewed plan and an explicit --allow-dangerous run flag.

Use argv arrays for new deploy plans so commands run without a shell:

{
  "shadow": { "argv": ["npm", "run", "deploy:shadow"], "env": ["DEPLOY_TOKEN"] },
  "shadowHealth": { "argv": ["npm", "run", "health:shadow"] }
}

Spawned commands inherit only a small safe environment by default. Use .holdthegoblin/config.json execution.env for verification/scanner commands and deploy command env lists for deploy phases that need reviewed environment variable names from the current process; never put secret values in config or plans.

Disabling deploy verification, checkpoint creation, checkpoint rollback, or required health gates is blocked unless the reviewed plan sets allowPolicyDowngrade: true and the run also passes --allow-dangerous.

Observability Export

holdthegoblin observability export --provider all
holdthegoblin observability export --provider langfuse --send

Local exports are written to .holdthegoblin/exports/. --send is opt-in. Langfuse send mode uses LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and optional LANGFUSE_BASE_URL. AgentOps send mode expects AGENTOPS_API_KEY and AGENTOPS_INGEST_URL for an OpenTelemetry relay you control.

MCP Server

HoldTheGoblin ships a local stdio MCP server so MCP-capable agents can call the same verifier, read-only config validation, checkpoint, handoff, deploy, test generation, observability, and event tools without shelling out manually.

holdthegoblin mcp
holdthegoblin mcp-http --host 127.0.0.1 --port 3333

When binding beyond loopback, pass a strong bearer token and explicit allowed hosts:

HOLDTHEGOBLIN_MCP_HTTP_TOKEN="$(openssl rand -hex 24)" \
  holdthegoblin mcp-http --host 0.0.0.0 --port 3333 --allowed-host your-host.example

Example MCP client config:

{
  "mcpServers": {
    "holdthegoblin": {
      "command": "holdthegoblin",
      "args": ["mcp"]
    }
  }
}

Available tools:

• verify: run tests, security checks, edge-case detection, and evidence reporting.
• readiness: score latest verification evidence, CI gates, agent setup, scanner availability, policy posture, and evidence hygiene.
• doctor: inspect project setup and planned commands.
• config_validate: validate .holdthegoblin/config.json before verify; this is read-only config checking, not an independent sandbox or hard enforcement layer.
• policy_evaluate: evaluate a normalized shell/file/tool policy event and write a redacted local audit decision.
• risk_assess: evaluate a proposed shell command or tool path; this is advisory unless the host enforces the decision.
• checkpoint_create, checkpoint_list, checkpoint_rollback: snapshot and restore local work.
• handoff_validate: validate a JSON handoff payload against a schema.
• events: read recent HoldTheGoblin event logs.
• deploy_run: execute a guarded deploy plan.
• observability_export: write or send observability payloads.
• tests_generate: write deterministic or LLM-assisted test plans.
• models_providers: list supported model providers and environment variables.

The verify MCP tool accepts format: "html" and returns HTML as text content. Verification also writes .holdthegoblin/latest.html and .holdthegoblin/runs/<run-id>.html; JSON responses include htmlReportPath.

LLM-assisted test generation is opt-in. Provider base URLs reject URL credentials, credential-like path/query/fragment values, non-loopback cleartext HTTP, and redirects; loopback HTTP remains supported for local model servers.

Evidence Reports

Each verification writes:

.holdthegoblin/latest.md
.holdthegoblin/latest.html
.holdthegoblin/runs/<run-id>.json
.holdthegoblin/runs/<run-id>.md
.holdthegoblin/runs/<run-id>.html
.holdthegoblin/events.jsonl

In GitHub Actions, pass --github-step-summary to add a short Markdown summary to the workflow run page. The summary contains counts, failed checks, warnings/skips, findings, and root-relative evidence paths; it does not include raw command stdout or stderr.

Pass --github-annotations to add workflow UI annotations for failed checks, failed commands, warnings/skips, and scanner findings. Annotation messages are redacted and escaped before printing, and command annotations point to the evidence report instead of embedding raw stdout or stderr.

Other commands may also write:

.holdthegoblin/exports/*.json
.holdthegoblin/deploy-latest.json
.holdthegoblin/generated-tests.md

Use:

holdthegoblin events --limit 10

to review recent init, verification, and guard events.

Modes

• relaxed: more issues are warnings.
• balanced: default; fails tests, secrets, Semgrep ERROR, Trivy HIGH|CRITICAL.
• strict: missing tests are also a failure.

Examples

• examples/db-delete-block: hard hook denial demo.
• examples/handoff: schema and payload validation.
• examples/claude-hook: raw Claude hook payload.
• examples/cursor-rule: Cursor integration notes.
• examples/codex-rule: Codex AGENTS.md integration notes.
• examples/warp-rule: Warp AGENTS.md/WARP.md integration notes.
• examples/github-action: pull request verification workflow template.
• examples/mcp: MCP server client config.
• examples/deploy: shadow/canary deploy plan example.
• examples/observability: Langfuse and AgentOps export notes.
• examples/langgraph: LangGraph adapter example.
• examples/crewai: CrewAI guard example.
• examples/testgen: deterministic, Ollama Cloud, and external provider test generation notes.

Development

npm ci
npm run typecheck
npm test
npm run smoke
npm run demo:db-delete
npm run package:smoke
npm run release:check
npm pack --dry-run

CI runs the same checks on Node 20 and 22.

Project docs:

• docs/ARCHITECTURE.md: verifier and integration design.
• docs/CONFIG.md: policy, execution, scanner, and observability configuration.
• docs/SCANNERS.md: optional Semgrep/Trivy CI setup recipes.
• docs/ROADMAP.md: what is implemented now and what stays on the V1 roadmap.
• PRIVACY.md: local reads/writes, opt-in network egress, and redaction scope.
• CONTRIBUTING.md: local development and release checklist.
• SECURITY.md: vulnerability reporting and guardrail scope.

Limitations

• Cursor rules are advisory; they cannot enforce a hard block by themselves.
• Codex and Warp project rules are advisory; use CI or Claude Code hooks for hard enforcement.
• mcp-http exposes Streamable HTTP on a host/port. It uses MCP SDK host validation. When binding beyond localhost, HOLDTHEGOBLIN_MCP_HTTP_TOKEN or --auth-token plus at least one --allowed-host is required; still put TLS and network policy in front of it.
• Semgrep and Trivy are optional external CLIs. If missing, HoldTheGoblin reports them as skipped.
• Deterministic test generation writes a test plan, not committed test files. External providers require the user to bring their own API key/subscription. HoldTheGoblin does not resell model access.
• Langfuse direct send uses the legacy ingestion API shape; Langfuse recommends OpenTelemetry for new ingestion pipelines. AgentOps export is OTLP-style JSON intended for a relay or SDK bridge.
• Deploy guard runs the commands you configure. It blocks known risky command text and requires explicit approval for human-review rules, but it is not a sandbox or a replacement for cloud-provider permissions, backups, or production deployment controls.

For intentional fake credentials in tests or demos, add holdthegoblin: allow-secret on that line.

License

MIT