Quickstart

I Choose one installation route

Universal CLI

Install persistently from the public Git repository:

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

pipx users can install the same source:

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:

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:

/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

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.

$ 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:

gate unregister

Plugin users uninstall from Claude Code:

/plugin uninstall my-gate@my-gate