HAL — Harmful Action Limiter
"I'm sorry, Dave. I'm afraid I can't do that."
— HAL 9000, 2001: A Space Odyssey

HAL provides critical protection for AI coding agents, ensuring that automated systems function safely while executing commands. As development teams increasingly rely on these agents to write code, run tests, and manage infrastructure, the need for oversight is more important than ever.

The Challenge

The rapid evolution of AI agents brings efficiency, but it also introduces risks. Mistakes can happen, such as executing commands like rm -rf in the wrong directories or pushing undesirable changes to branches. These 1% mistakes can lead to significant data loss or disruptions. HAL steps in as a robust solution by adding a necessary layer of command supervision without slowing down operations.

Key Features

• Command Supervision: HAL intercepts commands before they are executed, using a structured rule system to allow or block actions based on their context.
• Plain YAML Rules: Configure rules easily in plain YAML format without needing complex regex or coding skills.
• Token-Level Matching: Ensure accurate matching of commands by analyzing structured tokens rather than raw command strings.
• Predefined Rule Packs: HAL comes preloaded with several rule packs catering to common command scenarios, significantly reducing initial setup time.

Example Rule

Here’s an example of how a rule is defined in HAL:

- name: push-force
  command: git
  has_all: [push]
  has_any: [--force, -f]
  unless: [--force-with-lease]
  severity: critical
  reason: "Rewrites remote history. Use --force-with-lease instead."

This structure demonstrates how HAL prevents unsafe usage while allowing safer alternatives.

How It Works

HAL operates as a command hook within your AI coding agent. It reviews commands against a set of specified rules before they are executed, ensuring that commands never run unchecked.

Use HAL in hook mode to evaluate and respond to commands interactively, ensuring every command executed is compliant with your safety criteria:

hal test "git reset --hard"        # BLOCKED
hal test "git commit -m 'fix'"     # ALLOWED
hal test "sudo rm -rf /"           # BLOCKED
hal test "rm -rf node_modules"     # ALLOWED

Available Packs

HAL includes five comprehensive rule packs:

Configuration

While HAL works out of the box, it also allows additional custom configurations. Users can modify the global settings in ~/.config/hal/config.yaml or override at the project level using .hal.yaml files.

Design Principles

• Fail-open by default: Ensures that HAL does not block legitimate commands, defaulting to ALLOW on errors.
• Efficiency: Designed for sub-millisecond performance with minimal overhead, making it suitable for high-performance environments.
• Lightweight Code: Approximately 400 lines of code deliver safety, highlighting the effectiveness of HAL.

Contribution

HAL is an open-source project, encouraging community contributions. Help improve HAL by reporting bugs or enhancing the rules.

Detailed guidance on contributing and defining new rules can be found in the repository.

For further information or to report issues, visit the Open issues page.

With HAL, it is possible to harness the power of AI coding agents while maintaining command oversight, ultimately leading to more reliable development workflows.