Hefesto - AI-Powered Code Quality Guardian

AI-powered pre-commit guardian. Catches security flaws, code smells, and complexity issues in 0.01s across 21 formats.

Quick Start

pip install hefesto-ai
cd your-project
hefesto analyze . --fail-on critical

What Hefesto Catches

# Hefesto catches:
password = "admin123"  # HARDCODED_SECRET
query = f"SELECT * FROM users WHERE id={id}"  # SQL_INJECTION_RISK
os.system(f"rm {user_input}")  # COMMAND_INJECTION

# Hefesto suggests:
password = os.getenv("PASSWORD")
cursor.execute("SELECT * FROM users WHERE id=?", (id,))
subprocess.run(["rm", user_input], check=True)

GitHub Action

steps:
  - uses: actions/checkout@v4
  - name: Run Hefesto Guardian
    uses: artvepa80/Agents-Hefesto@v4.9.8
    with:
      target: '.'
      fail_on: 'CRITICAL'

Inputs:

Outputs:

AI-Generated Code Guardrails (Pre-commit + MCP)

HefestoAI is a pre-commit guardian for AI-generated code. It detects semantic drift and risky changes before merge.

Add as an MCP server:

npx @smithery/cli@latest mcp add artvepa80/hefestoai

API Endpoints:

Language Support

Code Languages

DevOps & Configuration

Cloud Infrastructure

Total: 7 code languages + 10 DevOps formats + 4 Cloud formats = 21 supported formats

Installation

# FREE tier
pip install hefesto-ai

# TS/JS parsing + symbol metadata (optional)
pip install "hefesto-ai[multilang]"

# PRO tier
pip install hefesto-ai[pro]
export HEFESTO_LICENSE_KEY="your-key"

# OMEGA Guardian
pip install hefesto-ai[omega]
export HEFESTO_LICENSE_KEY="your-key"

CLI Reference (v4.9.8)

# Analyze code
hefesto analyze <path>
hefesto analyze . --severity HIGH
hefesto analyze . --output json

# Check status
hefesto status

# Install/update git hook
hefesto install-hooks

# Start API server (PRO)
hefesto serve --port 8000

# Telemetry Management
hefesto telemetry status
hefesto telemetry clear

JSON Output

hefesto analyze . --output json          # stdout = pure JSON, banners -> stderr
hefesto analyze . --output json 2>/dev/null | jq .  # pipe-safe

Exit Codes

Gate Examples

hefesto analyze . --fail-on high         # exit 1 if HIGH+ found
hefesto analyze . --fail-on critical     # exit 1 only if CRITICAL found
hefesto analyze .                        # always exit 0 (report only)

Pre-Push Hook

Automatic validation before every git push:

# Install/update hook (copies scripts/git-hooks/pre-push -> .git/hooks/pre-push)
hefesto install-hooks

# Update an existing hook
hefesto install-hooks --force

# Bypass temporarily
SKIP_HEFESTO_HOOKS=1 git push

The hook runs two gates:

1. Security gate — hefesto analyze with --fail-on CRITICAL --exclude-types VERY_HIGH_COMPLEXITY,LONG_FUNCTION (blocks security issues, ignores complexity debt)
2. Fast lint/test gate — Black, isort, Flake8, and a minimal test suite

Note: Hooks are local to your machine and not committed to git. Run hefesto install-hooks after cloning or whenever scripts/git-hooks/pre-push is updated.

Features by Tier

• PRO: Start Free Trial - 14 days, no credit card
• OMEGA: Start Free Trial - 14 days, no credit card
• Founding Members: 40% off forever (first 25 customers)

Hefesto PRO Optional Features

Hefesto OSS works standalone. If Hefesto PRO is installed, OSS can optionally enable: Patch C API hardening for hefesto serve, scope gating (first-party by default), TS/JS symbol discovery, and safe deterministic enrichment (schema-first, masked, bounded). See docs/PRO_OPTIONAL_FEATURES.md.

REST API (PRO)

# Start server (binds to 127.0.0.1 by default)
hefesto serve --port 8000

# Analyze code
curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $HEFESTO_API_KEY" \
  -d '{"code": "def test(): pass", "severity": "MEDIUM"}'

API Security (v4.8.0)

The API server is secure by default:

# Production example
export HEFESTO_API_KEY=my-secret-key
export HEFESTO_CORS_ORIGINS=https://app.example.com
export HEFESTO_API_RATE_LIMIT_PER_MINUTE=60
export HEFESTO_EXPOSE_DOCS=false
hefesto serve --host 0.0.0.0 --port 8000

Endpoints

CI/CD Integration

GitHub Actions

name: Hefesto

on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Hefesto
        run: pip install hefesto-ai
      - name: Run Analysis
        run: hefesto analyze . --severity HIGH

GitLab CI

hefesto:
  stage: test
  script:
    - pip install hefesto-ai
    - hefesto analyze . --severity HIGH

Configuration

Environment Variables

# Core
export HEFESTO_LICENSE_KEY="your-key"
export HEFESTO_SEVERITY="MEDIUM"
export HEFESTO_OUTPUT="json"

# API Security (v4.7.0)
export HEFESTO_API_KEY="your-api-key"                # Enable API key auth
export HEFESTO_API_RATE_LIMIT_PER_MINUTE=60           # Enable rate limiting
export HEFESTO_CORS_ORIGINS="https://app.example.com" # Restrict CORS
export HEFESTO_EXPOSE_DOCS=true                       # Enable /docs, /redoc
export HEFESTO_WORKSPACE_ROOT="/srv/code"              # Path sandbox root
export HEFESTO_CACHE_MAX_ITEMS=256                     # Cache size limit
export HEFESTO_CACHE_TTL_SECONDS=300                   # Cache entry TTL

Config File (.hefesto.yaml)

severity: HIGH
exclude:
  - tests/
  - node_modules/
  - .venv/

rules:
  complexity:
    max_cyclomatic: 10
    max_cognitive: 15
  security:
    check_secrets: true
    check_injections: true

OMEGA Guardian

Production monitoring that correlates code issues with production failures.

Features

• IRIS Agent: Real-time production monitoring
• Auto-Correlation: Links code changes to incidents
• Real-Time Alerts: Pub/Sub notifications
• BigQuery Analytics: Track correlations over time

Setup

# iris_config.yaml
project_id: your-gcp-project
dataset: omega_production
pubsub_topic: hefesto-alerts

alert_rules:
  - name: error_rate_spike
    threshold: 10
  - name: latency_increase
    threshold: 1000

# Run IRIS Agent
python -m hefesto.omega.iris_agent --config iris_config.yaml

# Check status
hefesto omega status

IRIS Telemetry Contract (OMEGA)

IRIS labels deployments as GREEN/YELLOW/RED using post-deploy telemetry. The input format is an open contract — any observability stack can produce it:

# Validate your telemetry file
python scripts/validate_aggregates_jsonl.py aggregates.jsonl

# Feed to IRIS (OMEGA tier)
export IRIS_TELEMETRY_SOURCE=file
export IRIS_TELEMETRY_FILE=aggregates.jsonl
iris label-outcomes --repo org/repo --commit abc123 --env production --window both --json

Enterprise collectors (Prometheus, Datadog, CloudWatch) and integration runbooks are available in the PRO distribution.

The Dogfooding Story

We used Hefesto to validate itself before publishing v4.0.1:

Critical bugs found:

1. Hardcoded password in test fixtures (CRITICAL)
2. Dangerous exec() call without validation (HIGH)
3. 155 other issues (code smells, security, complexity)

Result: All fixed before shipping. Meta-validation at its finest.

Changelog

v4.9.8 (2026-03-13)

• Telemetry: Anonymous usage pings enabled by default (opt-out via HEFESTO_TELEMETRY=0)
• First-run notice printed once to stderr
• No code, paths, or PII collected

v4.9.7 (2026-03-13)

• Telemetry: Anonymous usage ping endpoint (CLI opt-in + GitHub Action always-on)

v4.9.3 (2026-02-24)

• MCP endpoint live (JSON-RPC 2.0)
• AI discoverability stack complete (llms.txt, agent.json, OpenAPI, FAQ, Changelog)
• Registered in official MCP Registry and Smithery

v4.9.0 (2026-02-14)

• Boundary: Public/private repo split — community edition only in public repo.
• Removed: Paid modules (api, llm, licensing, omega), paid infra, paid tests.
• Hardened: Packaging (packages.find exclude, MANIFEST.in prune, CI guard).

v4.8.5 (2026-02-13)

• GitHub Action: Market-ready Docker-based action (bypassing PyPI).
• Security: Deterministic smoke tests with clean/critical fixtures.
• CLI: Verified exit code contract (2 = Issues Found).

v4.7.0 (2026-02-10)

• Patch C: API Hardening — hefesto serve is secure-by-default (local-first)
• Security: API key auth, CORS allowlist, docs toggle, path sandbox

v4.3.3 (2025-12-26)

• Fix LONG_PARAMETER_LIST: use AST formal_parameters instead of comma counting
• Fix function naming: infer names from variable_declarator for arrow functions

v4.2.1 (2025-10-31)

• Critical tier hierarchy bugfix
• OMEGA Guardian release

Telemetry

HefestoAI collects anonymous usage data by default to help improve the tool.

What's sent: event type, version, OS, Python version, file count, duration, issue count. What's NOT sent: code, file paths, file contents, project names, or any PII.

Disable with:

export HEFESTO_TELEMETRY=0

Support

• Email: support@narapallc.com
• GitHub Issues: Open an issue
• PRO/OMEGA: Priority support via email

Keywords: pre-commit code quality, AI generated code validation, semantic drift detection, Claude Code validator, GitHub Copilot quality gate, vibe coding safety net, code quality tool, developer tools LatAm, Peru startup, hefesto-ai, HefestoAI, open source code guardian

License

MIT License for core functionality. PRO and OMEGA features are licensed separately.

Hefesto: AI-powered code quality that caught 3 critical bugs in its own release.

(c) 2025 Narapa LLC, Miami, Florida