add-git-sync

Files (5)

• SKILL.md
• git-pre-compact.sh · templates/
• git-session-start.sh · templates/
• git-sync-local.sh · templates/
• git-sync.sh · templates/

SKILL.md (first lines)

# Add Git Sync

> ℹ️ **First, set expectations:** before anything else, print one short line with this skill's version and its most recent change — the top entry of `metadata.changelog` above — e.g. `add-git-sync vX.Y — recent: <summary>`. Then proceed.

Installs three hooks that turn the agent's own repo into its durable state layer:

| Hook | Event | Job |
|---|---|---|
| `git-session-start.sh` | `SessionStart` (startup/resume) | Stash local drift → fetch → rebase onto remote branch → restore drift. Every session begins consistent with origin. |
| `git-pre-compact.sh` | `PreCompact` | Fast local commit so in-flight work survives context compaction. No push. |
| `git-sync.sh` | `Stop` (async) | `git add -A` → commit → push with rebase-on-reject retry. Drops `.git/SYNC_FAILED` if it can't reconcile; SessionStart surfaces the note next run. |

**Who this is for:** any agent whose directory is its own git repo and is worked on in **local** Claude Code sessions that should leave the repo committed and pushed — authoring an agent before it is deployed, long-running local research agents. Not appropriate for agents nested inside a larger monorepo.

**Where it fits with Trinity:** Trinity deploys an agent by **cloning its GitHub repo**, so the deployed agent starts from whatever the branch tip holds. Locally, these hooks keep that tip honest — work is committed and pushed at session end instead of lingering uncommitted, so the deployed copy's own pull (or `/trinity:sync`) carries it forward. **Inside a deployed agent the hooks stand down:** the platform heartbeat owns commit-and-push there (one writer, visible in sync health — trinity-enterprise#708), and the hooks exit as soon as they see the platform (`/opt/trinity/hooks`). Committing them to the repo is harmless; they simply stay silent on Trinity.

**Escape hatches baked in:**
- `touch .git/NO_AUTOSYNC` — disables all three hooks
- `echo "..." > .git/SELF_SELECT_MSG` — subagents write structured commit messages that survive the generic Stop-hook commit
- `.git/SYNC_FAILED` — propagates push failures forward to the next session

---

## Process

### Step 1: Preflight

Run from inside the target agent directory (or ask the user for the path). Verify:

```bash
# 1. CWD has CLAUDE.md (i.e. is an agent root)
[ -f CLAUDE.md ] || ask_user_for_agent_path

# 2. CWD is a git repo root (not nested). Resolve both sides with `pwd -P`
#    so macOS /tmp vs /private/tmp symlinks don't cause a false positive.
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
if [ -z "$REPO_ROOT" ]; then
  # Not a git repo — ask whether to init
  :
elif [ "$(cd "$REPO_ROOT" && pwd -P)" != "$(pwd -P)" ]; then
  # Nested inside a larger repo — refuse or offer local-only
  echo "ERROR: Agent dir is nested inside $REPO_ROOT. Hooks would push the wrong scope."
  exit 1
fi

# 3. Does .claude/settings.json exist? (create if missing)
# 4. Do any of the target hooks already exist? (if yes, diff and ask)
```

If no `.git/`: ask "Initialize git repo here?" If yes, `git init`.

### Step 2: Ask configuration questions

Use AskUserQuestion with these three questions (in order):

**Q1 — Sync mode**
- `remote-push` (default) — Stop hook commits and pushes
- `local-only` — Stop hook commits but does not push (use when there's no remote or the agent is air-gapped)

**Q2 — Remote and branch** (only if Q1 = remote-push)
- Default: `origin` / `main`
- If `git remote get-url origin` fails, ask for the remote URL and set it up before continuing

**Q3 — Commit co-author line**
- Default: `Co-Authored-By: Claude <noreply@anthropic.com>`
- Or blank (no co-author)

### Step 3: Install hook scripts

Templates live in this skill's `templates/` directory. Copy to the agent's `.claude/hooks/` with placeholder substitution:

```bash
SKILL_DIR="$(dirname "${0}")"  # resolved at runtime
TEMPLATES="$SKILL_DIR/templates"
HOOKS_DIR="$AGENT_DIR/.claude/hooks"
mkdir -p "$HOOKS_DIR"

substitute() {
  local src="${1}" dst="${2}"
  sed -e "s|__BRANCH__|$BRANCH|g" \
      -e "s|__REMOTE__|$REMOTE|g" \
      -e "s|__COAUTHOR__|$COAUTHOR|g" \
      "$src" > "$dst"
  chmod +x "$dst"
}

if [ "$MODE" = "remote-push" ]; then
  substitute "$TEMPLATES/git-session-start.sh" "$HOOKS_DIR/git-session-start.sh"
  substitute "$TEMPLATES/git-pre-compact.sh"   "$HOOKS_DIR/git-pre-compact.sh"
  substitute "$TEMPLATES/git-sync.sh"          "$HOOKS_DIR/git-sync.sh"
else
  # local-only: no SessionStart (no remote to rebase from)
  substitute "$TEMPLATES/git-pre-compact.sh"   "$HOOKS_DIR/git-pre-compact.sh"
  substitute "$TEMPLATES/git-sync-local.sh"    "$HOOKS_DIR/git-sync.sh"
fi
```

**Idempotency:** before overwriting any existing hook file, diff content. If identical, skip silently. If different, show the diff and ask the user whether to overwrite.

### Step 4: Merge into `.claude/settings.json`

Load existing settings (create `{}` if missing), merge the `hooks` block, write back. Use `jq` to keep the JSON canonical:

```bash
SETTINGS="$AGENT_DIR/.claude/settings.json"
[ -f "$SETTINGS" ] || echo '{}' > "$SETTINGS"

# Build the hooks JSON we want to ensure is present
NEW_HOOKS=$(jq -n --arg mode "$MODE" '{
  SessionStart: (if $mode == "remote-push" then [{
    matcher: "startup|resume",
    hooks: [{
      type: "command",
      command: "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/git-session-start.sh",
      timeout: 20,
      statusMessage: "Syncing from git..."
    }]
  }] else null end),
  PreCompact: [{

From Abilityai/trinity-skills, Apache-2.0.

More from Abilityai/trinity-skills