Helix

A self-improving agent skill system for Claude Code. Helix treats skills as hypotheses, sessions as experiments, and uses an evolution loop (mutate, test, score, keep/discard) to continuously improve skill performance over time.

How It Works

Helix integrates with Claude Code's hooks system to automatically:

1. Plan sessions -- On startup, Helix loads skills, builds a dependency graph, assigns tournament variants, and injects skill context into Claude's conversation.
2. Collect signals -- During the session, every tool use, user message, permission denial, and correction is logged to a JSONL event stream.
3. Score performance -- On session end, Helix computes completion, correction, and efficiency signals, normalizes against a historical baseline, and produces a composite score.
4. Evolve skills -- Scores feed into active tournaments that compare baseline skills against mutant variants. Winners promote; losers are archived (never deleted).

SessionStart                           SessionEnd
    |                                      |
    v                                      v
 Load skills                         Read event log
 Build graph                         Compute signals
 Assign variants                     Normalize + score
 Inject context -----> Session -----> Feed tournaments
                    (tool use,          |
                     messages,          v
                     corrections)    Promote winners

Architecture

Helix is a 5-layer stack. Each layer depends only on the layers below it.

Layer	Directory	Purpose
1. Federated State	src/state/	Path resolution, config loading with cascade (project -> global -> defaults)
2. Skill Registry	src/skills/	Skill parsing, validation, typed contracts
3. Orchestrator	src/orchestrator/, src/graph/	Dependency graph, pipeline assembly, advisory reconciliation
4. Metrics Collector	src/metrics/	Event logging, signal computation, scoring, session finalization
5. Evolution Engine	src/evolution/	Tournaments (5A), mutation generation (5B), variant lifecycle
-- Discovery	src/discovery/	K-means clustering + LLM-assisted skill discovery from session data
-- Hooks Integration	src/hooks/	Wires layers 1-5 into Claude Code's session lifecycle

Getting Started

Prerequisites

• Node.js >= 20
• A project where you use Claude Code

Install

# Clone and build
git clone <repo-url> helix
cd helix
npm install
npm run build
npm link    # makes 'helix' available as a command

# Initialize in your project
cd /path/to/your/project
helix init

helix init does three things:

1. Creates .helix/ with skills/, sessions/, tournaments/, and a default config.yaml
2. Copies the 6 built-in skills into .helix/skills/
3. Writes hook registrations to .claude/settings.local.json (project-scoped, not committed to git)

Usage

# Check if Helix is working and how skills are performing
helix status

# List recent sessions with scores
helix sessions
helix sessions 50    # show last 50

# Deep dive into a single tournament
helix tournament debugging

# Run tournament evaluation on accumulated session data
helix evolve

# Scan for mutation candidates (skills that could improve)
helix mutate

# Generate a variant for a specific skill
helix mutate debugging

# List pending variants awaiting approval
helix mutate --list

# Approve or reject a variant
helix mutate --approve debugging/v1
helix mutate --reject debugging/v1

# Import sessions from existing Claude Code transcripts
helix import                          # auto-discover for current project
helix import path/to/session.jsonl    # import specific file

# Discover new skills from session patterns
helix discover                          # local mode (K-means, zero tokens)
helix discover --llm                    # LLM-assisted discovery
helix discover --auto                   # LLM + auto-approve (full pipeline)
helix discover --list                   # show pending candidates
helix discover --approve exploration    # approve a candidate
helix discover --reject exploration     # reject a candidate

# View and edit configuration
helix config                          # show all config values
helix config get evolution.auto_mutate
helix config set evolution.auto_mutate true

# Auto-generate mutations for underperforming skills
helix mutate --auto

# Machine-readable output (works with status, sessions, tournament, import, config)
helix status --json
helix sessions --json

# Remove Helix hooks (preserves session data and tournaments)
helix deinit

Uninstall

helix deinit

Removes Helix hook entries from .claude/settings.local.json but preserves .helix/ (your session data and tournament history are kept).

Built-in Skills

Helix ships with 6 baseline skills that cover the core development loop:

Skill	Triggers On	Purpose
task-understanding	Any input (low confidence)	Clarify requirements before acting
implementation	Build/implement patterns	Write code following project conventions
testing	Test/spec/coverage patterns	Write tests that verify behavior
code-review	Review/check patterns	Review for correctness and convention adherence
debugging	Error/bug/fail patterns (high confidence)	Diagnose systematically without guessing
verification	Post-implementation	Verify work before claiming completion

Skills are structured markdown files with typed YAML contracts defining inputs, outputs, triggers, dependencies, and metrics. See any file under skills/ for the format.

Configuration

Helix loads config from .helix/config.yaml with these defaults:

score_weights:
  completion: 0.4       # task done, tests passed, committed
  correction: 0.35      # human overrides, permission denials
  efficiency: 0.25      # tool use relative to baseline

gates:
  tier1_min_sessions: 5
  tier1_outlier_threshold: 0.15
  tier2_min_sessions: 12
  tier2_p_value: 0.1
  tier3_min_sessions: 20
  tier3_p_value: 0.05

efficiency_baseline_window: 20  # sessions for normalization

evolution:
  dormancy_days: 14
  margin_delta: 0.01
  auto_mutate: false
  max_active_variants: 3

Tiers control statistical rigor: Tier 1 uses deterministic comparison (fast, low confidence), Tier 2 uses bootstrap resampling, and Tier 3 requires more sessions and a tighter p-value. Skills promote through tiers as evidence accumulates.

Session Lifecycle

When Claude Code starts a session with Helix installed:

1. SessionStart fires -> Helix loads the skill registry, builds the dependency graph, runs the orchestrator to produce a pipeline, assigns tournament variants (baseline vs. mutant), writes a session_plan event to JSONL, and returns skill bodies as additionalContext injected into Claude's context.

2. Mid-session events (UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PermissionDenied) are appended to the session's JSONL log.

3. SessionEnd fires -> Helix reads the session plan back from JSONL, calls finalizeSession to compute signals and a composite score, saves a SessionLog, and feeds the score into any active tournaments the session participated in.

On resume, Helix skips re-planning and re-injects the same skill context by reading the existing session_plan event.

Evolution Loop

The evolution engine runs tournaments to compare skill variants:

1. Mutation -- Identify underperforming skills, assemble context (baseline, failure patterns, tournament history), generate a variant.
2. Assignment -- Each new session is blindly assigned to either the baseline or a variant arm (stratified deficit counter + seeded RNG prevents bias).
3. Evaluation -- After enough sessions, the evaluator compares arms using tier-graduated statistical tests.
4. Promotion -- Winners replace the baseline. Losers are archived (never deleted -- full audit trail).
5. Dormancy -- Skills with no recent sessions are honestly reported as dormant rather than silently stale.

Key principles:

• Skills are hypotheses, sessions are experiments
• Blind assignment prevents placebo effects
• Archival not deletion (rollback always possible)
• Human veto at every gate
• Federated evolution (project-local -> global with evidence)

Project Structure

helix/
  src/
    state/          Config loading, path resolution
    skills/         Parser, registry, validator
    graph/          Dependency graph, resolver, pipeline assembly
    orchestrator/   Pipeline orchestration, advisory reconciliation
    metrics/        Event logging, signals, scoring, finalization
    evolution/      Tournaments, assignment, evaluation, mutation
    discovery/      Skill discovery from session data (K-means, LLM)
    hooks/          Session lifecycle handlers, CLI router, installer
    index.ts        Barrel exports
  skills/           6 built-in baseline skills
  tests/            430 tests across 57 files
    state/          Config, paths
    skills/         Parser, registry, validator
    graph/          Graph, resolver, pipeline
    orchestrator/   Orchestrator, advisory
    metrics/        Signals, corrections, scoring, finalization, normalization
    evolution/      Tournaments, assignment, evaluation, mutation, bootstrap
    discovery/      Features, K-means, interpreter, LLM, candidate store, skill writer
    hooks/          Handler, session-start, session-end, install
    integration/    Full pipeline, evolution, mutation, metrics, session lifecycle
  docs/
    specs/          Design specifications
    plans/          Implementation plans

Development

# Install dependencies
npm install

# Run tests (430 tests, 57 files)
npm test

# Watch mode
npm run test:watch

# Build
npm run build

Design Docs

• Foundation Design -- Layers 1-4, skill contracts, orchestrator
• Tournament Runner Design -- Layer 5A, tier-graduated evaluation
• Mutation Engine Design -- Layer 5B, variant generation
• Session Lifecycle Hooks Design -- End-to-end integration with Claude Code
• Skill Discovery Design -- Mining session data for new skill categories

License

MIT