Guides

Configure

Selection files, switching plugin members on and off, local policies, and where to customise.

This page covers what you can change after an install, and the files that hold it.

The selection file

A selection is a small JSON or YAML file naming the agent, the pinned catalog commit and the policies you picked. The builder writes one for you. The install command reads the same file. These are the fields it checks:

Field	Meaning
`schema`	2, the selection format version.
`client`	The agent the plugin is built for: claude-code, cursor, codex, copilot, devin, grok, goose, antigravity, openhands, kimi-code, factory-droid. The --client option on the command line overrides it.
`bundle.version`	The plugin's version, 1.0.0 from this site.
`catalog.source`	The chock-catalog repository.
`catalog.ref`	The pinned catalog commit. The plugin builds only from it.
`catalog.release`	Optional. A named catalog release over the commit.
`preset`	Optional. The preset the picks started from.
`policies`	One entry per picked policy: from (catalog), id, version and sha256.

Switch members on and off

These commands come from the engine. Their help appears here as the engine prints it.

`chock bundle`

Switch a member of an installed plugin bundle on or off (bundle on|off <id>, bundle status)

usage: chock bundle [-h] {on,off,status} ...

Switch a member of an installed bundle.

positional arguments:
  {on,off,status}
    on             switch one policy on
    off            switch one policy off
    status         every installed bundle, each member's state and label

options:
  -h, --help       show this help message and exit

`chock enable`

Enable a policy by id

usage: chock enable [-h] [--repo REPO] policy_id

positional arguments:
  policy_id    Policy identifier to enable

options:
  -h, --help   show this help message and exit
  --repo REPO  Repo root

`chock disable`

Disable a policy by id

usage: chock disable [-h] [--repo REPO] policy_id

positional arguments:
  policy_id    Policy identifier to disable

options:
  -h, --help   show this help message and exit
  --repo REPO  Repo root

From the engine docs: docs/custom-policies.md

2. Add it to a selection

A schema-2 selection names it with from: local and a path relative to the selection file's own folder:

schema: 2
client: claude-code
bundle: {name: chock-guardrails, version: 1.0.0}
catalog: {source: https://github.com/open-coder-ai/chock-catalog, ref: <40-hex commit>}
policies:
  - {from: catalog, id: block-destructive-commands, version: <version>, sha256: <64-hex>}
  - {from: local, id: my-tf-destroy, path: .agents/policies/my-tf-destroy}

sha256 is optional on a local entry; when present, the folder must hash to it. A selection with only local entries needs no catalog. A link or a #s= code never carries a local policy: install refuses one, because only a file has a folder beside it.

From the engine docs: docs/baseline-policies.md

Customising a policy

Because an installed policy is yours, the first option is simply edit it. Change the regex, add your own token formats, drop rules you disagree with. Re-copying from the catalog is an explicit act; nothing does it behind your back.

Config overlays remain useful for things you want to change without touching the manifest:

policies:
  disabled: [block-no-verify]        # fully disable a policy
  overrides:
    scan-secrets:
      enforcement: advise            # downgrade to ambient rule only
    protect-main-branch:
      surfaces: [ambient-rule]       # or scope by explicit surfaces

disabled removes the policy's compiled artifacts and git-hook wiring.
overrides.<id>.surfaces becomes the targets passed to compile_policy.
overrides.<id>.enforcement: advise is shorthand for surfaces: [ambient-rule].
A policy marked mandatory: true cannot be disabled; the CLI and chock check both refuse.

Some values are reachable from config without editing the manifest — protect-main-branch reads chock.defaults.protected_branches via its config_key. Recompile after changing config, and the compiled gate, the block message and the advisory text all follow.

Use chock disable <id> and chock enable <id> for ergonomic toggles, or chock status to see the current state and coverage.

See Authoring Policies to write your own and Enforcement Surfaces for where each guard actually holds.

From the engine docs: docs/adopting.md

Golden rule: customize in these places only

Want to change	Do this	Never edit
Protected branch names	`.chock/config.yaml` → `defaults.protected_branches`	the installed policy manifest
Disable a policy	`.chock/config.yaml` → `policies.disabled`	deleting the policy folder
Add a team policy	`chock new policy <id>`	editing an unrelated policy
Add a skill or adapter	`chock new` or `install-skills`	generated adapter files

Customizing only in your own policies and config means git merge upstream/main stays clean.

Built from engine 5a4b6287a46e and catalog 1e60d211c1bb.