shipit

git, PRs, and merges your agent actually does for you

---

In vibe-coding sessions, git is the part you forget. You churn through three features in an afternoon, end up with one giant uncommitted mess, and lose all the natural checkpoints. shipit is a skill + hook pair that makes the agent treat version control as a first-class part of the work — auto-initializing repos, committing at logical task boundaries, opening PRs, resolving rebase conflicts, and squashing before merge.

Configurable autonomy: from "ask before every git operation" to "ship it, I'll review the PR." Ships for Claude Code, Codex, Gemini CLI, opencode, and other harnesses via the same installer pattern as caveman.

What it does

On first run in a non-git directory

• Asks: public or private GitHub repo?
• Asks: repo name? (default: directory name)
• Runs git init, creates the GitHub repo (via gh CLI or the agent's /install-github-app integration if available), pushes initial commit
• Sets up a sensible .gitignore based on detected stack

During coding

• Detects logical task boundaries (test passes, feature complete, file refactor done) and proposes a commit
• Writes the commit message — mimicking your existing commit history's style (Conventional Commits? JIRA IDs like PROJ-123? Plain prose? Whatever the last 20 commits show, it matches)
• One sentence, present tense, focused on why not what

Around PRs

• After N commits or a logical milestone, suggests opening a PR
• For large vibe-coded sessions, proposes splitting into multiple smaller PRs along natural seams (feature A, feature B, refactor) — easier to review, easier to revert
• Generates PR title + body from commits + diff summary
• Asks before pushing; asks before opening PR; asks before merging

Cleanroom — undo for AI-driven dev

Before any risky operation (migration, mass refactor, force-push, new dep install, mass file delete), shipit auto-snapshots: working tree to a labeled git stash, lockfiles to disk, optional pg_dump for DB changes. Say undo within the retention window (default 30 min) and shipit walks you through the rollback step by step. The biggest fear in AI-first dev — "the agent broke something and there's no undo" — solved.

Keeping main fresh

• Background git fetch --prune runs on a throttled cadence (default every 15 min) — never touches the working tree
• When main moves ahead of your feature branch, surfaces the drift once and proposes a rebase before push/PR/merge
• Refuses to merge a PR that isn't up to date with target — rebases first

Around rebase / merge

• On rebase conflict, attempts automatic resolution for trivial cases (import order, formatting, whitespace) and surfaces the rest with context: "3 conflicts. 2 auto-resolved. 1 in src/auth.ts:42 needs you — both sides changed the token check."
• Before merge, auto-squashes the branch into one clean commit with a generated message derived from the PR description

Autonomy levels

/shipit ask         ask before every git op (default)
/shipit auto        commit + push automatically, ask only for PR + merge
/shipit yolo        commit + push + PR automatically, ask only for merge
/shipit off         disable

The merge step always asks. shipit will never merge to main without explicit confirmation — that's a hard rule.

What it WON'T do

• Force-push to main / master / develop — ever
• Commit secrets — runs a basic regex sweep before every commit (api keys, .env, private keys); flagged files get pulled from the staged set and surfaced to you
• Skip pre-commit hooks (no --no-verify unless you explicitly say so)
• Merge a PR with failing required checks
• Delete branches without confirmation

Install

curl -fsSL https://raw.githubusercontent.com/USER/shipit/main/install.sh | bash

(scaffold — not published yet; see HANDOFF.md)

Requires git. gh CLI strongly recommended for PR/repo operations; falls back to URL-only flow without it.

Configuration

~/.config/shipit/profile.json:

{
  "default_mode": "ask",
  "default_visibility": "private",
  "github_user": "kagan",
  "commit_style": "auto",
  "commit_style_overrides": {
    "prefix_pattern": "PROJ-\\d+",
    "max_subject_length": 50
  },
  "auto_split_pr_threshold": 8,
  "fetch_interval_minutes": 15,
  "snapshot_retention_hours": 24,
  "snapshot_db_retention_hours": 72,
  "snapshot_db_auto": false,
  "protected_branches": ["main", "master", "develop", "production"],
  "never_commit_globs": ["*.env", "**/secrets/*", "*.pem"]
}

commit_style: "auto" makes shipit infer style from git log each session. Override only if you want to force a specific format regardless of history.

Per-repo overrides

Drop .shipit.json at the repo root for repo-specific rules (different protected branches, stricter secret patterns, required PR template path, etc.).

Pairs well with

• [[chronos]] — "you've been coding for 90 minutes uncommitted, want me to checkpoint?"
• [[pushback]] — pushback challenges the plan, shipit checkpoints the execution
• [[caveman]] — keeps the generated commit messages and PR bodies short