Agents & Automation

When AI coding agents like Claude Code, Cursor, or other MCP-compatible tools execute shell commands, they cannot solve interactive challenges. shellfirm provides an agent mode that automatically assesses risk and denies dangerous commands based on severity thresholds.

How it works

shellfirm exposes an MCP (Model Context Protocol) server that AI agents connect to over stdio. When an agent wants to execute a command, it sends the command to shellfirm for assessment. shellfirm runs the full check pipeline and returns a structured JSON response with:

• Whether the command is allowed or denied
• Matched rules with severity and descriptions
• Blast radius information
• Safer alternative commands
• Environmental context (SSH, root, git branch, k8s)

Starting the MCP server

shellfirm mcp

This starts a JSON-RPC 2.0 server over stdin/stdout that implements the MCP tool protocol.

MCP tool: assess_command

The MCP server exposes a single tool that agents call:

Input:

{
  "command": "rm -rf /tmp/data"
}

Output (allowed):

{
  "allowed": true,
  "risk_level": "Normal",
  "severity": null,
  "matched_rules": [],
  "alternatives": [],
  "context": {
    "risk_level": "Normal",
    "labels": []
  }
}

Output (denied):

{
  "allowed": false,
  "risk_level": "Normal",
  "severity": "High",
  "matched_rules": [
    {
      "id": "git:force_push",
      "description": "This command will force push and overwrite remote history.",
      "severity": "High",
      "group": "git",
      "blast_radius_scope": "PROJECT",
      "blast_radius_detail": "Force-pushes 5 commits to origin/main"
    }
  ],
  "alternatives": [
    {
      "command": "git push --force-with-lease",
      "explanation": "Checks that your local ref is up-to-date before force pushing.",
      "source": "regex-pattern"
    }
  ],
  "denial_reason": "Severity HIGH meets or exceeds agent auto-deny threshold HIGH",
  "requires_human_approval": false
}

Agent configuration

Auto-deny severity

Control which severity level triggers automatic denial for agent commands:

# In ~/.config/shellfirm/settings.yaml
agent:
  auto_deny_severity: High   # default

Setting	Effect
Critical	Only Critical commands are denied; High and below are allowed
High	High and Critical are denied (default)
Medium	Medium, High, and Critical are denied
Low	Almost everything is denied
Info	Everything is denied

Or edit via shellfirm config edit.

Human approval

Reserve the option to require human approval for denied commands (for future workflow integrations):

agent:
  require_human_approval: false   # default

Deny list

Commands matching deny-listed patterns are always rejected, regardless of severity:

deny_patterns_ids:
  - git:force_push
  - kubernetes:delete_namespace
  - terraform:apply_with_auto_approve

Or via project policy (.shellfirm.yaml):

version: 1
deny:
  - git:force_push
  - kubernetes:delete_namespace

Configuring Claude Code

To use shellfirm with Claude Code, add it as an MCP server in your Claude Code configuration:

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

Claude Code will then call assess_command before executing shell commands, and respect the allowed/denied decision.

Audit trail for agent commands

All agent-assessed commands are logged to the audit trail with additional fields:

{
  "command": "git push --force",
  "outcome": "DENIED",
  "severity": "High",
  "agent_name": "claude-code",
  "agent_session_id": "session-abc123",
  "blast_radius_scope": "PROJECT",
  "blast_radius_detail": "Force-pushes 5 commits to origin/main"
}

This provides full visibility into what AI agents attempted to execute and what was blocked.

Security invariant

The same security invariant applies to agent mode: policies and configuration can only escalate protections, never weaken them. An agent cannot bypass deny-listed patterns or lower severity thresholds.