setup-reference.md

ContextGuard setup reference

This file is generated from context-guard-kit/setup_wizard.py. Do not edit it manually. Regenerate it with python3 scripts/generate_setup_reference.py --write and verify it with --check.

Agent capability matrix

verified means ContextGuard has a bounded project write path. report-only means setup reports guidance and does not claim a verified write target. Only Claude Code currently has a verified user-scope write path; every user-scope write requires explicit agent selection and --yes.

Key	Agent	Project scope	User scope	Rules	Skill	MCP	Hooks	Notes
claude	Claude Code	verified	verified write	yes	—	—	yes	Installs project-local hooks, denies, and statusline in .claude/settings.json.
codex	OpenAI Codex CLI	verified	report-only	yes	yes	yes	—	Reads AGENTS.md and supports an optional project skill and project-scoped stdio MCP configuration.
gemini	Gemini CLI	verified	report-only	yes	—	yes	—	Reads GEMINI.md and supports project .gemini/settings.json MCP setup.
cursor	Cursor	verified	report-only	yes	—	yes	—	Reads project rules and supports project .cursor/mcp.json setup.
windsurf	Windsurf	verified	report-only	yes	—	—	—	Reads project rules; add an advisory ContextGuard block with --with-init.
cline	Cline	verified	report-only	yes	—	—	—	Reads project rules; add an advisory ContextGuard block with --with-init.
copilot	GitHub Copilot Coding Agent	verified	report-only	yes	—	yes	—	Reads repository instructions and supports project .vscode/mcp.json setup.
opencode	OpenCode	verified	report-only	—	yes	yes	—	Supports a project skill and project opencode.json MCP setup; no hooks are auto-written.
forgecode	ForgeCode	verified	report-only	—	—	yes	—	Supports project-local .mcp.json setup; other helpers remain shell-driven.
generic	Other / unknown agent	shell only	report-only	—	—	—	—	No automated setup surface; run ContextGuard helpers from the shell as needed.

Setup flags

--plan and --dry-run are read-only. Writes require --yes; user scope additionally requires explicit --agent or --only selection.

Flag	Default	Choices	Description
--root	—	—	project root to configure (default: nearest git root, else current directory)
--scope	project	project, user, global	setup scope: project-local by default; user/global targets only known user-level paths and requires explicit --agent for writes
--profile	recommended	minimal, recommended, max	which guardrails to enable: minimal (deny rules + Read guard), recommended (adds Bash trim/escrow and model defaults), max (adds the deprecated statusline and the failed-attempt nudge); individual --no-* flags still remove items
--yes	false	—	apply the recommended/selected setup without prompts
--plan	false	—	show the setup plan without writing files
--verify	false	—	run a read-only setup health check; never writes or prompts
--json	false	—	print machine-readable result
--rules-only	false	—	run an isolated rule-file operation without reading or changing settings/hooks
--narration-mode	—	quiet, default	with --rules-only, add quiet Claude narration guidance or restore default behavior
--no-backup	false	—	do not create .bak-* before modifying existing settings
--no-denies	false	—	skip recommended permissions.deny rules
--no-statusline	false	—	skip the token statusline (deprecated: it duplicates Claude Code /usage; only --profile max installs it)
--no-bash-hook	false	—	skip Bash trim/sanitize hook
--bash-reference-v1	false	—	opt in to 7-day scoped receipt references in the Bash hook; handles are provider-visible
--no-bash-reference-v1	false	—	disable/remove the optional Bash receipt-reference hook flag (default)
--no-read-guard	false	—	skip large Read guard hook
--no-model-defaults	false	—	skip model/effort defaults
--no-diet-scan	false	—	skip the read-only diet scan summary after applying setup
--allow-path-helper-fallback	false	—	allow trusted PATH helper resolution only after bundled/repo helpers are missing and identity validation passes
--agent	—	—	adapter key(s) to configure; comma-separated or repeatable. Alias for --only.
--only	—	—	restrict cross-agent setup/plan to adapter key(s); comma-separated or repeatable (e.g. --only codex,gemini). Default: claude plus any detected agents.
--with-init	false	—	also write advisory ContextGuard rule files for repo-rule agents (AGENTS.md, GEMINI.md, .cursorrules, etc.) when applying; safe and idempotent.
--with-skill	false	—	also generate optional project-local skill files where supported, currently Codex and OpenCode .agents/skills/context-guard/SKILL.md.
--with-mcp	false	—	also configure a verified project-scoped stdio MCP server for Codex, Gemini, Cursor, Copilot/VS Code, OpenCode, or ForgeCode.
--brief-mode	—	lite, standard, ultra, off	plan/apply advisory brief-mode snippets in project rule files; choose lite, standard, ultra, or off to remove.
--list-adapters	false	—	print the cross-agent adapter registry and exit
--failed-attempt-nudge	—	—	enable Bash terminal-event hooks that inject a one-line strategy-switch hint when the same command fails twice in a row (off by default; also enabled by --profile max)
--no-failed-attempt-nudge	—	—	skip the failed-attempt nudge hook even under --profile max