Troubleshooting

shellfirm is not intercepting commands

Shell hook not loaded

The most common issue. Verify that the shell hook is active:

shellfirm status

If the hook is not loaded, re-run the setup:

shellfirm init --install

Then restart your shell (open a new terminal window or run exec $SHELL).

Manual hook setup

If --install did not work, add the hook manually. Check your shell configuration file:

Shell	Config file	Hook line
Zsh	~/.zshrc	eval "$(shellfirm init zsh)"
Bash	~/.bashrc	eval "$(shellfirm init bash)"
Fish	~/.config/fish/config.fish	shellfirm init fish | source

See Shell Setup for all 8 shells.

shellfirm not in PATH

Verify shellfirm is accessible:

which shellfirm
shellfirm --version

If not found, ensure the installation directory is in your PATH:

# Homebrew
export PATH="/opt/homebrew/bin:$PATH"

# Cargo
export PATH="$HOME/.cargo/bin:$PATH"

Commands pass through without challenge

Severity threshold too high

If you set min_severity to High or Critical, many checks will be skipped. Check your current threshold:

shellfirm config show

Lower it or remove it:

shellfirm config severity all

Check group disabled

Verify which groups are active:

shellfirm config show

Pattern is ignored

Check if the specific pattern ID is in your ignore list:

shellfirm config ignore --list

Test a specific command

Use the check command to dry-run:

shellfirm check --command "git push --force origin main"

This shows whether the command matches any patterns and why.

Too many false positives

Disable strict groups

The strict check groups (fs-strict, git-strict, kubernetes-strict) are broader and may generate noise. Disable them:

shellfirm config groups --disable fs-strict --disable git-strict --disable kubernetes-strict

Raise the severity threshold

shellfirm config severity Medium

Ignore specific patterns

If a specific pattern fires too often on commands you regularly use, add it to the ignore list:

shellfirm config ignore git:interactive_rebase
shellfirm config ignore git:cherry_pick
shellfirm config ignore git:bisect

To see what's currently ignored:

shellfirm config ignore --list

Blast radius is not showing

Check if enabled

shellfirm config show

Command not supported

Not all checks have blast radius computation. See Blast Radius for the list of supported checks.

Computation timed out

Blast radius has a 3-second timeout. On very large directories or slow Docker daemons, the computation may time out silently. This is by design -- blast radius never blocks the challenge prompt.

Missing tools

Blast radius relies on system commands (find, du, git, docker, kubectl). If these tools are not available, the computation returns nothing.

Configuration issues

Find your config file

shellfirm status

This shows the path to your settings file.

Validate configuration

If shellfirm fails to start, your settings file may have invalid YAML. Try resetting:

shellfirm config reset

Choose the backup option to preserve your current settings.

Invalid values

shellfirm validates config values and provides helpful error messages:

$ shellfirm config challenge Foo
Error: invalid challenge type: 'Foo'

Valid options: Math, Enter, Yes

MCP server issues

Agent cannot connect

Verify the MCP server starts correctly:

shellfirm mcp

It should wait for JSON-RPC input on stdin. Press Ctrl+C to exit.

Check agent configuration

For Claude Code, verify your MCP configuration:

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

Ensure shellfirm is in the PATH used by the agent.

shellfirm wrap issues

PTY not available

shellfirm wrap requires a PTY-capable terminal. It will not work inside certain CI environments or non-interactive shells.

Wrong delimiter

If statements are not being intercepted in a wrapped session, the delimiter may be wrong. Override it:

shellfirm wrap --delimiter ';' psql -h localhost

Performance

shellfirm is designed to be fast:

• Pattern matching uses compiled regexes with parallel execution (rayon)
• All checks are compiled into the binary at build time
• The shell hook adds minimal latency to command execution
• Blast radius has a 3-second timeout with graceful degradation

If you notice slowness, it is likely the blast radius computation on a large directory. You can disable it in ~/.config/shellfirm/settings.yaml:

blast_radius: false

Getting help

If your issue is not covered here:

1. Check the GitHub Issues for known problems
2. Run shellfirm check --command "<your command>" to diagnose pattern matching
3. Check the audit log for clues: shellfirm audit show | jq . | tail -20
4. Open a new issue with your shellfirm version (shellfirm --version), shell, and OS