Set up graft on a repository
Setup opens a browser and stores a private key on this machine, so a person runs it. In Claude Code, prefix each command with ! to run it as yourself in the session.
-
Install the CLI (once per machine). It must be on
PATH; hooks and the git credential helper call it by name.Terminal window npm install -g @oakgreencc/graft -
From inside the repository’s clone, run:
Terminal window graft setupIf the repository’s owner has no App yet, this creates one through GitHub’s manifest page (named
<owner>-agentsby default;--namepicks another), then bootstraps the repository. To run the two halves separately, usegraft setup app, thengraft setup project.If you already have an App, register it with
graft setup app --manual. -
In the browser, confirm the App, then install it on only the repositories agents should work in.
-
Review the diff
graft setup projectshows. It writes.graft.json, seeds CODEOWNERS and merges into.claude/settings.json. Commit those files yourself. -
If
ghis not logged in as a repository admin, import the ruleset it saved under~/.config/graft/rulesets/at Settings → Rules → New ruleset → Import a ruleset. -
Restart every Claude Code session already open in the repository. The git environment and hooks load at session start.
-
Check:
Terminal window graft doctor✗lines are broken and name their fix.!lines work but protect less than they appear to.
Options worth deciding up front
Section titled “Options worth deciding up front”Flag on graft setup project |
Decides |
|---|---|
--required-check <job> |
The CI check that must pass before merging. Add it once CI exists. |
--mergeable <a,b | none> |
Which base branches agents may merge into. |
--app-branches <prefix | none> |
Confine the App to creating branches under one prefix (agent/). |
--auto-merge / --no-auto-merge |
Turn on Allow auto-merge, needed by graft pr merge --auto. |
--config-in package.json |
Keep the policy under a "graft" key instead of .graft.json. |
Full lists: graft CLI, graft configuration, GitHub App and rulesets.
A second App for workers
Section titled “A second App for workers”If cambium’s workers should act as a different identity, repeat step 2 with graft setup app --name <name>, then check with GRAFT_APP=<name> graft doctor.