hikaflow 2.2.0

Deterministic test replay and autonomous debugging with LLM-powered fix generation

Hikaflow Debugger

Deterministic test replay and autonomous debugging with LLM-powered fix generation.

Hikaflow captures all external dependencies (HTTP, SQL, Redis, MongoDB, AWS, etc.) during test execution, enabling deterministic replay and automated fix generation.

Features

• Dependency Capture - Records HTTP, SQL, Redis, MongoDB, gRPC, AWS S3 calls
• Deterministic Replay - Replay tests with exact same external responses
• Flakiness Detection - Identify non-deterministic tests automatically
• Transcript Minimization - Delta debugging to find minimal failing case
• Autonomous Debugging - LLM-powered fix generation with proof certificates
• CI Integration - GitHub Actions, GitLab CI, CircleCI support

Installation

pip install autodebug

# With all optional dependencies
pip install autodebug[all]

# Or specific extras
pip install autodebug[probe]  # Full dependency capture
pip install autodebug[llm]    # LLM-powered debugging

Quick Start

Note: The legacy autodebug CLI is deprecated. Use hikaflow for all new workflows.

1. Authenticate

hikaflow login

2. Capture a failing test

# Run your test under Hikaflow instrumentation
hikaflow run -- pytest tests/test_api.py::test_user_creation -x

# Output:
# Run id: abc123
# Local bundle path: .autodebug/runs/abc123/

3. Debug interactively (requires LLM API key)

export ANTHROPIC_API_KEY=your_key  # or OPENAI_API_KEY

hikaflow debug

CLI Commands

Core Commands

Command	Description
hikaflow setup	Guided setup: doctor, login, init
hikaflow login	Authenticate via browser or device code
hikaflow logout	Clear stored credentials
hikaflow whoami	Show current authentication status
hikaflow doctor	Check environment and dependencies
hikaflow status	Show project status and recent errors
hikaflow run	Run a command under instrumentation
hikaflow errors	List recent production errors
hikaflow inspect	Inspect a specific error by ID
hikaflow debug	Interactive AI debugging session
hikaflow watch	Watch for new errors in real time
hikaflow openclaw-eval	Use OpenClaw to evaluate a run and suggest test/reliability improvements

hikaflow replay — Transcript replay & analysis

Command	Description
replay diff	Compare two transcripts
replay export	Export to HAR/curl/Postman
replay minimize	Delta-debug to smallest failing case
replay debug	Interactive transcript debugger
replay share	Share a run via public link
replay repro	Reproduce a run locally
replay prod	Replay a production error locally
replay optimize	Optimize a bundle for storage
replay auto	Autonomous debug workflow
replay analyze	Analyze a failure for root cause

hikaflow flaky — Flakiness detection & management

Command	Description
flaky scan	Scan for flaky tests and quarantine
flaky detect	Analyze tests for flakiness patterns
flaky heal	Automated healing for flaky tests
flaky measure	Run repeated tests to measure flakiness

Other command groups

Group	Description
hikaflow patterns	Manage the fix pattern database
hikaflow session	Session replay commands
hikaflow issues	Issue grouping commands
hikaflow quarantine	Manage test quarantine (list/add/remove/auto)

Supported Dependencies

Full Support

• requests - HTTP client
• httpx - Async HTTP client
• aiohttp - Async HTTP client
• psycopg2 / psycopg - PostgreSQL
• redis - Redis client
• time / random - Deterministic time and randomness

Partial Support

• sqlalchemy - ORM (DBAPI layer captured)
• grpcio - gRPC (unary-unary only)
• boto3 - AWS (S3 read operations only)
• pymongo - MongoDB (read operations only)

Not Yet Supported

• asyncpg - Async PostgreSQL
• aioredis - Async Redis
• motor - Async MongoDB
• celery / dramatiq - Task queues

How It Works

1. Capture Phase

When you run hikaflow run -- pytest, Hikaflow:

• Patches HTTP clients, database drivers, and other I/O
• Records all external calls with request/response data
• Captures timestamps, random values, and environment access
• Writes everything to .autodebug/runs/<run_id>/

2. Replay Phase

The repro harness:

• Rebuilds the exact Python environment
• Injects recorded responses instead of making real calls
• Blocks network access to ensure determinism
• Detects divergences from recorded behavior

3. Autonomous Debugging

With an LLM API key:

• Analyzes the failure and categorizes it
• Generates fix hypotheses using Claude or GPT
• Validates fixes by running them against the harness
• Produces proof certificates for working fixes

Configuration

Create .autodebug.yml in your project root:

# Environment handling
environment:
  tier: B  # A = pip freeze, B = lockfiles (poetry/pipenv)

# File capture
files:
  include:
    - "*.yaml"
    - "*.json"
    - "*.toml"
  exclude:
    - "*.pyc"
    - "__pycache__"
  max_size: 1048576  # 1MB

# Secret redaction
redaction:
  env_patterns:
    - "*_KEY"
    - "*_SECRET"
    - "*_TOKEN"

Scan Confidence Guardrails

Environment flags for scan confidence and degraded-mode behavior:

• HIKAFLOW_STRICT_EVIDENCE_MODE=1
  Demotes root-cause claims when evidence artifacts are missing.
• HIKAFLOW_DEGRADED_SCAN_GUARD=1
  Marks root-cause conclusions as tentative when scan fidelity is degraded.

CI Integration

GitHub Actions

- name: Run tests with Hikaflow
  uses: hikaflow-debug/hikaflow-debugger/.github/actions/capture@main
  with:
    test-command: pytest tests/ -x
    hikaflow-token: ${{ secrets.HIKAFLOW_TOKEN }}

- name: Comment on PR
  if: failure()
  uses: hikaflow-debug/hikaflow-debugger/.github/actions/pr-comment@main

GitLab CI

test:
  script:
    - pip install hikaflow
    - hikaflow run -- pytest tests/ -x
  artifacts:
    paths:
      - .autodebug/runs/

Repo Hygiene

• Ignore TypeScript build artifacts: add *.tsbuildinfo to .gitignore.
• If a .tsbuildinfo file is already tracked, untrack it once:

git rm --cached web/tsconfig.tsbuildinfo
git commit -m "chore: stop tracking tsbuildinfo artifact"

Project Structure

autodebug/              # CLI and core tools
  autonomous/           # LLM-powered debugging
  cli.py               # Command-line interface
  diff.py              # Transcript comparison
  minimize.py          # Delta debugging
  flakiness.py         # Flakiness detection

autodebug_probe/        # Capture instrumentation
  http_patch.py        # requests/httpx/aiohttp
  sql_patch.py         # psycopg2/psycopg
  redis_patch.py       # redis
  pymongo_patch.py     # pymongo
  boto3_patch.py       # boto3/botocore
  grpc_patch.py        # grpcio

autodebug_replay/       # Replay runtime
  http_replay.py       # HTTP replay
  sql_replay.py        # SQL replay
  redis_replay.py      # Redis replay

worker/                 # Background processing
  harness.py           # Repro harness generation
  validate.py          # Determinism validation
  optimize.py          # Storage optimization

api/                    # FastAPI server
  main.py              # API endpoints
  auth.py              # JWT authentication

API Server

Deploy the API for team collaboration:

# Install API dependencies
pip install autodebug[api]

# Set environment variables
export SUPABASE_URL=...
export SUPABASE_SERVICE_ROLE_KEY=...
export CLERK_SECRET_KEY=...
export UPSTASH_REDIS_REST_URL=...
export UPSTASH_REDIS_REST_TOKEN=...

# Run the server
uvicorn api.main:app --host 0.0.0.0 --port 8000

Development

# Clone and install
git clone https://github.com/hikaflow-debug/hikaflow-debugger.git
cd hikaflow-debugger
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Format code
black .
ruff check --fix .

# Type check
mypy autodebug/

Requirements

• Python 3.9+
• Docker (for validation harness)
• LLM API key (for autonomous debugging)

License

Proprietary - All rights reserved.

Contributing

Contributions welcome! Please read the contributing guidelines first.

Links

• Documentation
• Issues
• Changelog