Claude Code Permissions: Securing .env Files, Git, and Dangerous Shell Commands

When configuring Claude Code on production repositories, developers often encounter a frustrating trade-off: either constantly confirm trivial read commands, or enable full bypass mode (--dangerously-skip-permissions) and risk accidental .env leaks, unintended git push --force executions, or broken project dependencies.

Neither extreme is effective. To troubleshoot permission errors and establish safe AI coding practices, build your setup on the principle of least privilege: clearly delineating read access, write permissions, shell execution boundaries, and version control operations.

---

1. The 4-Tier Permission Map

Organize tools and commands into four distinct access tiers to fix security vulnerabilities:

Tier	Operations	Default Policy	Examples
1. Code Inspection	Reading workspace files	In Manual mode, usually no prompt inside the working directory; depends on mode and managed settings	cat, grep, viewing source files in src/
2. Secrets & Config	Accessing .env, keys, tokens	Explicit Read deny plus sandbox and credential isolation	.env*, id_rsa, *.pem, credentials.json
3. File Edits	Modifying and authoring code	Manual mode requires approval; organizational rules may be stricter	Edits inside the dedicated workspace
4. Dangerous Shell & Git	Package managers, destructive operations	Explicit deny or one-time manual approval in an isolated environment	rm -rf, git push --force, npm publish, DROP TABLE

---

2. Isolating .env Files and Project Secrets

Transport Layer Security (TLS) encrypts API traffic over the wire, but it does not prevent confidential credentials from entering the model context window, error logs, or handoff summaries.

To troubleshoot and ensure Claude Code does not ingest private credentials, apply these fixes:

1. Add all environment files containing secrets to .gitignore.
2. Provide a clean .env.example template with dummy values so the agent understands variable names without seeing runtime secrets.
3. Add a strict boundary rule to CLAUDE.md or AGENTS.md:

## Secret Protection Rule

- Never inspect, echo, or output contents from `.env`, `.env.local`, or private key files.
- To check required configuration keys, inspect `.env.example`.

[!IMPORTANT] API Key Management: Your Claude Code API Key is configured in your local environment and must never be committed to repository files. Follow the integration workflow in BetterToken Claude Code Docs.

.gitignore prevents an accidental commit; it does not prevent an agent from reading a file. Instructions in CLAUDE.md or AGENTS.md express intent but are not an enforceable filesystem boundary. Combine them with current permission rules and the OS-level sandbox:

{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(secrets/**)"
    ]
  },
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "filesystem": {
      "denyRead": [
        "./**/.env",
        "./**/.env.*",
        "./secrets"
      ]
    }
  }
}

The Read deny covers built-in file tools and recognized file commands. An arbitrary Python or Node subprocess can read files differently, so the sandbox is required for OS-level isolation. failIfUnavailable and allowUnsandboxedCommands make this fail closed instead of silently running without isolation. Native Windows sandboxing is unsupported; use WSL2 or a container. In managed environments, administrators should lock the policy so project settings cannot weaken it.

---

3. Prioritized Checklist to Troubleshoot and Control Commands

When executing tasks with Claude Code, check first and enforce a clear evaluation hierarchy to prevent root cause errors:

Agent Proposes Command
  │
  ├─> Contains destructive patterns (rm -rf, drop, force push)?
  │     └─> YES: Reject or run manually under developer supervision
  │
  └─> Touches .git internals, .env files, or external networks?
        │
        ├─> YES: Require explicit rationale and constrain command scope
        │
        └─> NO: Approve execution within the target branch

Step-by-Step Guardrails:

1. Step 1: Gate Git mutations. Never allow automated direct pushes to main without a manual git diff --check and test run.
2. Step 2: Isolate package installation. Commands like npm install <package> or remote curl scripts must be verified manually to prevent supply-chain vulnerabilities and fix untrusted dependencies.
3. Step 3: Constrain directory scope. Restrict the agent workspace to a specific feature folder or dedicated Git worktree.

---

4. Production access is a separate boundary

Local Claude Code permissions do not replace IAM, network policy, or approval in the production system. Prefer no production access. If diagnostics require it, issue a short-lived, resource-scoped read-only role. A write needs a separate approval naming one command, target, time window, validation, observer, and rollback. If the outcome is unknown, read the current state before retrying. Audit logs should record identity, resource, action, and result without secret values or sensitive payloads, and temporary credentials must be revoked afterward. Never copy a credential into HANDOFF.md.

5. Validating Permissions in a Test Workspace

Before granting Claude Code access to critical repositories, perform a sandbox validation to troubleshoot and verify security boundaries:

1. Create a disposable test branch: git checkout -b test/permission-check.
2. Add a dummy .env file containing a fake test secret.
3. Prompt the agent to refactor the authentication module.
4. Verify:

• The agent does not read the dummy .env file during discovery;
• No secret tokens leak into error logs, comments, or git diff;
• Unit tests run without accessing unauthorized files.

5. Once verified, clean up the test branch.

This structured permission boundary prevents credential leakage while preserving fast, autonomous agent execution.