---
description: "Install the git-span CLI, then wire it into Claude Code, OpenAI Codex, or OpenCode."
---

# Getting started (/docs/getting-started)

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

```bash
npm install -g git-span
```

Verify the install:

```bash
git span --version
```

```txt
git-span 1.1.19
```

> [!NOTE]
> 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
```

> [!NOTE]
> For a non-interactive or scripted install, use the `claude` CLI form instead:
>
> ```bash
> 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](/docs/agent-integration) for what each piece does.

## Install the Codex plugin

```bash
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:

```bash
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.

> [!WARNING]
> 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`):

```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/`:

```bash
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](/docs/agent-integration) for what each piece does.

## Verify

```bash
claude plugin list
```

or

```bash
codex plugin list
```

or

```bash
ls .opencode/skills
```

or, for a `--global` install,

```bash
ls ~/.config/opencode/skills
```

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

```bash
git span doctor
```

## Where to go next

* [Agent integration](/docs/agent-integration) — what the plugin actually wires up: the touch hook, the commit advisor, the skills, and the expert subagent.
* [Concepts](/docs/concepts) — spans, anchors, drift, and the why, defined precisely.
* [Command reference](/docs/commands) — every subcommand, grouped by task.
* [Guides](/docs/guides/reconcile-drifted-spans) — task-shaped walkthroughs: reconciling drift, re-anchoring, mining history for span candidates.