Skip to main content

What SSG changes on your machine

When you run ssg init (CLI), open the desktop wizard, or click through the web setup flow, SSG modifies a small, predictable set of files. This page documents every single one so you know exactly what landed on your disk before, during, and after onboarding.

The same information is available three other ways:

  • Before install (CLI): ssg init --dry-run — colourised preview with per-file diff hunks, no writes.
  • Before install (Desktop): the wizard's "Transparency" step renders the same preview, line-for-line, by shelling out to the CLI.
  • After install (any platform): ssg whatchanged — re-reads the append-only .sigmashake/install-manifest.json and prints the full audit log of everything SSG has ever touched in this project. Pass --verbose for the full diff per entry, --json for machine output.

If anything on this page surprises you, open an issue.

The install manifest — your auditable receipt​

The single most important file for transparency:

.sigmashake/install-manifest.json

Created the first time ssg init writes to this project. Append-only. Records:

  • ISO-8601 timestamp of every change
  • Which SSG version made the change
  • Which subsystem requested it (core, claude-code, cursor, …)
  • The full line-level diff (before / after / context) — so even after the file gets edited further, the manifest preserves what SSG itself did

This file is the truth source for ssg whatchanged and, eventually, the one-shot ssg init --rollback command. You can read it, search it, and commit it to your repo — it's deterministic JSON, never includes secrets.

Core files (always written by ssg init)​

These five files are written regardless of which AI adapter you choose:

PathKindPurposeHow to undo
.sigmashake/config.tomlcreateTop-level config (dashboard port, eval timeout, per-agent toggles).Remove the file.
.sigmashake/rules/security.rulescreateStarter ruleset: blocks destructive shell ops, force-push, secret-file reads.Remove the file.
.sigmashake/presets/minimal.rulescreateBare-minimum guardrails preset (not active by default).Remove the file.
.sigmashake/presets/strict.rulescreateStrict preset with deploy-approval gate (not active by default).Remove the file.
.gitignoremodifyAppends .sigmashake/rules/autopilot.rules so auto-generated rules don't get committed.Open .gitignore and remove that one line.

Every file above is plain text. Nothing is encrypted, obfuscated, or generated from a remote source — what ssg init --dry-run shows you is what gets written.

Per-adapter changes​

Adapters are the integration glue between SSG and the AI agent you actually use day-to-day. Each one writes a different small set of files:

claude-code​

SSG writes to your global ~/.claude/settings.json by default (so every Claude Code session is governed regardless of which directory you open). Pass --project-only to scope the write to the current project's .claude/settings.json instead.

  • ~/.claude/settings.json (global install, default) or .claude/settings.json (project install with --project-only) — upserts eight hook entries:

    • PreToolUse → ssg hook eval (the enforcement gate)
    • PostToolUse → ssg hook post-eval (audit)
    • UserPromptSubmit → ssg hook health
    • SessionStart → ssg hook session-start
    • PreCompact → ssg hook pre-compact
    • SessionEnd → ssg hook session-end
    • Stop → ssg hook stop
    • SubagentStop → ssg hook subagent-stop

    Also merges a curated permissions.allow / permissions.deny list and sets permissions.defaultMode when not already present. Pre-existing keys are preserved; SSG never removes non-SSG entries.

Undo: open the file and remove the SSG hook entries and permission additions, or run ssg init --client=claude-code --uninstall.

cursor​

  • .cursor/mcp.json — upserts the ssg-governance MCP server entry (merges into an existing file, never overwrites unrelated entries).
  • .cursor/rules/ssg-governance.mdc — Cursor MDC rule that wires the governance prompt into Cursor's rule pane (alwaysApply).
  • .cursor/hooks.json — Cursor 1.7+ native lifecycle hooks: beforeShellExecution, beforeMCPExecution, and post-execution audit hooks pointing at ssg hook cursor. failClosed: true so a stopped daemon denies rather than silently allows. Ignored by Cursor builds older than 1.7.
  • .cursor/sandbox.json — written only when SSG_CURSOR_NETWORK_SANDBOX=1 is set at install time; adds deny-by-default network egress. Not written in a default install.

Undo: remove those files; restart Cursor.

copilot​

  • .vscode/mcp.json — upserts the ssg-governance MCP server (merges; VS Code Copilot Chat uses this file in recent releases).
  • .github/copilot-instructions.md — appends the SSG governance block (idempotent; skipped if already present).
  • ~/.copilot/hooks/ssg-governance.json — Copilot CLI native lifecycle hooks (preToolUse + postToolUse) pointing at ssg hook copilot. Dedicated SSG-owned file; user hook files in the same directory are untouched. Older Copilot CLI builds without the hooks system ignore it.

Undo: open each file and remove the SSG-tagged blocks; remove the hooks JSON file.

codex​

  • ~/.codex/config.toml — upserts a [mcp_servers.ssg-governance] TOML block (user-global Codex config). Absolute binary path baked in at install time so the MCP server resolves without requiring ssg on PATH in non-interactive shells.
  • .codex/mcp.json — project-level MCP config (committed with the repo, portable npx command so it works on every OS/clone).
  • ~/.sigmashake/hooks/bin/bash — shared shell wrapper (mode 0755). Set SHELL to this path when starting Codex to intercept bash invocations.

Undo: remove the MCP server block from ~/.codex/config.toml; remove .codex/mcp.json; remove the shell wrapper.

codex-desktop​

The Codex Desktop app shares ~/.codex/config.toml with the Codex CLI. No shell wrapper is installed — governance is delivered entirely via MCP.

  • ~/.codex/config.toml — upserts [mcp_servers.ssg-governance] (same structure as the codex adapter above).
  • .codex/mcp.json — project-level portable MCP config (same as codex).

Any legacy [[hooks]] array-of-tables block left by older SSG releases is automatically stripped because it causes codex-cli >= 0.134.0 to refuse to load the config.

Undo: remove the MCP server block from ~/.codex/config.toml; remove .codex/mcp.json.

pi​

  • ~/.pi/mcp.json — upserts ssg-governance MCP server entry (merges; creates the file and ~/.pi/ directory if absent). When aider is on PATH, also registers a ssg-coder MCP entry that exposes aider edit/ask tools to Pi.
  • ~/.sigmashake/hooks/bin/bash — shared shell wrapper (mode 0755).
  • ~/.sigmashake/hooks/hooks/ssg-node-hook.cjs — Node.js Pi hook (mode 0755).
  • ~/.sigmashake/hooks/hooks/python/sitecustomize.py — Python Pi hook (mode 0644).

Undo: remove the four files above; remove the ssg-governance entry from ~/.pi/mcp.json.

gemini (Gemini CLI)​

All files are written inside the project directory, not ~/.gemini.

  • .gemini/settings.json — upserts the ssg-governance MCP server entry (merges; creates the file if absent).
  • .gemini/GEMINI.md (project root) — appends the SSG governance block between <!-- SSG_GOVERNANCE_START --> / <!-- SSG_GOVERNANCE_END --> markers; creates the file if absent.
  • .gemini/policies/ssg-governance.toml — native Gemini CLI policy file (TOML format); transpiled from your current .rules if any are loaded, otherwise a static baseline.
  • ~/.sigmashake/hooks/bin/bash — shared shell wrapper (mode 0755).

Undo: remove the SSG sections from each file; remove the shell wrapper.

antigravity​

One client ID covers Antigravity CLI (agy), Antigravity 2.0 Desktop, and the Antigravity IDE — all three share the same customization system and governance layers.

  • .agents/hooks.json (project root) — merges a single named key, ssg-governance, into Antigravity's native PreToolUse lifecycle hook (JSON-merge only; any other named hooks already in the file, yours or a plugin's, are preserved untouched). The hook command is a fixed, quoted, absolute path to the ssg binary — tool-call context arrives over stdin, never interpolated into the command line. Internal errors, malformed input, or an internal ~20s timeout (ahead of Antigravity's own 30s hook timeout) fail closed to deny, never a bare ask.
  • ~/.gemini/config/mcp_config.json — the unified global MCP config Antigravity now reads for all three surfaces (superseding the old per-product ~/.gemini/antigravity/mcp_config.json / %APPDATA%\Google\Antigravity\mcp_config.json path). Written unconditionally (the directory is created if absent) and JSON-merged under the ssg-governance key — other registered MCP servers are left alone.
  • .sigmashake/antigravity-rules.md (project root) — generated governance rules document for pasting into Antigravity's user rules config.
  • ~/.sigmashake/hooks/bin/bash — shared shell wrapper (mode 0755).
  • ~/.sigmashake/hooks/hooks/ssg-node-hook.cjs — Node.js runtime hook (mode 0755).
  • ~/.sigmashake/hooks/hooks/python/sitecustomize.py — Python runtime hook (mode 0644).
  • ~/.sigmashake/hooks/hooks/src/libssg.c and ssg-seccomp.c — C source files for the OS-level interposer (kept as an additional, unchanged defense-in-depth layer alongside the native hooks.json above). On Linux/macOS with gcc installed, also compiled to ~/.sigmashake/hooks/hooks/libssg.so (Linux) / libssg.dylib (macOS) and ~/.sigmashake/hooks/bin/ssg-seccomp. Compilation is skipped on Windows.

Undo: remove the ssg-governance key from .agents/hooks.json and ~/.gemini/config/mcp_config.json (other keys are left intact), remove the SSG-tagged sections, and remove the runtime hook files.

aider​

  • .aider.conf.yml (project root) — created only when the file does not already exist; adds lint-cmd: ["ssg check ."] and auto-lint: true so every edit cycle runs an SSG scan. An existing file is left untouched.
  • ~/.sigmashake/hooks/bin/bash — shared shell wrapper (mode 0755).
  • ~/.sigmashake/hooks/hooks/ssg-node-hook.cjs — Node.js runtime hook (mode 0755).
  • ~/.sigmashake/hooks/hooks/python/sitecustomize.py — Python runtime hook (mode 0644).

Undo: remove the SSG-tagged section from .aider.conf.yml; remove the three hook files.

opencode​

Three governance layers are written to the project directory.

  • opencode.json (project root) — upserts an mcp.ssg-governance entry and a permission block (merges into an existing file; SSG tracks which permission keys it authored via an internal sentinel so uninstall is safe).
  • .opencode/plugins/ssg-governance.js — in-process OpenCode plugin that calls ssg hook opencode via tool.execute.before (enforce) and tool.execute.after (audit). Note: does not fire inside task-spawned subagents (opencode#5894).
  • AGENTS.md (project root) — appends the SSG governance block between <!-- ssg:governance --> / <!-- /ssg:governance --> markers; creates the file if absent. OpenCode auto-loads this file.

Undo: remove both files; restart OpenCode.

replit​

Replit runs in the cloud — no local files outside the project directory are touched. The adapter writes:

  • replit.md (project root) — appended with the SSG governance block between <!-- SSG_GOVERNANCE_START --> / <!-- SSG_GOVERNANCE_END --> markers (so Replit Agent knows about the governance contract).
  • .sigmashake/replit-install.url — the pre-encoded one-click MCP install URL.
  • .sigmashake/replit-install.md — a markdown badge snippet you can paste into a README.

Undo: remove the SSG-tagged section from replit.md; remove the two helper files.

nemoclaw (NVIDIA NemoClaw)​

  • ~/.nemoclaw/policies/ssg-governance.yaml — governance policy fragment in NemoClaw's declarative YAML format; merged into every sandbox the host launches. Covers filesystem writable/readonly/deny paths, network egress allowlist, and privileged syscall denials.
  • ~/.sigmashake/hooks/bin/bash — shared shell wrapper (mode 0755) for defence-in-depth on host-side bash invocations outside the sandbox boundary. Kernel-level Landlock/seccomp inside the sandbox enforces the YAML policy directly.

Undo: delete ~/.nemoclaw/policies/ssg-governance.yaml; remove the shell wrapper.

claude-cowork​

Claude Cowork (the Claude Desktop desktop-agent with computer-use) does not yet expose a public PreToolUse hook API, so governance is delivered via MCP and a prompt file.

  • CLAUDE_COWORK.md (project root) — governance prompt between <!-- SSG_GOVERNANCE_START --> / <!-- SSG_GOVERNANCE_END --> markers; instructs Cowork to call ssg_evaluate before each tool call.
  • ~/.claude/mcp.json — upserts the ssg-governance MCP server entry (user-scoped Claude Desktop MCP config; merges; creates the file if absent).

Undo: remove the SSG governance block from CLAUDE_COWORK.md; remove the ssg-governance entry from ~/.claude/mcp.json.

generic​

The fallback when no AI agent is detected and no --client is passed. Touches no files outside .sigmashake/ — it just creates the rules directory and prints wire-format instructions on stdout.

Optional, opt-out only​

These run by default but are easy to skip:

Smart Hub ruleset pull​

After scaffolding, ssg init runs a stack-detection pass and downloads Hub rulesets that match the languages/frameworks it finds (TypeScript, Python, Terraform, etc.). Each ruleset lands in .sigmashake/rules/.

Skip: pass --no-smart.

Daemon auto-start​

ssg init registers the local SSG daemon to launch on login:

  • macOS — ~/Library/LaunchAgents/com.sigmashake.daemon.plist
  • Linux — ~/.config/systemd/user/sigmashake-daemon.service
  • Windows — Task Scheduler entry

The daemon binds only to 127.0.0.1 — it is never exposed externally.

Skip: pass --no-autostart, or remove later with ssg autostart disable.

"Wait, what about my home directory?"​

The only files SSG writes outside the current project are:

  1. ~/.sigmashake/ — local SQLite audit DB, license JWT, agent toggles, shared shell wrapper, plus runtime hooks (see per-adapter table).
  2. ~/.<agent>/ — the agent's own config file (Codex/Codex Desktop use ~/.codex/config.toml; Pi uses ~/.pi/mcp.json; Gemini CLI, Antigravity, NemoClaw each use paths under ~/.gemini/ or ~/.nemoclaw/; Claude Code and Claude Cowork use ~/.claude/; Copilot CLI uses ~/.copilot/hooks/; Cursor, Copilot Chat, and OpenCode are project-local only).
  3. ~/Library/LaunchAgents/ (macOS) / ~/.config/systemd/user/ (Linux) / Task Scheduler (Windows) — daemon auto-start, opt-out via --no-autostart.

Nothing is ever written to system paths (/etc/, /usr/, C:\Windows\) or to other users' home directories.

Shared shell wrapper​

Several adapters (Codex, Pi, Gemini, Antigravity, Aider, NemoClaw) install the same shell wrapper at ~/.sigmashake/hooks/bin/bash. This is a single user-scoped install, not per-project. The wrapper intercepts bash -c "cmd" calls by acting as a POSIX shell that pipes each command through ssg hook eval before executing it. Set SHELL=~/.sigmashake/hooks/bin/bash when starting the agent to engage it.

Verify any of this​

# Show the plan before running anything:
ssg init --dry-run

# Show the same plan as JSON (for tools, scripts, audits):
ssg init --json --dry-run

# After installing, re-read the audit log:
ssg whatchanged

# With full line-level diffs:
ssg whatchanged --verbose

# As JSON for ingestion into your own audit pipeline:
ssg whatchanged --json

The exact same JSON shape is consumed by the desktop wizard's Transparency step — the CLI and the GUI cannot show you different things about what's about to happen.