HAVFRYS
An Uncertainty-Aware Engineering Runtime for AI Coding Agents
What is HAVFRYS?
HAVFRYS is an uncertainty-aware engineering runtime built for AI coding agents (Claude Code, Cursor, Gemini CLI, VS Code, Windsurf, OpenCode, Cline, Continue, Zed).
AI coding agents excel at linear tasks, but fail when tasks become uncertain. When a complex refactor or dependency upgrade breaks 40 tests across a codebase, agents lose their place, oscillate in trial-and-error loops, and hallucinate fixes.
HAVFRYS provides execution resilience:
- Linear by Default: Simple commands execute with near-zero overhead.
- Uncertainty-Driven Micro-Branching: Automatically detects when linear execution hits an uncertainty point, spawning budget-constrained micro-branches to evaluate competing engineering solutions in isolated worktrees.
- Aggressive Loop Termination: Detects code oscillation ($A \to B \to A \to B$) and kills failing branches before token drift occurs.
- Immediate Merge: Merges the winning branch back into the working tree cleanly.
Quickstart
1. Install via PyPI
pip install havfrys
2. Auto-Configure Local Coding Agent
havfrys init
Welcome to HAVFRYS.
Detected Claude Code.
Configure automatically? [Y/n]
3. Verify Environment Health
havfrys doctor
HAVFRYS Diagnostics
Runtime: [ok] Installed
Python: [ok] 3.14.6
MCP Server: [ok] Available (havfrys serve)
Clients: [ok] Claude Code, Cursor, VS Code detected
Compression Engine: [ok] Loaded (Lossless + SmartCrusher)
Loop Detection: [ok] Loaded (BranchLoopDetector)
Version: v0.2.2
Repository: [ok] Ready
System Architecture & Execution Flow
1. Complete Task Execution Lifecycle
HAVFRYS
Uncertainty-Aware Repository Evolution Runtime
|
|
---------------------------------
| |
SDK MCP
| |
havfrys.run() havfrys tool
havfrys.resume() |
havfrys.inspect() |
| |
---------------------------------
|
|
Task Submission
|
|
"Modernize this repository to 2026 standards"
|
|
Orchestrator
|
|
Is this a difficult engineering task?
|
-----------------------------------------
| |
NO YES
| |
Linear Execution Linear Execution
(20-50 ms) |
| |
SUCCESS |
|
Uncertainty Detection
|
Is this an engineering uncertainty point?
|
----------------------------------------
| |
NO YES
| |
Retry / Fix Spawn Micro Branches
| |
| -----------------------------------
| | | |
| Branch A Branch B Branch C
| | | |
| | | |
| Execute Task Execute Task Execute Task
| | | |
| -----------------------------------
| |
| Internal Loop Detection
| |
| Kill Losing Branches
| |
| Select Winner Branch
| |
------------------------------------------
|
Merge Winning Changes
|
Resume Linear Execution
|
Validate Repository State
|
-----------------------------------
| |
FAILED SUCCESS
| |
Recover / Retry Repository GREEN
| |
-----------------------------------
|
Final Result
|
Python 3.14 + Tests Passing + Docs Updated
2. Runtime Component Stack
HAVFRYS RUNTIME
|
|
Orchestrator
|
---------------------------------------------------
| | | |
Compression Engine Memory Engine Loop Engine Branch Engine
| | | |
---------------------------------------------------
|
Repository State
|
---------------------------------------------------
| | | |
Git Worktrees Tests Validation
| | | |
---------------------------------------------------
|
Execution Layer
|
-------------------------------------
| |
Native Docker
Backend Backend
3. End-User Integration Journey
pip install havfrys
|
havfrys init / doctor
|
Configure MCP Client
|
Claude Code / Gemini
Cursor / OpenCode etc.
|
"Modernize this repository"
|
HAVFRYS
|
Repository GREEN
|
Continue Working
The 7 Invariants
- Linear Execution Default: Simple commands execute natively with ~20ms overhead.
- Branch at Uncertainty: Micro-branching only activates when ambiguous failures recur.
- Tiny, Short-Lived Branches: Ephemeral worktrees constrained by hard budgets (2,000 tokens, 5 attempts, 3 minutes).
- Compress Before Reasoning: Output streams are compressed before model evaluation.
- Rich Internal Loop Detection: Catches code oscillation ($A \to B \to A \to B$), no-diff stagnation, and compression loops.
- Aggressive Branch Termination: Bad branches exceeding budgets or looping are killed immediately.
- Immediate Patch Merge: Winning micro-branch merges back into the source working tree cleanly.
The 3 HAVFRYS Laws
- Law #1: Nothing reasons over raw artifacts.
- Law #2: Nothing branches unless uncertainty exists.
- Law #3: Nothing lives longer than its usefulness.
Single-Tool FastMCP Server
HAVFRYS exposes a single, unified MCP tool (havfrys) over stdio:
havfrys serve
Input
{
"task": "Upgrade codebase to Pydantic V2 and fix breaking schema changes"
}
Output
{
"status": "success",
"summary": "Task completed successfully in 1.42s across 2 attempt(s). Spawning 2 micro-branches; Branch A merged.",
"output": "...",
"error": null,
"next_steps": "Proceed to next task.",
"retries": 1,
"cached": false,
"mode": "branching"
}
Python API Primitives
import havfrys
# 1. Execute an engineering task
result = havfrys.run("Fix breaking API migration tests")
# 2. Resume work from last execution state
result = havfrys.resume()
# 3. Inspect execution trajectory history
info = havfrys.inspect()
Real Engineering Case Studies (The Dogfooding Suite)
HAVFRYS is evaluated on real production repositories facing breaking ecosystem migrations. See DOGFOODING.md for the full 10-repository case study matrix across Python 3.14, Pydantic V2, Django, Prefect, and GraphQL stacks.
| # | Repository | Task | Stress Test | Status |
|---|---|---|---|---|
| 1 | FastAPI Full Stack Template | Modernize 2023 template to 2026 standards | Pydantic V2, SQLModel 2026, Thread Isolation | DONE (54/54 Passed) |
| 2 | Cookiecutter Django | Upgrade Python 3.14 & Django | Django ORM, CI/CD, Env setup | DONE (193 Passed) |
| 3 | Prefect | Modernize dependencies & tests | Async systems, 380+ flow tests | DONE (384 Passed) |
| 4 | LiteLLM | Modernize OpenAI & Anthropic SDKs | AI tooling & breaking API migrations | DONE (209 Passed) |
| 5 | CrewAI | Upgrade agent framework stack | Agent schema breakages & API updates | DONE (16/16 Passed) |
| 10 | HAVFRYS | Self-dogfooding & refactoring | Architectural consolidation & Rust bindings | DONE (468/468 Passed) |
Demo
Local Development & Testing
Build Rust Engine
maturin develop --offline
Run Full Test Suite
pytest tests/
cargo test
License
HAVFRYS is released under the Business Source License 1.1 (BUSL-1.1).
- Production, Personal, Academic, & Internal Company Use: Permitted under the Additional Use Grant.
- Commercial SaaS & Competing Offerings: Prohibited without explicit written authorization from Licensor.
- Automatic Open Source Transition: On January 1st, 2030, HAVFRYS automatically converts to the Apache License, Version 2.0.
1 maintainer
Release files for havfrys 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| havfrys-0.4.0-cp38-abi3-macosx_11_0_arm64.whl | CPython 3.8 | abi3 | macOS 11.0+ ARM64 | Details |
Release files / havfrys-0.4.0-cp38-abi3-macosx_11_0_arm64.whl
| Download URL | havfrys-0.4.0-cp38-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 854.0 kB |
| Tags | CPython 3.8 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
19401047f02c974ad651c22362994a02e5a27c94a16d3581872711b63c061264
|
|
BLAKE2b-256 checksum How to use checksums |
4b18c6af2fe2ef4d0dad42cf891cbc311a3da1a7afaf25e2a775aad66112ac86
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.6
|
