Claude Code Integration

Claude Code can use shellfirm as an MCP tool server to check commands before executing them. When configured, Claude checks every command against shellfirm's pattern database and context-aware rules before running it.

Setup

1. Install shellfirm

brew tap kaplanelad/tap && brew install shellfirm

Or with Cargo:

cargo install shellfirm

2. Add MCP configuration

Add shellfirm to your Claude Code MCP configuration. You can configure it globally or per-project.

Global configuration (~/.claude.json):

{
  "mcpServers": {
    "shellfirm": {
      "command": "shellfirm",
      "args": ["mcp"]
    }
  }
}

Per-project configuration (.claude.json in your project root):

{
  "mcpServers": {
    "shellfirm": {
      "command": "shellfirm",
      "args": ["mcp"]
    }
  }
}

3. Restart Claude Code

After adding the configuration, restart Claude Code so it picks up the new MCP server.

4. Verify the integration

Ask Claude Code to check a command:

Can you check if "git push --force origin main" is safe to run?

Claude should use the check_command tool and report the risk assessment.

How it works

Once configured, Claude Code has access to four shellfirm tools:

• check_command -- checks if a command is risky before executing it
• suggest_alternative -- gets safer alternatives for a risky command
• get_policy -- retrieves the current shellfirm configuration
• explain_risk -- provides detailed risk explanations

When Claude Code plans to execute a shell command, it can call check_command first. If the command is flagged as risky, Claude sees the matched patterns, severity, alternatives, and denial reason, and can decide to use a safer alternative or ask for your confirmation.

Example interaction

You: Deploy the latest changes to production.

Claude Code:

Let me check if the deployment command is safe first.

[calls check_command with "git push --force origin main"]

shellfirm flagged this command:

• git:force_push (High) -- "Force push can overwrite remote history."
• Alternative: git push --force-with-lease

I'll use the safer alternative instead: git push --force-with-lease origin main

Auto-deny for unattended use

When Claude Code runs autonomously, configure auto-deny to automatically block high-severity commands:

# ~/.shellfirm/settings.yaml
agent:
  auto_deny_severity: High

With this setting:

• Commands matching patterns with severity High or Critical are automatically denied
• Commands with Medium, Low, or Info severity are allowed to proceed
• Claude sees the denial reason and can suggest alternatives

Combining with project policies

When you have a .shellfirm.yaml in your project, Claude Code benefits from team-level policies. For example, if your team denies force pushes:

# .shellfirm.yaml
version: 1
deny:
  - "git:force_push"

Claude will see that force push is on the deny list and will not attempt it, regardless of severity thresholds.

Troubleshooting

• shellfirm tools not appearing -- verify that shellfirm is in your PATH by running which shellfirm
• Connection errors -- check that the MCP configuration JSON is valid and the command path is correct
• Commands not being checked -- Claude Code decides when to use MCP tools; it may not check every command automatically. You can instruct it in your project's CLAUDE.md to always check commands before executing.