DEV Community

BetterToken.ai profile image Adela
Adela for BetterToken.ai

Posted on Originally published at bettertoken.ai

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

#ai #programming #productivity #tutorial

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 Allowed (Auto-approved) cat, grep, viewing source files in src/
2. Secrets & Config Accessing .env, keys, tokens Strictly Prohibited .env*, id_rsa, *.pem, credentials.json
3. File Edits Modifying and authoring code Allowed within workspace scope write_to_file, replace_file_content
4. Dangerous Shell & Git Package managers, mutating Git commands Manual Approval Required 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`.
Enter fullscreen mode Exit fullscreen mode

[!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.

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
Enter fullscreen mode Exit fullscreen mode

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

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

Originally published on the BetterToken blog.

BetterToken provides pay-as-you-go access to AI model APIs through
OpenAI-compatible and Anthropic-compatible endpoints — useful if you are wiring
Claude Code, Codex, or your own tooling to a custom base URL.
See the docs to get started.

Top comments (0)