Getting started — git-span docs

git-span is a CLI. Day to day, it's your coding agent that runs it — declaring spans, checking git span drift, reconciling drift — while you review the results. Install the binary first, then install the plugin for whichever agent runtime you use.

Install the CLI

npm install -g git-span

Verify the install:

git span --version

git-span 1.1.30

The agent plugins don't install this binary — they call git span on PATH. Install the CLI first, on any machine or container an agent session runs in.

Install the Claude Code plugin

Inside a Claude Code session:

/plugin marketplace add goodfoot-io/git-span
/plugin install git-span@git-span

For a non-interactive or scripted install, use the claude CLI form instead:

claude plugin marketplace add goodfoot-io/git-span
claude plugin install git-span@git-span

This wires the workflow hooks, four skills (git-span, cover-commits, reconcile, and hook-effect-analysis), and an expert subagent — see Agent integration for what each piece does.

Install the Codex plugin

codex plugin marketplace add goodfoot-io/git-span
codex plugin add git-span@git-span

Installing the plugin does not trust its hooks. Codex is fail-closed here: hooks stay inert, and Codex prints a startup warning, until you explicitly review and trust them:

codex
/hooks

Launch codex and run /hooks to review the git-span hook definitions and trust them. Hash-stable hook filenames keep that trust decision valid across plugin upgrades, so re-trusting after every update isn't expected.

On Windows, hooks are disabled entirely — there's no partial fallback. --dangerously-bypass-hook-trust exists for CI or other one-off, non-interactive runs where a trust prompt can't be answered; avoid it for normal interactive use.

Install the OpenCode plugin

Add the npm package to the plugin array in your OpenCode config (opencode.jsonc or opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-git-span"]
}

An npm plugin can't contribute skills or agents, so the package ships an installer that materializes them on disk. Run it once per checkout — add --global to target your user-level directories (~/.config/opencode) instead of the project's .opencode/:

npx opencode-git-span install

Use npx opencode-git-span install --global instead to install the skills and expert agent under $XDG_CONFIG_HOME/opencode (or ~/.config/opencode). Re-run the installer after upgrading the npm package.

This wires the touch hook, four skills (git-span, cover-commits, reconcile, and hook-effect-analysis), and an expert subagent — see Agent integration for what each piece does.

Install the Antigravity plugin

From a git-span checkout:

agy plugin validate ./plugins-antigravity/git-span
agy plugin install ./plugins-antigravity/git-span

Or install the plugin directory directly from GitHub:

agy plugin install https://github.com/goodfoot-io/git-span.git/plugins-antigravity/git-span

Antigravity has no marketplace or separate hook-trust prompt. The plugin installs four skills and the workflow hooks; it does not install an expert subagent. Re-run the install after upgrading to refresh the installed copy under ~/.gemini/config/plugins/git-span/.

Verify

claude plugin list

codex plugin list

ls .opencode/skills

or, for a --global install,

ls ~/.config/opencode/skills

agy plugin list

should show git-span. Independently of any plugin, confirm the CLI itself is healthy:

git span doctor

Where to go next

Agent integration — what the plugin actually wires up: the touch hook, the skills, and the expert subagent.
Concepts — spans, anchors, drift, and the why, defined precisely.
Command reference — every subcommand, grouped by task.
Guides — task-shaped walkthroughs: reconciling drift, re-anchoring, mining history for span candidates.