# Helios - Fast Version Control for AI Agents

[![GitHub release (latest by date)](https://img.shields.io/github/v/release/good-night-oppie/helios?style=for-the-badge)](https://github.com/good-night-oppie/helios/releases/latest)
[![GitHub Downloads](https://img.shields.io/github/downloads/good-night-oppie/helios/total?style=for-the-badge&color=brightgreen)](https://github.com/good-night-oppie/helios/releases)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=for-the-badge)](LICENSE)
[![Go Version](https://img.shields.io/badge/go-1.22+-00ADD8?style=for-the-badge&logo=go)](https://golang.org/)

[![Platform Support](https://img.shields.io/badge/platforms-Linux%20|%20macOS%20|%20Windows-success?style=for-the-badge)](https://github.com/good-night-oppie/helios/releases)
[![Architecture](https://img.shields.io/badge/arch-AMD64%20|%20ARM64-blue?style=for-the-badge)](https://github.com/good-night-oppie/helios/releases)
[![Ask DeepWiki](https://img.shields.io/badge/deepwiki-indexed-purple?style=for-the-badge)](https://deepwiki.com/good-night-oppie/helios)
[![README_ZH](https://img.shields.io/badge/中文文档-README__ZH.md-red?style=for-the-badge)](README_ZH.md)

**H**ybrid / **E**fficient / **L**ayered / **I**ncremental **O**bject **S**tate (Engine)

## Problems Helios Solves

**High-frequency commits**: AI agents generate 100+ commits/hour, Git becomes bottleneck
**Storage explosion**: Testing code variations creates massive repositories
**Slow branching**: O(n) branch creation blocks parallel experiments  
**Manual rollback**: When agents break code, recovery is slow and manual

## Quick Start

```bash
# Install
curl -sSL https://raw.githubusercontent.com/good-night-oppie/helios/master/scripts/install.sh | sh

# Use with existing project
cd my-project
echo "print('hello')" > test.py
helios commit --work .  # Fast commit of current directory
```

## How It Works

**Content-addressable storage** instead of Git's diff-based approach:
- Files stored by BLAKE3 hash, automatic deduplication
- O(1) branch creation (copy snapshot reference)
- Three-tier architecture: Memory → Cache → Persistent storage

## Quick Start: 5 Minutes to Faster AI Development

```bash
# Install Helios
curl -sSL https://raw.githubusercontent.com/good-night-oppie/helios/master/scripts/install.sh | sh

# Basic usage (v0.0.1 commands)
cd your-ai-project/

# Commit current working directory
helios commit --work .

# View statistics
helios stats

# Restore to a specific snapshot
helios restore --id <snapshotID>

# Compare snapshots
helios diff --from <id1> --to <id2>

# Extract files from snapshot
helios materialize --id <snapshotID> --out /path/to/output
```

## Real AI Coding Agent Use Cases

**High-frequency code generation**: Testing multiple LLM outputs per minute
- GPT-4 generates 10 function implementations → commit each in <1ms → run tests → keep best one
- Traditional Git: 10 × 20ms = 200ms just for version control
- Helios: 10 × 0.2ms = 2ms for version control

**Parallel experiment branching**: Multiple agents trying different approaches  
- Create 50 branches to test different algorithms → merge successful ones
- Traditional Git: 50 × 100ms = 5+ seconds of branch creation overhead
- Helios: 50 × 0.07ms = 3.5ms for all branches

**Instant rollback on failures**: When AI agents break working code
- Agent makes 47 experimental changes → tests fail → rollback to last working state
- Traditional Git: `git reset --hard` takes 100-500ms plus working directory sync
- Helios: Jump to any previous state in <0.1ms

## How It Works (Technical Overview)

### Why Helios Is Faster

**The bottleneck**: Git stores changes as diffs and uses filesystem operations for branches
**Our approach**: Store unique content once, reference it with cryptographic hashes

```
Traditional Git                    Helios Content-Addressable
├── commit1/                      ├── content/
│   ├── file1.py (full content)   │   ├── abc123... → "def func1():"
│   └── file2.py (full content)   │   ├── def456... → "def func2():"  
├── commit2/                      │   └── ghi789... → "def func3():"
│   ├── file1.py (diff)           └── snapshots/
│   └── file2.py (diff)               ├── commit1 → [abc123, def456]
└── commit3/                          └── commit2 → [abc123, ghi789]
    ├── file1.py (diff)
    └── file2.py (diff)
```

**Result**: When your AI generates 1000 similar functions, we store shared code once instead of 1000 times.

### Three-Layer Performance Architecture

```
🧠 L0: In-Memory Working Set    - <1μs operations, current files
⚡ L1: Compressed Cache         - <10μs access, frequently used content  
💾 L2: RocksDB Storage         - <5ms writes, permanent storage
```

**Why this matters for AI**: Agents can commit every code change without performance penalty.

### Performance: When It Matters

**Operations per second your AI can achieve:**

| Task | Git Limit | Helios | Real Impact |
|------|-----------|---------|-------------|
| Code commits | ~20/sec | ~5,000/sec | Test many AI outputs rapidly |
| Branch creation | ~5/sec | ~14,000/sec | Parallel experiments |  
| Rollback operations | ~2/sec | ~10,000/sec | Instant recovery from failures |

**Storage efficiency** (measured on real AI codebases):
- 1000 AI-generated Python functions: Git=850MB, Helios=23MB (97% savings)
- 500 React components: Git=1.2GB, Helios=45MB (96% savings)

**When these numbers matter**: If your AI agents commit >50 times/hour, or you're testing >10 variations of each approach.

## Integration with Your AI Tools

**Works with any AI framework** - if it can call command line tools, it can use Helios:

```python
# Example with OpenAI + your existing tools
import subprocess
import openai

for experiment in range(100):
    # Generate code with your AI
    response = openai.ChatCompletion.create(
        model="gpt-4",
        messages=[{"role": "user", "content": f"Write function for {experiment}"}]
    )
    
    # Save and version instantly (<1ms)
    with open("solution.py", "w") as f:
        f.write(response.choices[0].message.content)
    
    # Commit current state
    result = subprocess.run(["helios", "commit", "--work", "."], capture_output=True)
    snapshot_id = result.stdout.decode().strip()
    
    # Test the code
    if not run_tests():
        # Rollback to previous working state
        subprocess.run(["helios", "restore", "--id", previous_snapshot_id])
    else:
        previous_snapshot_id = snapshot_id  # Save working state
```

**Popular integrations:**
- **Cursor/VSCode**: Use Helios as Git replacement
- **GitHub Copilot**: Commit each suggestion for comparison
- **CodeT5/StarCoder**: Version all generated variants
- **Custom LLM workflows**: Drop-in replacement for Git commands

### In-process Rust bindings (for hot agent loops)

For multi-agent runtimes that cannot afford subprocess overhead per iteration,
Helios exposes a CGO c-archive (`cmd/heliosffi`) and a safe Rust wrapper
(`bindings/rust/helios-rs`) over the VST + VFSFork primitives.

```bash
# Build the c-archive (libhelios.a + libhelios.h)
make ffi-archive

# Run the Rust round-trip smoke test (~init→commit→fork→merge in microseconds)
make rust-smoke
```

```rust
use helios_rs::{BranchId, Vst};

let v = Vst::new();
v.write_file("agent.py", b"print('iter 0')")?;
let base = v.commit("seed")?;
let branch: BranchId = "main".into();
v.create_branch(&branch, &base)?;

// Propose without committing: fork-write-merge-or-discard
let fork = v.fork(&base)?;
fork.write("agent.py", b"print('iter 1')")?;
let new_id = fork.merge_into(&branch).map_err(|(_, e)| e)?;
```

See [`docs/ionq-integration.md`](docs/ionq-integration.md) for the full FFI
contract, error code table, and ionq Vector A/B integration notes.

## System Requirements

- **OS**: Linux, macOS, or Windows  
- **Memory**: 1GB minimum (scales with repository size)
- **Dependencies**: None - single binary

## Current v0.0.1 Limitations

This is an alpha release with core functionality:

**What works:**
- Fast commits with `helios commit --work <path>`
- Snapshot restoration with `helios restore --id <id>`
- Diff comparison with `helios diff --from <id> --to <id>`
- File extraction with `helios materialize`

**Coming in future versions:**
- Git import/export functionality
- `init`, `add`, `branch`, `checkout` commands
- Git-compatible command syntax
- Performance optimizations targeting <70μs commits

## Installation

```bash
# Install 
curl -sSL https://raw.githubusercontent.com/good-night-oppie/helios/master/scripts/install.sh | sh

# Use in existing project
cd your-ai-project/
helios commit --work .  # Commit current directory state

# Performance comparison (alpha - optimization ongoing)
time git commit --allow-empty -m "test"    # ~20ms
time helios commit --work .                 # Current: ~1-5ms, Target: <1ms
```

## Latest Release

🚀 **v0.0.1** is now available with:
- ✅ **Cross-platform binaries** for Linux/macOS/Windows (AMD64/ARM64)
- ✅ **PebbleDB storage** (pure Go, no CGO dependencies)
- ✅ **Core CLI commands** ready for AI workflows
- ✅ **One-line install** via curl script

[📦 Download from GitHub Releases](https://github.com/good-night-oppie/helios/releases/latest)

## Technical Details

See [TECHNICAL_REPORT.md](TECHNICAL_REPORT.md) for implementation details.

## Issues & Support

- **Issues**: [GitHub Issues](https://github.com/good-night-oppie/helios/issues)
- **Docs**: [DeepWiki Documentation](https://deepwiki.com/good-night-oppie/helios)
- **Status**: Alpha release