Install, configure, verify, troubleshoot, or operate the Gommage policy decision and audit harness for AI coding agents. Use when an agent is asked to set up Gommage, wire Claude Code or Codex hooks, install or manage the daemon, diagnose `gommage doctor` output, reason about Gommage policies/capability mappers/pictos/audit logs, evaluate release artifacts, or answer whether crates.io installation is supported.
Install, configure, verify, troubleshoot, or operate the Gommage policy decision and audit harness for AI coding agents. Use when an agent is asked to set up Gommage, wire Claude Code or Codex hooks, install or manage the daemon, diagnose `gommage doctor` output, reason about Gommage policies/capability mappers/pictos/audit logs, evaluate release artifacts, or answer whether crates.io installation is supported.
Gommage
Gommage is a beta policy-as-code harness for AI coding agent tool calls. It is
not an OS sandbox; keep the agent's native sandbox or permission layer enabled
unless the user explicitly chooses otherwise. For existing harnesses, treat
Gommage as a coexistence layer first: inspect dry-runs and status reports before
asking it to replace any host hooks.
The beta contract is explicit and evidence-driven. Read
docs/beta-contract.md before claiming beta readiness, and use
docs/beta-readiness.md as the launch gate. The existence of
gommage beta check means "run the beta gate"; it does not mean the current
host is healthy until the command returns pass or an understood, documented
warn.
Fast Path
Prefer the verified GitHub Release installer for users:
curl --proto '=https' --tlsv1.2 -sSf \
https://raw.githubusercontent.com/Arakiss/gommage/main/scripts/install.sh | sh
To install binaries plus this agent skill for Codex and Claude Code:
curl --proto '=https' --tlsv1.2 -sSf \
https://raw.githubusercontent.com/Arakiss/gommage/main/scripts/install.sh \
| sh -s -- --with-skill --skill-agent codex --skill-agent claude
To install or update only this skill:
curl --proto '=https' --tlsv1.2 -sSf \
https://raw.githubusercontent.com/Arakiss/gommage/main/scripts/install.sh \
| sh -s -- --skill-only --skill-agent codex --skill-agent claude --no-prompt
Set up the target agent. On mature dotfiles or existing hook stacks, inspect
the harness report and dry-run before applying quickstart:
# `--self-test` is the default; keep it explicit in scripts for readability.
gommage harness diagnose --json
gommage quickstart --agent claude --daemon --dry-run --json
gommage quickstart --agent claude --daemon --dry-run --explain
gommage quickstart --agent claude --daemon --self-test
gommage quickstart --agent codex --daemon --dry-run --json
gommage quickstart --agent codex --daemon --self-test
Verify:
gommage doctor
gommage tui --snapshot --view all
gommage tui --snapshot --view onboarding
gommage tui --snapshot --view approvals
gommage tui --snapshot --view metrics
gommage tui --watch --watch-ticks 2 --view approvals
gommage tui --stream --stream-ticks 1 --stream-limit 8
gommage beta check --json
gommage verify --json
gommage posture --json
gommage session doctor --json
gommage managed status --json
gommage run codex --dry-run --json -- "<task>"
gommage doctor --json
gommage smoke --json
gommage stats --json
sh scripts/launch-demo.sh
gommage report bundle --redact --output gommage-report.json
# Optional, when the repository includes policy fixtures.
gommage beta check --json --policy-test path/to/policy-fixtures.yaml
gommage verify --json --policy-test path/to/policy-fixtures.yaml
Treat beta check --json as the host-level beta gate. It aggregates doctor,
smoke, agent status, optional policy fixtures, state-index readiness, dashboard
availability, and actionable next steps. status: "fail" means the host should
not be used for trusted hook decisions yet; warn is acceptable only when the
warning is understood and documented in the beta feedback.
Treat verify --json status as:
pass: doctor, built-in smoke checks, and requested policy fixtures passed.
warn: operable, commonly before the first audit entry or without a daemon socket.
fail: do not trust the hook path until fixed.
On a fresh machine, verify --json includes a top-level hint and reports
smoke.status: "skip" when doctor already failed. Follow the hint before
debugging policy semantics.
Treat lower-level doctor --json status as:
ok: healthy.
warn: operable, commonly before the first audit entry or without a daemon socket.
fail: do not trust the hook path until fixed.
Treat smoke --json status as:
pass: active mapper + policy semantics match the built-in harness fixtures.
fail: do not trust the hook path until the unexpected decision is understood.
Use gommage verify --json --policy-test <file> when the repository provides
its own policy fixtures. Treat status: "fail" as a policy regression until
the policy or capability mapper change is reviewed.
GitHub Releases remain the recommended end-user install path because they
provide signed, checksum-verified, prebuilt binaries and install all runtime
binaries together. crates.io is supported for users who intentionally want
Cargo to build from source.
Agent Notes
Agent skill install destinations:
Codex: ${CODEX_HOME:-$HOME/.codex}/skills/gommage
Claude Code: ${CLAUDE_HOME:-$HOME/.claude}/skills/gommage
The canonical command contract is
docs/agent-command-manifest.json; CI executes it via
scripts/check-agent-command-contracts.sh.
Host validation evidence should use scripts/host-smoke.sh; CachyOS and
other systemd hosts should pass --daemon-manager systemd.
The shortest local proof path is sh scripts/launch-demo.sh. It uses an
isolated temporary home and captures quickstart dry-run, ask_picto,
one-use picto allow, hard-stop deny, signed audit verification,
state.sqlite rebuild/verify/stats, policy fixtures, beta check, and a TUI
snapshot without mutating the operator's real agent config.
Agent automation should prefer gommage harness diagnose --json, gommage harness explain --json, gommage harness write-context --dry-run, gommage quickstart --dry-run --json, gommage quickstart --dry-run --explain, gommage beta check --json, gommage beta check --json --policy-test <file>, gommage verify --json, gommage verify --json --policy-test <file>, gommage posture --json, gommage session doctor --json, gommage managed status --json, gommage run codex --dry-run --json -- <task>, gommage project init --dry-run --json, gommage report bundle --redact --output <file>, gommage doctor --json, gommage agent status claude --json, gommage agent status codex --json, gommage approval list --json, gommage approval list --status all --json, gommage approval deny-stale --older-than 24h --json, gommage approval show <id> --json, gommage approval replay <id> --json, gommage approval evidence <id> --redact, gommage approval webhook --dry-run --json, gommage approval callback --body <file> --signature <sig> --timestamp <ts> --signing-secret <secret> --dry-run --json, , , , , , , , , , , , , , , , , , , , , , and JSON. is a rebuildable read-model only; never treat it as permission authority over , policies, or pictos. defaults to pending; use for history. is a dry-run by default; use only when deliberately appending denied resolutions for stale pending requests. exposes shaped request bodies in ; signed dry-runs also expose , , and a request-bound . verifies the HMAC signature, timestamp freshness, pending request state, and nonce before applying an approve/deny action. is advisory only and is not OS confinement. Use , especially for first-minute operator guidance and for a human-readable local health summary, bounded , or bounded only when a human-readable operator report is useful; do not parse TUI output as a stable contract. Stream/snapshot output includes daemon reachability, active pictos, local counters, webhook DLQ count, and audit anomaly count when available. Use only for manual forensic review. Do not parse , , or interactive ; they are presentation-only. Interactive may adjust TTL/use-count and approve/deny after y/n confirmation, so agents should not drive it programmatically.
Policies live in ~/.gommage/policy.d/; capability mappers live in ~/.gommage/capabilities.d/. Keep policies and policy test fixtures reviewed and versioned. Use gommage map --json to inspect raw mapper output before writing rules; add --hook when stdin is the real PreToolUse payload. Use policy schema before generating or editing fixture YAML, then use policy snapshot or policy snapshot --hook to capture a real tool call as a starter fixture and review the generated expected decision before committing it. Use policy suggest --audit <file> --json only as advisory authoring input: it never mutates active policy and generated fixture drafts are not usable until raw input is captured. Gommage is fail-closed when no rule matches.
Publishing And Releases
Current beta distribution:
GitHub Releases provide one platform archive that contains the prebuilt
gommage, gommage-daemon, and gommage-mcp binaries. The installer copies
all three into the selected bin directory.
The installer verifies Sigstore bundle identity and SHA-256 before extracting.
~/.gommage/state.sqlite is a local SQLite read-model for fast TUI metrics
and stream fallback. Rebuild with gommage state rebuild; verify with
gommage state verify --json. The signed audit.log remains authoritative.
Installing the gommage-mcp binary does not auto-register a universal MCP
gateway. New agent hooks invoke gommage hook --agent <host> after quickstart;
gommage-mcp remains explicit per stdio MCP server with
gommage-mcp --gateway --server-name <name> -- <stdio-mcp-server>.
Use gommage release verify --all-assets --json --require-sbom --require-provenance for full beta/RC release evidence. For current-platform checks, use gommage release verify --json --require-sbom --require-provenance; from a checkout, sh scripts/verify-release.sh --json --require-sbom --require-provenance provides the shell fallback.
The installer can also install/update this skill with --with-skill or --skill-only.
gommage mascot / gommage logo prints the Gommage Gestral terminal logo. Use --plain or NO_COLOR=1 for script-safe output.
crates.io is supported for Rust-native source builds; GitHub Releases remain
the signed binary install path.
Before claiming a newly published version, check docs/publishing.md and
require the package gates there to pass.
References
Read only the docs needed for the task:
README.md: status, install, quickstart, roadmap.
docs/existing-setups.md: migration, coexistence with existing hooks,
dual-agent flows, MCP scope, and rollback.
Prefer gommage audit-verify --explain --json for new automation; bare --explain remains JSON for compatibility. Human approval deny-stale output is summarized by default; use --show-all or --verbose only when a person needs every matched request printed in the terminal.
Existing host setups: quickstart preserves unrelated host hooks by default.
Use --replace-hooks only when the operator intentionally wants Gommage to
own the whole PreToolUse surface. Existing hooks can coexist, but the first
layer to block determines what the agent sees; if another hook blocks before
Gommage, Gommage cannot audit that decision.
Agent-readable context: gommage harness diagnose --json is the canonical
preinstall/local truth source for host hooks, native permission imports,
coverage boundaries, and next commands. After real quickstart, Gommage writes
$GOMMAGE_HOME/AGENT_CONTEXT.md and
$GOMMAGE_HOME/integration-report.json; future agent sessions should read
these files or call gommage harness explain before making coverage claims.
Claude Code: quickstart --agent claude installs the PreToolUse hook,
imports supported permissions.deny entries into 05-claude-import.yaml,
and imports supported permissions.allow entries into
90-claude-allow-import.yaml. Supported broad allow entries such as Bash
are imported as late allow rules, so earlier hard-stops, denies, ask rules,
and native deny imports still win. Use --no-import-native-permissions when
the operator wants to author the initial Gommage policy manually.
Codex CLI: quickstart --agent codex enables hooks and installs a Gommage
matcher for Bash, apply_patch, and Codex MCP tool names. apply_patch
payloads are mapped to parsed filesystem write paths and fail closed when
they cannot be parsed safely. Keep Codex sandboxing enabled because hooks do
not intercept every shell path or non-shell, non-MCP tool call.
Dual-agent flows: if Claude launches Codex via tmux, shell, or script,
Gommage sees the outer Claude Bash call only. Inner Codex calls are governed
only when the invoked Codex session uses a CODEX_HOME with Gommage's Codex
hook installed and the tool call falls inside Gommage's mapped hook surface.
Prefer a shared GOMMAGE_HOME or deliberate org/project policy layer, then
run both gommage agent status claude --json and
gommage agent status codex --json before the handoff.
Hook adapter: new quickstart installs call gommage hook --agent claude or gommage hook --agent codex; older gommage-mcp, gommage mcp, and unqualified gommage hook commands are compatibility surfaces.
MCP gateway: use gommage-mcp --gateway --server-name <name> -- <stdio-mcp-server> only for stdio MCP servers you intentionally proxy. This is optional compatibility plumbing, not the canonical Gommage operation path. Allowed tools/call requests are forwarded; denied or picto-required calls return MCP tool errors and are not sent upstream.
Daemon: --daemon installs and starts the user-level service. Use --daemon-no-start for CI/image builds that should write service files without starting them.
Quickstart self-test: the readiness gate runs by default. --self-test remains accepted for scripts; --no-self-test is the manual escape hatch.
Backups: Gommage writes .gommage-bak-<timestamp> backups before replacing agent configs, generated policy imports, daemon service files, installed binaries, or installed skill files when content changes. Unchanged files are not backed up.
Recovery: use gommage repair agent claude --dry-run or gommage repair agent codex --dry-run first for old/broken alpha hooks; repair rewrites Gommage-owned hook groups to the current scoped hook while preserving unrelated hooks. Use gommage agent uninstall claude --restore-backup, gommage agent uninstall codex --restore-backup, or gommage uninstall --all --dry-run before destructive cleanup. --purge-home requires --yes; --purge-backups removes Gommage-created .gommage-bak-* files only when a clean slate is intentional.
Break-glass: GOMMAGE_BYPASS=1 is a policy bypass, not a hard-stop bypass. Valid hook payloads are still mapped and compiled hard-stops still deny; when a usable home/key exists, bypass writes a signed bypass_activated audit event. Use only to recover a broken hook path.
Exact-input approvals: bind_input: true is valid only with decision: ask_picto. It makes approval mint a picto tied to the canonical observed tool input as well as scope. Direct gommage grant --scope … remains scope-only; approve the pending request from an input-bound rule when the exact call matters.
Hard-stop scope for rm -rf: this is any-absolute-path, not root-only. Despite the hs.rm-rf-root id and the rm -rf /* glob, rm -rf of any argument beginning with / is denied (e.g. /tmp/scratch, /home/me/build), because the glob * crosses / and a shell-semantic scanner independently flags rm with r+f flags plus a /-leading argument (also through bash -c, sudo/env prefixes, ;/&&, and $(...)). Relative paths (./build, node_modules) are deliberately out of scope — gate those at the policy layer. To clear an absolute scratch dir, cd into its parent and delete by relative name rather than forcing the gate; there is no picto for a hard-stop. See THREAT_MODEL.md for the rationale (intentional blast-radius containment).
