Installing with npx

The npx option puts the gate inside Claude Code as a PreToolUse hook. One command, and it is on in observe mode stopping nothing.

npx @trustcoco/guardrails claude-code

Restart Claude Code afterwards so the hook is picked up.

Good to know. The package is not on the public npm registry yet. Until it is, the install runs from a copy of the repository, npm install then node bin/coco claude-code, and access starts at trustcoco.ai.

What the installer does

Six things, in this order.

1. Finds a working python3 and proves it runs before writing a hook that depends on it.
2. Copies the gate to ~/.coco/gate, so the hook does not point into an npx cache that can be cleared. A guardrail that quietly stops running is worse than no guardrail, because nobody notices.
3. Copies the contracts to ~/.coco/packs and the mandate to ~/.coco/mandate.yaml, and leaves both alone if they are already there. Contracts are yours to edit and an existing set is never clobbered.
4. Compiles the YAML to JSON, and refuses to install if a contract does not compile.
5. Writes ~/.coco/config.json.
6. Merges a PreToolUse hook into ~/.claude/settings.json, keeping every hook it did not write and replacing its own previous entry.

Flags

Starting in enforce mode is possible and it is usually the wrong trade. Enforcement on day one blocks work on rules nobody has tested, and the fastest way to get a guardrail uninstalled is to have it block something legitimate on the first morning. Modes has the argument in full.

What lands where

~/.coco is created with owner-only permissions, and config.json is written the same way.

Which contracts arrive

Four, and they are deliberately quiet.

packs/baseline/credential_access.yaml
packs/baseline/destructive_command.yaml
packs/session/blast_radius.yaml
packs/session/credential_then_egress.yaml

The default mandate names the baseline and session sets and nothing else. The KYC and payments contract sets are not in the package, because neither can fire for a coding agent, and both live in the repository for a team that has the workflow they govern.

Verify it took

coco status

Coco gate
  mandate        coco.developer (active)
  mode           observe
  contracts      4 packs
  on error       block
  home           ~/.coco
  hook installed yes

  decisions      0
    allow        0
    block        0
    escalate     0

  Observe mode. Nothing is being stopped.
  Read 'coco report', then set mode to enforce in ~/.coco/config.json.

The hook installed line reads ~/.claude/settings.json and looks for the gate's own entry, so it answers whether Claude Code will actually call the gate rather than whether the files exist.

Getting the coco command

npx runs the package once and puts nothing on your PATH, so coco status works only if the package is installed globally.

npm install -g @trustcoco/guardrails    # then: coco status
npx @trustcoco/guardrails status        # or run it through npx every time

Both reach the same commands. Every example in these docs writes coco <command> for readability.

Installing as a Claude Code plugin

The repository is also a plugin with its own marketplace entry, which carries the hook, the setup skill and the operator commands together. That route suits a team that already distributes plugins, and it registers the same PreToolUse hook. It installs from the repository rather than from npm.

Next

• Quick start with npx to see it stop something
• Modes and the week before anything stops
• Managed fleet to install it as policy rather than a preference
• Uninstalling when you want it off