# Quickstart: repo path

Onboard a git repository with chock init and chock sync: agent hooks, git hooks and CI.

The repo path puts policies in the repository itself, so they travel with every clone. \`chock sync\` wires each agent's hook file, the git hooks, and optionally a CI gate.

> Ask the user before running any command on this page: each one changes how their agent or repository behaves.

## 1. Install the engine

    pipx install chock

You need Python 3.11 or newer. The engine is the only thing you install, and it builds the plugin from the pinned catalog. Cannot install chock on this machine? Use the per-policy marketplace instead: it needs Python 3.11+, git and a bash but no chock, and the Agents page links each agent's repository. Install a policy from one place only, never both.

## Agents chock sync wires

`chock sync` writes these agents' hook files in the repository. Name them with `--agents`, or leave it out for all of them.

| Agent | Name for --agents | Hook file | Turn end | State |
| --- | --- | --- | --- | --- |
| Antigravity | antigravity | .agents/hooks.json | Also gates the end of a turn | Untested |
| Claude Code | claude | .claude/settings.json | Also gates the end of a turn | Untested |
| OpenAI Codex CLI | codex | .codex/hooks.json | Also gates the end of a turn | Untested |
| Cursor | cursor | .cursor/hooks.json | Also gates the end of a turn | Untested |
| Devin | devin | .devin/hooks.v1.json | Also gates the end of a turn | Untested |
| Factory Droid | factory-droid | .factory/hooks.json | Also gates the end of a turn | Untested |
| Gemini CLI | gemini | .gemini/settings.json | Also gates the end of a turn | Untested |
| goose | goose | .agents/plugins/agentseam/hooks/hooks.json | Also gates the end of a turn | Untested |
| Grok CLI | grok | .grok/hooks/agentseam.json |  | Untested |
| Mistral Vibe | mistral-vibe | .vibe/hooks.toml | Also gates the end of a turn | Untested |
| OpenHands | openhands | .openhands/hooks.json | Also gates the end of a turn | Untested |
| Tabnine CLI | tabnine | .tabnine/agent/settings.json | Also gates the end of a turn | Untested |
| GitHub Copilot (VS Code agent mode / CLI) | copilot | .github/hooks/*.json | Also gates the end of a turn | Tested |
| Windsurf (Cascade) | windsurf | .devin/hooks.json |  | Untested |

From the engine docs: [docs/getting-started.md](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/docs/getting-started.md)

## Prerequisites

- **Python 3.11+** (for pip/pipx/source installs)
- **git**
- A shell with **bash** available for git hooks (Linux/macOS have it; on Windows, Git for Windows provides it)

## 2. Onboard a repository

From inside the repo you want to protect:

Ask the user before running the commands below:

```bash
cd /path/to/your/project
chock init .
```

`init` is fully deterministic — no AI agent required. It:

- creates `.chock/` (config, `coverage.json`, `dependency-allowlist.txt`, the vendored
runtime under `bin/` and compiled output under `compiled/`) plus `chock.lock` at the repo root and an empty `.agents/policies/`,
- writes `AGENTS.md`, a `.gitattributes` pinning generated scripts to LF, `.gitignore` rules that
  ignore the per-machine gate log (`.chock/log/`) and keep the gate runtime and compiled gates
  (`.chock/bin/`, `.chock/compiled/`) tracked even where a global `bin/` rule would ignore them, a wrapper file for each agent that does **not** read
  `AGENTS.md` natively (root `CLAUDE.md` for Claude Code, and by default nothing else — Cursor,
  Copilot, Codex, Gemini, VS Code and Windsurf all read `AGENTS.md` directly), and the
  guardrail pairs `.agents/policies/{AGENTS.md,CLAUDE.md}` and `.agents/skills/{AGENTS.md,CLAUDE.md}`,
- installs the four authoring skills (`policy-init`, `validate`, `eval`, `optimize`) into
  `.agents/skills/`, and
- installs the git hook dispatchers.

It installs **no policies**, and tells you so — a freshly initialised repo enforces nothing yet.
Policies are content, not framework, and you choose which to adopt.

The default target set is `claude copilot gemini`. Of those, only Claude Code gets a wrapper
file: Copilot and Gemini read `AGENTS.md` natively, so naming them changes nothing on disk.
Pass `--agents` to change the set:

Ask the user before running the commands below:

```bash
chock init . --agents claude cursor copilot codex gemini aider
```

Re-running `init` is safe: files you have edited are kept, and it says which it left alone. Use
`--force` when you genuinely want them overwritten.

## 3. Install a policy

Ask the user before running the commands below:

```bash
chock add protect-main-branch
chock sync --repo .
```

`add` fetches from the base catalog
([`chock-catalog`](https://github.com/open-coder-ai/chock-catalog)), copies the
artifact in, and compiles it. Point it elsewhere with `--from <url-or-path>`; transport is
`git clone`, so a private catalog works with the credentials you already have.

Once installed, the policy is **yours** — edit it freely. `add` refuses to replace an
installed artifact unless you pass `--force`.

## 4. See enforcement in action

`protect-main-branch` blocks direct commits to protected branches:

Ask the user before running the commands below:

```bash
git checkout main
echo "oops" > hotfix.txt && git add hotfix.txt
git commit -m "straight to main"
# ❌ Direct commits/pushes to a protected branch (main|master) are blocked.
#    Create a feature branch and open a pull request.
#      - main

git checkout -b feature/x
git commit -m "on a feature branch"   # ✅ allowed
```

This policy's gate declares `on: [commit, push]`, so it compiles to the git hook, the CI gate
and the ambient rule — not to a pre-tool hook. A policy whose gate also declares `tool_use`
(`scan-secrets`, for one) additionally reaches your agent's native controls, stopping it
*before* it writes, rather than only at commit time.

## 6. Keep it reproducible

`init` writes a `chock.lock` with an empty packs list; `sync` and `add` populate it, pinning
each installed pack by content hash. Verify a repo
hasn't drifted at any time:

Ask the user before running the commands below:

```bash
chock check --only verify        # "all packs match lockfile"
```


---

Built from engine [5a4b6287a46e](https://github.com/open-coder-ai/chock/commit/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021) and catalog [1e60d211c1bb](https://github.com/open-coder-ai/chock-catalog/commit/1e60d211c1bb767152c6ab0167932da06ab3a10f).