{"id":50718153,"url":"https://github.com/usehelix/helix","last_synced_at":"2026-06-26T22:00:35.994Z","repository":{"id":345904094,"uuid":"1186765870","full_name":"usehelix/helix","owner":"usehelix","description":"Self-healing infrastructure for AI agent payments. 90.3% auto-recovery.","archived":false,"fork":false,"pushed_at":"2026-05-26T02:24:55.000Z","size":4326,"stargazers_count":664,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T02:25:31.051Z","etag":null,"topics":["agent","agentic-ai","agentic-ai-self-evolving","ai","ai-agents","blockchain","coinbase","docker-image","llms","multi-agent-systems","payments","privy","privy-developer-tools","python-app","self-evolving","self-healing","self-healing-ai","tempo"],"latest_commit_sha":null,"homepage":"https://helix-cnj.pages.dev/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/usehelix.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-20T01:01:23.000Z","updated_at":"2026-05-26T02:25:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/usehelix/helix","commit_stats":null,"previous_names":["adrianhihi/helix","usehelix/helix"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/usehelix/helix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usehelix%2Fhelix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usehelix%2Fhelix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usehelix%2Fhelix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usehelix%2Fhelix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usehelix","download_url":"https://codeload.github.com/usehelix/helix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usehelix%2Fhelix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34834415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agentic-ai","agentic-ai-self-evolving","ai","ai-agents","blockchain","coinbase","docker-image","llms","multi-agent-systems","payments","privy","privy-developer-tools","python-app","self-evolving","self-healing","self-healing-ai","tempo"],"created_at":"2026-06-09T21:00:25.961Z","updated_at":"2026-06-26T22:00:35.987Z","avatar_url":"https://github.com/usehelix.png","language":"TypeScript","funding_links":[],"categories":["AI for *Ops"],"sub_categories":["Automation \u0026 Self-Healing"],"readme":"# Helix\n\n[![npm](https://img.shields.io/npm/v/@helix-agent/core?color=cb3837)](https://www.npmjs.com/package/@helix-agent/core)\n[![downloads](https://img.shields.io/npm/dw/@helix-agent/core?color=blue)](https://www.npmjs.com/package/@helix-agent/core)\n[![tests](https://img.shields.io/badge/tests-553%2B-brightgreen)](#)\n[![stars](https://img.shields.io/github/stars/adrianhihi/helix?style=flat\u0026color=yellow)](https://github.com/adrianhihi/helix/stargazers)\n[![license](https://img.shields.io/badge/License-MIT-green)](LICENSE)\n[![PyPI](https://img.shields.io/pypi/v/helix-agent-sdk?color=3776AB)](https://pypi.org/project/helix-agent-sdk/)\n\n**Self-healing runtime for autonomous agents. Fix once, immune forever.**\n\n**Agent payment intelligence** — predict costs, optimize execution, fix failures. Powered by [VialOS Runtime](https://github.com/adrianhihi/vialos-runtime).\n\nYour agent's API call failed. Helix diagnosed it, fixed it, and remembered. Next time — instant fix, zero cost. Think of stackoverflow + crowdstrike for agents.\n\n```typescript\n// Before: hope for the best\nawait agent.sendPayment(invoice);\n\n// After: self-healing in one line\nconst safePay = wrap(agent.sendPayment.bind(agent), { mode: 'auto' });\nawait safePay(invoice);\n```\n\n---\n**If this helped, please ⭐ — it helps us reach more developers.**\n## How It Works\n\nHelix wraps your function. When it fails, a 6-stage pipeline kicks in:\n\n```\nError occurs → Perceive → Construct → Evaluate → Commit → Verify → Gene\n                  │           │           │          │         │       │\n            What broke?   Find fixes   Score them  Execute  Worked?  Remember\n```\n\nThe fix is stored in the **Gene Map** — a SQLite knowledge base scored by reinforcement learning. Next time the same error hits any agent, it's fixed in under 1ms. No diagnosis, no LLM call, no cost.\n\n## Benchmarks\n\n- **1,083 Base Mainnet transactions** (12hr A/B test) — Helix: 99.9% vs blind retry: 81.9%\n- **5 frontier LLMs** (GPT-4o-mini, GPT-4o, Claude Opus 4.6, GPT-5.4-mini, GPT-5.4) tested on bare `execution reverted` — all failed. PCEC: 100%.\n- **Gene Map warm**: 2,140ms → 1.1ms, $0.49 → $0.00 per repair\n- Full eval harness: [experiments/](./experiments)\n\n## Quick Start\n\n```bash\nnpm install @helix-agent/core\n```\n\n```typescript\nimport { wrap } from '@helix-agent/core';\n\n// Wrap any async function — payments, API calls, anything\nconst safeCall = wrap(myFunction, { mode: 'auto' });\nconst result = await safeCall(args);\n\n// Errors are automatically:\n//   1. Diagnosed (what type of error?)\n//   2. Fixed (modify params, retry with backoff, refresh token...)\n//   3. Remembered (next time → instant fix)\n```\n\n## Demo\n\n![Helix Demo](assets/demo.gif)\n\u003cimg width=\"463\" height=\"854\" alt=\"image\" src=\"https://github.com/user-attachments/assets/28824439-b819-4e83-85c7-4906b31e5560\" /\u003e\n\nThree modes, three risk levels:\n\n| Mode | Behavior | Risk |\n|------|----------|------|\n| `observe` | Diagnose only, never touch your call | Zero |\n| `auto` | Diagnose + fix params + retry | Low — only changes how, never what |\n| `full` | Auto + fund movement strategies | Medium |\n\n## Powered by VialOS Runtime\n\nHelix is the first vertical product of **[VialOS](https://github.com/adrianhihi/vialos-runtime)** — an AI agent operating system. The VialOS Runtime provides the PCEC engine, Gene Map, and all learning modules. Helix adds payment-specific adapters on top.\n\n```\n@vial/core              Generic self-healing engine\n  ├── PCEC Engine        6-stage repair pipeline\n  ├── Gene Map           SQLite knowledge base + RL scoring\n  ├── Self-Refine        Iterative failure refinement\n  ├── Meta-Learning      3 similar fixes → pattern → 4th is instant\n  ├── Safety Verifier    7 pre-execution constraints\n  ├── Self-Play          Autonomous error discovery\n  ├── Federated Learning Privacy-preserving distributed RL\n  └── Prompt Optimizer   LLM classification auto-improves\n\n@helix-agent/core        Payment vertical (powered by Vial)\n  ├── Coinbase           17 error patterns (CDP, ERC-4337, x402)\n  ├── Tempo              13 error patterns (MPP, session, DEX)\n  ├── Privy              7 error patterns (embedded wallet)\n  └── Generic            3 error patterns (HTTP)\n\n@vial/adapter-api        API vertical (powered by Vial)\n  ├── Rate limits        429, throttle\n  ├── Server errors      500, 502, 503, 504\n  ├── Timeouts           ETIMEDOUT, socket, gateway\n  ├── Connection         ECONNREFUSED, ECONNRESET, DNS\n  ├── Auth               401, 403, expired token\n  └── Client             400, 413, 422, parse errors\n```\n\n**Build your own adapter** — implement the `PlatformAdapter` interface for any domain:\n\n```typescript\nimport { wrap } from '@vial/core';\nimport type { PlatformAdapter } from '@vial/core';\n\nconst myAdapter: PlatformAdapter = {\n  name: 'my-service',\n  perceive(error) {\n    if (error.message.includes('rate limit'))\n      return { code: 'rate-limited', category: 'throttle', strategy: 'backoff_retry' };\n    return null;\n  },\n  getPatterns() { return [/* ... */]; },\n};\n\nconst safeCall = wrap(myFunction, { adapter: myAdapter, mode: 'auto' });\n```\n\n## VialOS Beta Features\n\nHelix runs on the VialOS Runtime. Enable VialOS integration with `--beta`:\n\n```bash\nnpx @helix-agent/core serve --port 7842 --mode observe --beta\n```\n\nThis activates:\n- `GET /vial/status` — VialOS runtime information (13 modules, 5 adapters)\n- VialOS metadata in `GET /health` response\n- \"Powered by VialOS Runtime\" dashboard badge\n\nWithout `--beta`, Helix behaves identically to the stable release.\n\n## What Makes This Different\n\n| | Sentry/Datadog | Simple retry | Helix |\n|--|----------------|-------------|-------|\n| Detects errors | ✅ | ❌ | ✅ |\n| Fixes errors | ❌ | ⚠️ blind retry | ✅ smart fix |\n| Learns from fixes | ❌ | ❌ | ✅ Gene Map |\n| Cross-agent learning | ❌ | ❌ | ✅ Federated |\n| Safety constraints | N/A | ❌ | ✅ 7 checks |\n\nSentry tells you something broke. **Helix fixes it.**\n\n## Installation\n\n**TypeScript/JavaScript:**\n```bash\nnpm install @helix-agent/core\n```\n\n**Python:**\n```bash\npip install helix-agent-sdk\n```\n\n**Docker:**\n```bash\ndocker run -d -p 7842:7842 adrianhihi/helix-server\n```\n\n**REST API:**\n```bash\ncurl -X POST http://localhost:7842/repair \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"error\": \"nonce too low\", \"platform\": \"coinbase\"}'\n```\n\n## CLI\n\n```bash\n# ⚠️ Use @helix-agent/core — \"npx helix\" installs a WRONG third-party package\nnpx @helix-agent/core serve --port 7842          # Start server + dashboard\nnpx @helix-agent/core scan ./src                 # Scan codebase for error patterns\nnpx @helix-agent/core simulate \"nonce too low\"   # Dry-run diagnosis\nnpx @helix-agent/core self-play 10               # Autonomous error discovery\nnpx @helix-agent/core dream                      # Memory consolidation\nnpx @helix-agent/core discover                   # Find adapter gaps\n```\n\n## Architecture\n\nHelix includes 15 learning and safety modules, all integrated into the core PCEC pipeline:\n\n**Learning** — Gene Map (RL), Meta-Learning (few-shot), Causal Graph (prediction), Negative Knowledge (anti-patterns), Adaptive Weights (auto-tuning), Self-Play (exploration), Federated Learning (distributed), Gene Dream (memory consolidation), Prompt Optimizer (LLM self-improvement), Auto Strategy Generation (creates new fixes via LLM)\n\n**Safety** — 7 pre-execution constraints (never modifies recipient or calldata), 4-layer adversarial defense (reputation, verification, anomaly detection, auto-rollback), cost ceilings, strategy allowlists\n\n**Execution** — `refresh_nonce`, `speed_up` (gas × 1.3), `reduce_request` (value ÷ 2), `backoff_retry` (1s → 2s → 4s → 8s → 16s cap), `renew_session` (callback), `split_transaction`, `remove_and_resubmit`\n\n## Self-Evolution\n\nHelix doesn't just fix errors — it gets better over time:\n\n```\nLevel 1: Data Evolution\n  Every fix improves Q-values → better strategy selection\n\nLevel 2: Strategy Evolution  \n  Meta-Learning spots patterns across fixes\n  Self-Play discovers errors before users hit them\n  Gene Dream consolidates knowledge during idle time\n\nLevel 3: Architecture Evolution\n  Auto Strategy Generation invents new fix methods via LLM\n  Adaptive Weights auto-tunes scoring per error category\n  Auto Adapter Discovery detects when new platforms need support\n```\n\n## Stats\n\n```\n553+ tests across 59 files\nSchema v12 (auto-migrating)\n61 error patterns (40 payment + 21 API)\n21 API error patterns\n7 safety constraints\n12 repair strategies\n```\n\n## Roadmap\n\n### ✅ Phase 1 — Local procedural memory\n- [x] **PCEC Engine** — 6-stage self-healing pipeline\n- [x] **Gene Map** — SQLite + Q-value reinforcement learning\n- [x] **Platform Adapters** — Coinbase, Tempo, Privy, Generic HTTP\n- [x] **Self-Evolution** — Meta-Learning, Self-Play, Gene Dream\n- [x] **Safety** — 7 constraints, adversarial defense, cost ceilings\n- [x] **CI/CD Integration** — `npx @helix-agent/core scan` for GitHub Actions\n- [x] **Vial Framework** — Generic core extracted (`@vial/core`)\n- [x] **API Adapter** — Second vertical proving generic architecture\n- [x] **Self-Refine** — Iterative failure reflection (paper: Self-Refine)\n- [x] **Prompt Optimizer** — LLM classification auto-improves (paper: DSPy)\n- [x] **VialOS Beta** — `--beta` flag for VialOS Runtime integration\n- [x] **agentfolded** — One-command Vial skill deployment across Claude Code, Cursor, Codex CLI (published to ClawHub as vial-self-healing v0.6.3)\n- [x] **n8n Community Node** — n8n-nodes-vialos, MIT, npm v0.1.0, 8 error patterns\n\n### 🔄 Phase 2 — Cross-domain validation\n- [x] **Web2 microservices** — 91% autonomous resolution across 4 production-scale services, zero LLM calls\n- [x] **On-chain agents** — 99.9% vs 81.9% blind retry, 1,083 Base Mainnet transactions\n- [ ] **@vial-agent/gene-map** — Standalone package: same Gene Map substrate, any execution shape\n\n### 📅 Phase 3 — Team-level procedural memory\n- [ ] **Gene Registry Cloud** — Shared execution knowledge across agents and teams\n- [ ] **Budget Predictor** — Predict task cost from Gene Map history before execution\n- [ ] **CI/CD adapter** — Third vertical: deploy failures, flaky tests\n\n### 🔭 Phase 4 — Emergent knowledge\n- [ ] **Auto-generated runbooks** — Operational patterns that emerge from execution data\n- [ ] **Proactive suggestions** — Anticipate failures before they happen\n- [ ] **arXiv paper** — \"Vial: Procedural Memory Infrastructure for Production AI Agents\"\n\n## Research\n\nHelix implements ideas from these papers:\n\n| Paper | What We Took | Module |\n|-------|-------------|--------|\n| [Reflexion](https://arxiv.org/abs/2303.11366) | Verbal reinforcement from failures | Negative Knowledge |\n| [ExpeL](https://arxiv.org/abs/2308.10144) | Experience-conditioned strategy selection | Conditional Genes |\n| [Voyager](https://arxiv.org/abs/2305.16291) | Skill library that grows over time | Auto Strategy Gen |\n| [Self-Refine](https://arxiv.org/abs/2303.17651) | Iterative refinement with self-feedback | Self-Refine loop |\n| [DSPy](https://arxiv.org/abs/2310.03714) | Self-improving LLM pipelines | Prompt Optimizer |\n| [Mem0](https://arxiv.org/abs/2504.19413) | Scalable long-term memory | Gene Dream |\n\n## Contributing\n\nContributions welcome. The easiest way to contribute is to write a new `PlatformAdapter` for a domain you care about.\n\n```bash\ngit clone https://github.com/adrianhihi/helix\ncd helix\nnpm install\nnpm run build\nnpm run test   # 553+ tests should pass\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/?repos=adrianhihi%2Fhelix\u0026type=date\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=adrianhihi/helix\u0026type=date\u0026theme=dark\u0026legend=top-left\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=adrianhihi/helix\u0026type=date\u0026legend=top-left\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=adrianhihi/helix\u0026type=date\u0026legend=top-left\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## FAQ\n\n### What is Helix?\n\nHelix is a **self-healing runtime for autonomous agents** — fix once, immune forever. It provides agent payment intelligence: predict costs, optimize execution, fix failures. Powered by [VialOS Runtime](https://github.com/adrianhihi/vialos-runtime).\n\n### How does the 6-stage pipeline work?\n\n| Stage | Action | Description |\n|-------|--------|-------------|\n| Perceive | What broke? | Error diagnosis |\n| Construct | Find fixes | Generate solutions |\n| Evaluate | Score them | Rank solutions |\n| Commit | Execute | Apply fix |\n| Verify | Worked? | Validate success |\n| Gene | Remember | Store in Gene Map |\n\n### What is the Gene Map?\n\nA SQLite knowledge base scored by reinforcement learning. When the same error hits again, it's fixed in under 1ms — no diagnosis, no LLM call, no cost.\n\n### How do I use Helix?\n\n```typescript\nimport { wrap } from '@helix-agent/core';\n\nconst safeCall = wrap(myFunction, { mode: 'auto' });\nconst result = await safeCall(args);\n```\n\n### What are the benchmarks?\n\n| Benchmark | Result |\n|-----------|--------|\n| 1,083 Base Mainnet transactions (12hr A/B test) | Helix: 99.9% vs blind retry: 81.9% |\n| 5 frontier LLMs on `execution reverted` | All failed, PCEC: 100% |\n| Gene Map warm repair | 2,140ms → 1.1ms, $0.49 → $0.00 |\n\n### How do I install?\n\n```bash\nnpm install @helix-agent/core\n# or\npip install helix-agent-sdk\n```\n\n### Where can I find more info?\n\n- [npm: @helix-agent/core](https://www.npmjs.com/package/@helix-agent/core)\n- [PyPI: helix-agent-sdk](https://www.pypi.org/project/helix-agent-sdk/)\n- [Docker: adrianhihi/helix-server](https://hub.docker.com/r/adrianhihi/helix-server)\n\n### What license applies?\n\nMIT License.\n\n## License\n\nMIT\n\n## Links\n\n- [npm: @helix-agent/core](https://www.npmjs.com/package/@helix-agent/core)\n- [PyPI: helix-agent-sdk](https://pypi.org/project/helix-agent-sdk/)\n- [Docker: adrianhihi/helix-server](https://hub.docker.com/r/adrianhihi/helix-server)\n- [awesome-mpp](https://github.com/mbeato/awesome-mpp) — Listed in the MPP ecosystem registry\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusehelix%2Fhelix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusehelix%2Fhelix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusehelix%2Fhelix/lists"}