compass is configuration for AI coding agents (Claude Code + Codex): hooks, subagents, commands, skills, MCP/LSP wiring, and an installer. It ships shell scripts that run on your machine and a PreToolUse guardrail.

The guardrail hooks reduce footguns; they are not a security boundary. They stop common accidents (secret writes, secrets pasted into file content, rm -rf /, curl|sh, force-push to main), not a determined attacker or a cleverly-phrased command. Keep using least-privilege credentials and review diffs. When you need an actual boundary — running untrusted code, a downloaded build, an agent executing a script you didn't write — use compass sandbox -- <cmd>: a real OS sandbox (bwrap / firejail / macOS sandbox-exec) with no network and writes confined to cwd + temp. It refuses rather than run unconfined if no backend is available (no fake sandboxing).

Secret scanning has two layers. The protect-paths write-hook blocks an agent from writing a recognizable live credential (Anthropic/OpenAI/AWS/GitHub/GCP/Slack/ Stripe… formats) into a file. compass scan [--staged|--all] is the commit-boundary companion — run it in a pre-commit hook or CI; its built-in detectors are the deterministic gate and it uses gitleaks for extra depth when installed. Both honor an allowlist secret marker on a line for deliberate placeholders/fixtures.

compass itself phones home to nothing. Network calls happen only through tools you enable:

No telemetry. The compass-memory MCP is local-only (SQLite over stdio, no network). compass modifies shared files only by symlinking config into ~/.claude, ~/.codex, and (with --gemini) ~/.gemini, plus a compass CLI symlink in ~/.local/bin and — if that dir isn't on your PATH — one marker-tagged export PATH line appended to your shell rc (all backed up; make uninstall reverts every one, including the PATH line). No feature uses --dangerously-skip-permissions.

Every blocked/gated action is appended to ${COMPASS_HOME:-~/.compass}/audit.jsonl (one JSON object per line: ts · decision · tool · repo · rule · redacted detail). Read it with compass audit-log (table, --since, or --json for SIEM export). Details are redacted reasons — never the raw secret or payload.

• MCP servers are version-pinned (never @latest); scripts/check-mcp.sh enforces pins + manifest integrity in setup-mcp pre-flight, doctor, and CI, so a compromised upstream release isn't auto-pulled.
• Releases carry provenance. Every v* tag triggers release-sign.yml, which emits a keyless SLSA build-provenance attestation for the source tarball. Verify any download with compass verify [vX.Y.Z] (or gh attestation verify <tarball> --repo dshakes/compass). The Homebrew formula additionally pins the tarball sha256.

Please report security issues privately — do not open a public issue.

• Use GitHub's Report a vulnerability (Security → Advisories), or
• Email chandu1221@gmail.com with details and a reproduction.

You'll get an acknowledgment within a few days. Once a fix ships, we'll credit you (unless you prefer to remain anonymous).

• Read the hooks and scripts before make install — that's why they're short.
• Never put secrets in CLAUDE.md/AGENTS.md; use ${ENV} refs for MCP servers.
• Point database MCP servers at a read-only role or replica.
• Pin the marketplace to a tag (not main) for team rollouts.