Documentation

1. Install the CLI

# Install via pip
pip install hikaflow

# Or with all optional dependencies
pip install hikaflow[all]

# Verify installation
hikaflow --version

2. Authenticate

# Browser-based login (interactive)
hikaflow login

# Device code flow (headless / SSH)
hikaflow login --device

# Direct token (CI/CD)
hikaflow login --token YOUR_API_TOKEN

3. Initialize your project

# Guided setup (recommended for first time)
hikaflow setup

# Or initialize directly
hikaflow init --name "my-project"

# Check everything is working
hikaflow doctor

4. Capture a test run

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

# View the captured run
hikaflow status

5. Debug interactively

Requires an LLM API key (Anthropic or OpenAI).

export ANTHROPIC_API_KEY=your_key  # or OPENAI_API_KEY

# Start an interactive debugging session
hikaflow debug

# Or analyze a specific run
hikaflow replay analyze --run-id abc123

GitHub Actions

name: Tests with Hikaflow
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: |
          pip install -e ".[dev]"
          pip install hikaflow

      - name: Run tests with Hikaflow
        env:
          HIKAFLOW_TOKEN: ${{ secrets.HIKAFLOW_TOKEN }}
        run: hikaflow run -- pytest tests/ -x

      - name: Scan for flaky tests
        if: always()
        env:
          HIKAFLOW_TOKEN: ${{ secrets.HIKAFLOW_TOKEN }}
        run: hikaflow flaky scan

GitLab CI

test:
  image: python:3.11
  script:
    - pip install hikaflow
    - hikaflow run -- pytest tests/ -x
  variables:
    HIKAFLOW_TOKEN: $HIKAFLOW_TOKEN

Self-Healing (Auto-Fix PRs)

Install the Hikaflow GitHub App to enable automatic fix PRs for flaky tests. When a flaky test is detected, Hikaflow analyzes the failure, generates a fix, validates it against the reproduction harness, and opens a PR for review.

1. Go to Settings → Integrations in the dashboard
2. Click Connect GitHub and install the Hikaflow app
3. Select which repositories to monitor
4. Fix PRs appear automatically when flaky tests are detected

Key endpoints

Quick start (self-hosted)

# Clone the repository
git clone https://github.com/hikaflow-debug/hikaflow-debugger.git
cd hikaflow-debugger

# Copy and fill in your environment variables
cp .env.example .env
# Edit .env with your Supabase, Clerk, and Redis credentials

# Start all services
docker compose -f docker-compose.selfhosted.yml up -d

Air-gapped / offline

For environments without internet access. Uses PostgreSQL + PostgREST, MinIO for storage, and Ollama for local LLM inference.

docker compose -f docker-compose.airgapped.yml up -d

Required services

See .env.example for the complete list of configuration options.