Hooks

The hook protocol

xCoder hooks are Claude-Code-format: standalone Node scripts that receive JSON on stdin and signal decisions via exit code:

{
  "tool_name": "Bash",
  "tool_input": { "command": "git commit -m \"fix: thing #42\"" },
  "cwd": "/Users/.../my-project"
}

no-edit-on-integration

PreToolUse — covers I-1 and I-2.

Blocks Edit, Write, MultiEdit, NotebookEdit and Bash git commit/push when HEAD is on the configured integration branch.

What the agent sees on block

BLOCKED: refusing git commit/push on integration branch `main`.

Flow discipline (xc boot → ON START OF WORK):
  1. Create or find a tracking issue:  gh issue create ...
  2. Create a feature branch:          git checkout -b feat/<slug>
  3. Re-run the git commit/push

If this IS a hotfix that genuinely belongs on main:
  export XCODER_ALLOW_INTEGRATION_EDIT=1

If this repo really does want direct commits to main:
  set workflow.commitDirectly: true in .claude/settings.json

Bypass paths

• env XCODER_ALLOW_INTEGRATION_EDIT=1 — single shell invocation only. Right for hotfixes.
• config workflow.commitDirectly: true in .claude/settings.json — repo-wide opt-in. Right for solo / throwaway repos.

A note on the regex

The hook strips top-level quoted strings from the command before matching, so an echo with literal text like echo "git commit ..." doesn't trigger. The match is anchored to command-segment start (after ;, &&, ||, etc.).

typecheck-must-pass-before-commit

PreToolUse — covers I-6.

Blocks git commit when the project's TypeScript compilation fails. Runs npx tsc --noEmit with a 30-second budget.

Skipped when

• The Bash tool isn't being invoked.
• The command isn't a real git commit.
• The repo has no tsconfig.json.
• --no-verify or --amend is in the command.

Bypass paths

• env XCODER_SKIP_QA_GATE=1 — for intentional WIP commits.
• flag git commit --no-verify — standard git escape hatch.

commit-must-reference-issue

PreToolUse — covers I-8.

Blocks git commit -m "msg" when the message doesn't reference a tracking issue.

Accepted patterns

• #42 — bare reference, anywhere in the message.
• closes #42, fixes #42, resolves #42 (case-insensitive).
• issue 42, issues/42 (literal "issue").

Skipped when

• The command lacks -m (interactive editor mode).
• --no-verify, --amend, or --allow-empty is present.

Bypass paths

• env XCODER_SKIP_ISSUE_REF=1 — for chore commits with no tracking issue.
• flag git commit --no-verify.

session-end-pr-backstop

Stop — covers I-9.

Fires when the agent ends its turn. Notifies (or auto-opens) when HEAD is on a feature branch ahead of integration but no PR exists. A corrective layer rather than preventive — the equivalent of Open SWE's open_pr_if_needed middleware.

Behavior modes

Skipped when

• HEAD is on the integration branch.
• HEAD is detached.
• 0 commits ahead of integration.
• Working tree has uncommitted changes (don't surprise mid-work).
• A PR already exists for the branch.
• gh CLI is not available.

Installing the hooks

Automatic

xc hooks deploy

Detects your runtime (Claude Code today, others as drivers ship) and writes .claude/settings.json in place.

Manual

Add the following to your repo's .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit|NotebookEdit|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$CLAUDE_PROJECT_DIR\"/node_modules/@xcoder/xcoder/dist/hooks/branch-guard.js",
            "timeout": 5
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$CLAUDE_PROJECT_DIR\"/node_modules/@xcoder/xcoder/dist/hooks/qa-before-commit.js",
            "timeout": 35
          },
          {
            "type": "command",
            "command": "node \"$CLAUDE_PROJECT_DIR\"/node_modules/@xcoder/xcoder/dist/hooks/issue-ref-guard.js",
            "timeout": 5
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$CLAUDE_PROJECT_DIR\"/node_modules/@xcoder/xcoder/dist/hooks/session-end-pr-backstop.js",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Next