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.19

The Claude Code, Codex, and OpenCode 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, three skills (git-span, 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 --global

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

Verify

claude plugin list

codex plugin list

ls .opencode/skills

or, for a --global install,

ls ~/.config/opencode/skills

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 commit advisor, 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.