# Quickstart

## `I` Choose one installation route

### Universal CLI

Install persistently from the public Git repository:

```sh
uv tool install git+https://gitlab.com/doering-ai/apps/gate.git
gate register
gate doctor
```

`pipx` users can install the same source:

```sh
pipx install git+https://gitlab.com/doering-ai/apps/gate.git
gate register
gate doctor
```

The default registration targets Claude Code user settings. Register the separate Codex
pre-flight hook for the native spawn_agent fan-out boundary:

```sh
gate register --harness codex
gate doctor --harness codex
gate status --harness codex
```

Restart Codex after changing hooks configuration. Codex receives the pre-flight deny on
spawn_agent; Claude alone has the start/stop notification layers.

### Claude Code plugin

Run these commands inside Claude Code:

```text
/plugin marketplace add https://gitlab.com/doering-ai/apps/gate.git
/plugin install my-gate@my-gate
/reload-plugins
/plugin
```

Use the plugin manager's **Installed** and **Errors** tabs to inspect plugin state.
Do not also run `register`: duplicate hooks double notifications and can consume a one-off
grant without allowing the launch.

## `II` Verify the CLI route

```sh
gate doctor
gate status
```

`doctor` checks Python, configuration syntax, the hook script, a desktop notifier, Claude Code
settings JSON, and the grants store.
A healthy persistent CLI install ends with `0 failure(s).`.
`status` reports settings-file registrations; Claude marketplace plugins remain visible in
Claude Code's plugin manager instead.

## `III` See the decision path work

`selftest` feeds synthetic hook payloads through the real gate logic.
It launches no agents and suppresses desktop notifications.

```console
$ gate selftest
[ok] unpinned workflow under heavy session denied
[ok] fully light-pinned workflow allowed
[ok] explicit heavy pin denied even under light session
[ok] unpinned workflow under light session allowed
[ok] explicit heavy Agent override denied
[ok] inherited Codex sol spawn denied
[ok] garbage payload ignored
[ok] grant honored (heavy Agent allowed)
[ok] grant exhausted (heavy Agent denied)
[ok] expired grant ignored (heavy Agent denied)
[ok] unwritable store fails closed (denied)

0 failure(s).
```

The examples in package docstrings also run as part of the test suite, so behavior changes
cannot silently leave them stale.

## `IV` What happens at launch time

| Situation | Outcome |
| --- | --- |
| Explicit opus, fable, or sol nested-agent pin | Denied before launch |
| Inherited Codex spawn_agent under gpt-5.6-sol | Denied before launch |
| Unpinned Claude workflow under a resolvable superheavy session | Denied before fan-out |
| Explicit sonnet, haiku, terra, or luna pin | Allowed |
| Allowlisted or one-off-granted launch | Allowed and normally notified |
| Launch visible only after it starts | Start notification, then stop-time ground truth |

To remove settings-file registrations:

```sh
gate unregister
```

Plugin users uninstall from Claude Code:

```text
/plugin uninstall my-gate@my-gate
```