Run Claude Code in CI Without Shell Access: --restricted Mode Strips Commands Entirely

Claude Code v2.1.248 adds --restricted mode: one flag strips all shell and command tools, leaving only file read/write inside your working directory — safer for unattended CI pipelines.

If you run Claude Code headlessly in CI — triggered by a PR, a nightly cron, a GitHub Actions step — the default toolset includes Bash, which can run arbitrary shell commands. That is useful in interactive sessions; in an automated pipeline it is an unnecessary attack surface.

The flag

# as a flag
claude --restricted -p "Review the diff in src/ and suggest improvements"

# or as an environment variable
CLAUDE_CODE_RESTRICTED=1 claude -p "Generate JSDoc for all exported functions"

Requires v2.1.248 or later. Check with claude --version.

What it removes

In restricted mode, Claude Code:

• Strips all built-in tools that run commands or code (Bash, computer use, etc.)
• Removes WebFetch (the agent cannot make outbound HTTP requests)
• Keeps file tools (Read, Write, Edit, Glob, Grep) confined to the working directory
• Refuses bypassPermissions even if your config tries to set it
• Ignores user, project, and local settings files — the runtime is fully controlled by the caller

The result is a file-only agent: it can read your codebase, propose edits, and write results, but it cannot run a shell command or reach the network.

When to reach for it

Good fits:

• Automated code review — Claude reads changed files and outputs a structured review; no commands needed
• Documentation generators — reads source files, writes JSDoc or markdown in place
• Lint suggestion runners — reads the file, proposes the fix, writes it; no linter invocation required
• Any pipeline where you control the tool invocation and only want file-level access

When it breaks your pipeline

If your pipeline needs the agent to run tests, compile, fetch external documentation, or invoke any CLI tool, restricted mode breaks those flows. Use --allowedTools instead to allow a specific subset:

# Allow only Read, Glob, and Grep — no writes, no commands
claude --allowedTools "Read,Glob,Grep" -p "List all TODO comments in src/"

The key limit: restricted mode is all-or-nothing on command execution. If you need one command tool but not others, --allowedTools gives you the surgical control that --restricted does not.

Sources: Release v2.1.248 — GitHub · Choose a permission mode — Claude Code Docs · Claude Code in CI/CD and headless automation — hidekazu-konishi.com