AI Coding

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

A practical guide to least-privilege permissions in Claude Code: isolating .env files, gating destructive Git and shell operations, and validating access boundaries in a test workspace.

BT

BetterToken

Editorial Team
3 min read

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:

TierOperationsDefault PolicyExamples
1. Code InspectionReading workspace filesAllowed (Auto-approved)cat, grep, viewing source files in src/
2. Secrets & ConfigAccessing .env, keys, tokensStrictly Prohibited.env*, id_rsa, *.pem, credentials.json
3. File EditsModifying and authoring codeAllowed within workspace scopewrite_to_file, replace_file_content
4. Dangerous Shell & GitPackage managers, mutating Git commandsManual Approval Requiredrm -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](https://docs.bettertoken.ai/ai-tools/claude-code?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-102&utm_content=claude-code-permissions-secrets-git).

---

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. 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.
  1. Once verified, clean up the test branch.

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

Related articles

Ready to optimize your LLM workflow?

Join thousands of developers building faster, smarter, and more cost-effective AI applications with BetterToken.