Agents
An agent should run shipcheck run instead of the project's tests, and shipcheck commit -m "<subject>" instead of git commit. Then the run it waits for is the PR's check, and every commit is a tree that already passed. When a run fails, the agent reads shipcheck logs, reruns the failed job with shipcheck run --job <id>, and finishes with one full shipcheck run before it commits. shipcheck works the same with any agent, or with a person. It writes no agent config, hooks or permissions, since it does not know which agent you use or how you set it up.
Instructions
shipcheck init writes a short block between <!-- shipcheck:start v4 --> and <!-- shipcheck:end --> markers into the files agents read. Commit the files it changes. Running it again replaces only the text between the markers.
| File | When |
|---|---|
AGENTS.md | Always. Most agents read it |
CLAUDE.md, .claude/CLAUDE.md | When it exists and does not import AGENTS.md: an @AGENTS.md line in CLAUDE.md, or @../AGENTS.md in .claude/CLAUDE.md |
GEMINI.md | When it exists |
.github/copilot-instructions.md | When it exists |
If your agent reads another file, point it at AGENTS.md in that agent's own settings.
SKILL.md says how to run shipcheck, read a result and fix a failed check. Put it wherever your agent loads skills, if it does.
Git hooks
shipcheck install installs the pre-push and post-commit git hooks for the clone. They start a run in the background, so an agent that runs git commit instead of shipcheck commit still gets its check, after one more run. They never block git.
Your agent's sandbox
shipcheck keeps its results in SHIPCHECK_HOME, a folder your user can write. Nothing in shipcheck stops an agent from writing a fake result there. If your agent has a sandbox, keep it on and keep that folder outside its writable paths. See limits.
Upgrading from an older version
Older versions wrote hooks, permission rules and sandbox settings into .claude/settings.local.json, .codex/hooks.json, .codex/rules/shipcheck.rules, .cursor/hooks.json, .gemini/settings.json and .github/hooks/shipcheck.json. Run shipcheck install in each clone. It removes only the entries shipcheck wrote, keeps your own settings, and deletes a file only when nothing of yours is left in it. A file your team tracks in git is left alone with a note.
Check it
shipcheck doctor says whether each instruction file has the current block.