Noureddine RAMDI / Dippy: safe shell command hooks for Claude Code with a custom zero-dependency bash parser

Dippy tackles a real problem any developer using AI-assisted shell automation knows well: permission fatigue. When AI agents like Claude Code suggest or run shell commands, the risk of destructive or unintended operations can slow down development and introduce anxiety. Dippy’s approach is to analyze these commands with a custom-built bash parser and auto-approve safe, read-only commands while blocking dangerous ones. This reduces friction, speeds up workflows by up to 40%, and keeps your system safer.

What Dippy does and its architecture

Dippy is a Python-based tool designed as a PreToolUse hook for Claude Code, an AI agent orchestration platform. Its job is to intercept shell commands before Claude Code executes them, analyze their safety, and decide whether to auto-approve or block them with a custom deny message.

Under the hood, Dippy uses Parable, a hand-written bash parser implemented in Python with zero external dependencies. This parser isn’t a wrapper around existing shell parsers or external binaries; it directly parses bash command lines, handling complex constructs such as command chains (using &&, ||, ;), pipelines (|), and command substitutions ($(...)).

This approach allows Dippy to deeply understand the command structure and semantics without invoking a real shell parser, which would be heavier and potentially unreliable in AI contexts. Parable also detects advanced attack vectors like subshell injection, hidden mutations inside command substitutions, and destructive chains.

Configuration is granular: users can define custom deny messages that help steer the AI assistant back on track when commands are blocked, improving the interaction experience. The system is designed for smooth integration with Claude Code’s hook system, configured via JSON settings.

The repo boasts over 14,000 tests between Dippy and Parable, indicating a strong focus on correctness and edge case coverage. This test suite is essential given the inherent complexity of parsing bash safely.

The advantages and tradeoffs of a custom bash parser

Dippy’s core technical strength is Parable, the zero-dependency bash parser. Most tools that analyze shell commands either shell out to bash itself, rely on external libraries, or use partial regex-based heuristics. Parable takes a different route by implementing the parser logic from scratch in Python.

This has several benefits:

• No external dependencies: Simplifies installation and avoids security or compatibility issues with external binaries.
• Fine-grained control: The parser fully understands bash syntax, enabling detection of subtle destructive patterns.
• Performance: According to the README, the tool helps achieve up to 40% faster development cycles by reducing manual vetting.

However, the tradeoffs are clear:

• Complexity: Bash syntax is notoriously tricky and full-featured. Implementing a parser that covers all edge cases without invoking the shell parser is hard.
• Limitations: While Parable handles many cases including pipelines and substitutions, some extremely complex shell scripting features might still escape its detection.
• Maintenance burden: Maintaining a hand-written parser requires deep expertise and a comprehensive test suite, which Dippy addresses with its large number of tests.

The repo’s approach is opinionated: it prioritizes safety and minimizing dependencies at the cost of implementing and maintaining a non-trivial parser.

Quick start with Dippy

Installing and configuring Dippy is straightforward, especially if you use Homebrew:

brew tap ldayton/dippy
brew install dippy

For manual install:

git clone https://github.com/ldayton/Dippy.git

Integration with Claude Code requires adding a hook in your ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "dippy" }]
      }
    ]
  }
}

If installed manually, replace dippy with the full path to the hook binary.

Uninstall is just as clean by removing the hook entry and uninstalling via Homebrew if used.

verdict

Dippy is a practical tool for anyone using Claude Code to automate shell commands who wants to reduce permission fatigue and increase safety without adding heavy dependencies. Its hand-written bash parser Parable is the standout feature, providing deep command inspection and blocking destructive operations effectively.

That said, it’s important to recognize the inherent tradeoffs. Bash parsing is complex, and no parser outside of the shell itself can guarantee perfect coverage. Dippy’s approach is a pragmatic middle ground: it handles many real-world edge cases and complex constructs, but users should remain aware that extremely intricate shell scripts might not be fully parsed.

If you’re running Claude Code agents in environments where safe execution is critical and want a faster feedback loop on shell commands, Dippy is worth exploring. Its test coverage, zero dependencies, and integration with Claude Code hooks make it a solid choice for improving AI-assisted shell workflows.

→ GitHub Repo: ldayton/Dippy ⭐ 225 · Python