Jermator (jerm)

A terminal command repair assistant that auto-detects failures after shell commands, proposes fixes using rule-based matching with LLM fallback, and executes repairs safely in a sandboxed environment.

Features

• Auto-detection: Hooks into bash/zsh to detect command failures automatically
• Rules-first: Deterministic fixes for common errors (dpkg, apt, permissions, etc.)
• LLM fallback: Falls back to OpenAI, Anthropic, or Gemini when rules don't match
• Safe execution: Sandbox mode copies your working directory and applies changes safely
• Policy gates: Hard deny patterns prevent dangerous operations
• Dry-run default: Shows proposed fixes without executing them

Installation

From Source

git clone https://github.com/fentz26/jermator.git
cd jermator
go build -o jerm ./cmd/jerm
sudo mv jerm /usr/local/bin/

Shell Integration

Add to your shell configuration:

Zsh (~/.zshrc):

source /usr/local/share/jerm/hooks/jerm.zsh

Bash (~/.bashrc):

source /usr/local/share/jerm/hooks/jerm.bash

Configuration

Copy the example config:

mkdir -p ~/.jerm
cp config.example.toml ~/.jerm/config.toml

Edit with your API keys:

jerm -c
# or manually:
$EDITOR ~/.jerm/config.toml

Provider Setup

Set API keys via environment or config file:

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="..."

Or in ~/.jerm/config.toml:

[providers]
default = "openai"

[providers.openai]
api_key = "sk-..."
model = "gpt-4o"

Usage

Automatic Mode

After shell integration, jerm will prompt on command failures:

$ apt install nginx
E: Could not get lock /var/lib/dpkg/lock-frontend

✗ Command failed with exit code 100
  apt install nginx

Fix now? (Y/n): 

Manual Commands

# Fix last failed command (dry-run by default)
jerm -f

# Fix all failures in session
jerm -f all

# Fix with custom prompt
jerm -p "I need to install Docker but got an error"

# Apply fixes in sandbox
jerm -f --apply

# Apply fixes directly (live mode)
jerm -f --exec

# Skip confirmation prompts (except require_approval)
jerm -f --apply --yes

# Edit configuration
jerm -c

# Check for updates
jerm -u

Flags

Flag	Description
--dry-run	Show what would be done (default)
--apply	Run in sandbox mode
--exec	Run in live mode (direct changes)
--yes	Auto-confirm prompts
--trace	Enable debug output

How It Works

1. Capture: Shell hooks capture failed commands and their output
2. Classify: Pattern matching identifies the error type
3. Match Rules: Looks for deterministic fixes in rule packs
4. LLM Fallback: If no rule matches, asks configured LLM
5. Policy Check: Validates fix plan against security policies
6. Execute: Runs in sandbox or live mode based on flags
7. Verify: Runs verification commands to confirm the fix

Rule Packs

Jerm includes built-in rules for:

• apt/dpkg errors (lock conflicts, broken deps, inconsistent state)
• Permission denied errors
• Command not found
• Git conflicts

Custom rules go in ~/.jerm/rules/*.yaml:

rules:
  - name: my-fix
    description: Fix my specific error
    match:
      - my_error_type
    steps:
      - type: command
        command: my-fix-command
        requires_approval: true
    verify:
      - my-verify-command

Security

Policy Gates

Jerm enforces security policies:

Hard Deny (never allowed):

• rm -rf /
• chmod 777 /
• Fork bombs
• Direct disk writes

Require Approval (even with --yes):

• sudo commands
• apt remove/purge
• systemctl stop/disable

Sandbox Mode

By default, --apply runs in sandbox mode:

1. Copies working directory to ~/.jerm/sandboxes/<run_id>
2. Applies changes in the sandbox
3. Runs verification
4. Shows diff and prompts for approval
5. No auto git push

Project Structure

jermator/
├── cmd/jerm/          # CLI entry point
├── internal/
│   ├── hook/          # Shell hook handling
│   ├── capture/       # Session capture
│   ├── classify/      # Failure classification
│   ├── plan/          # FixPlan and rules engine
│   ├── policy/        # Security policy
│   ├── exec/          # Sandbox and runner
│   ├── verify/        # Verification
│   └── providers/     # LLM providers
├── rules/             # YAML rule packs
├── schemas/           # JSON schemas
└── docs/              # Documentation

License

MIT License