Helios

Fork of snoglobe/helios — generalized from ML-only experimentation to any domain: build optimization, performance benchmarking, infrastructure tuning, ML training, or any workflow that benefits from systematic trial-and-error.

Caution

Important: Helios does not currently have a permissions/security model. The agent runs basically unrestricted. You are responsible for any losses of data/other adverse outcomes from running it. If you have stuff you care about, then back it up (whether or not you use Helios, backing up is a good idea!), configure Helios to SSH into a container, or wait until it has a permissions system.

Claude mode will not work if you are running as root. It is recommended to instead run Helios on your local computer and set up your remote machine within Helios' SSH configuration. It will forward everything to your remote machine, no server required.

An autonomous experiment agent inspired by Andrej Karpathy's 'autoresearch'. Give it a goal — it designs experiments, runs them, measures results, and iterates until the goal is met.

What changed from upstream

The original Helios is purpose-built for ML training loops (loss/accuracy tracking, GPU monitoring, paper reading, hyperparameter sweeps). This fork generalizes the same powerful autonomous loop pattern to work across any experimentation domain:

• System prompt — domain-agnostic; no ML assumptions
• env_snapshot — detects Node, Python, Swift, Go, Rust, Java, Xcode (not just Python/GPU/CUDA)
• Bundled skills — generalized discover, ablation, writeup, consult
• Tool descriptions — generic examples (build flags, config params) instead of ML-specific (learning rate, batch size)
• doctor — reports all available toolchains
• init — no default ML metrics; you configure what matters for your domain

It can operate seamlessly over SSH (even multiple machines), keeps the model in a loop, has tools to view/compare metrics, shows metrics directly in the UI, and has a memory system.

You can leave it to work overnight and don't have to worry about it exiting the loop early to stupidly ask you something or because it has to wait for something. And hopefully you'll wake up to results.

Example Goals

> Reduce iOS app build time below 60 seconds
> Optimize Postgres query performance for the dashboard endpoint
> Find the best compiler flags for minimal binary size
> Train a 125M parameter GPT on TinyStories to loss < 1.0
> Benchmark and optimize nginx config for max requests/sec
> Find the fastest Docker build configuration for this project

Install

npm install -g @snoglobe/helios

Requires Node.js 20+.

Auth

Claude (default) — either:

• Install the Claude CLI and run claude login
• Or set ANTHROPIC_API_KEY and use /claude-mode api
• Claude CLI usage is ban-free; conforms to Anthropic's usage policy

OpenAI — OAuth login on first run (requires ChatGPT Plus or Pro).

Usage

helios [options]                    Interactive TUI
helios "prompt"                     TUI with initial prompt
helios -p "prompt"                  Print response and exit
helios -c                           Continue most recent session
helios -r <session-id>              Resume specific session

Options:
  -p, --provider <claude|openai>    Model provider (default: claude)
  --claude-mode <cli|api>           Claude auth mode (cli = Agent SDK, api = API key)
  -m, --model <model-id>            Model to use
  --headless                        Run without TUI (for scripting/hub agents)
  -v, --version                     Show version
  -h, --help                        Show help

Type a goal and Helios takes over:

> Reduce build time for this Xcode project below 60 seconds

It will analyze the build, identify bottlenecks, try different configurations, measure results, compare experiments, and keep iterating until the goal is met or you interrupt.

CLI Subcommands

Command	Description
helios auth login|logout|status	Manage provider authentication
helios sessions	List recent sessions
helios watch <machine:pid>	Stream task output + metrics live
helios replay <session-id>	Replay a past session
helios report [session-id]	Generate experiment writeup
helios discover [interests]	Background research discovery (runs until Ctrl+C)
helios init	Initialize project config (helios.json)
helios doctor	Diagnose setup (auth, machines, storage, config)
helios search "query"	Full-text search across session histories
helios export [session-id]	Export data to CSV/JSON
helios kill <machine:pid>	Kill a running task

Slash Commands

Command	Description
/switch <claude|openai>	Switch model provider
/model <model-id>	Set model
/models	List available models
/reasoning <level>	Set reasoning effort (Claude: medium high max / OpenAI: none minimal low medium high xhigh)
/claude-mode <cli|api>	Switch Claude auth mode
/machine add <id> <user@host[:port]>	Add remote machine (--key <path>, --auth <agent|key>)
/machine rm <id>	Remove machine
/machines	List machines and connection status
/metric [name ...]	Show metric sparklines
/metrics clear	Clear all metrics
/resume [n]	List or resume a past session
/writeup	Generate experiment writeup
/sticky <text>	Pin a note to the sidebar (always visible to model)
/stickies [rm <n>]	List or remove sticky notes
/memory [path]	Browse the agent's memory tree
/skills	List available skills
/hub [connect|disconnect|status]	AgentHub collaboration
/status	Provider, model, cost, state
/clear	Clear conversation
/help	Show all commands

Skills are also invocable as slash commands — e.g. /discover, /paper <url>, /ablation.

Keys

Key	Action
Ctrl+T	Task output overlay
Ctrl+G	Metrics overlay
Escape	Interrupt / close overlay
Ctrl+C	Interrupt / exit
Tab	Autocomplete command
Up Down	History / menu navigation
PageUp PageDown	Scroll conversation
Ctrl+A Ctrl+E	Start / end of line
Ctrl+W	Delete word backward
Ctrl+U	Clear line

Mouse scroll works in terminals that support SGR mouse reporting.

Remote Machines

Helios can run workloads on remote machines over SSH. The local machine is always available.

# Add a build server
/machine add build1 dev@10.0.0.5 --key ~/.ssh/id_rsa

# Add with custom port
/machine add server2 user@hostname:2222

Machines are stored in ~/.helios/machines.json and auto-connect on startup.

The agent prefers remote machines for heavy compute and uses local for lightweight tasks. Or if you don't have a remote machine.

How It Works

Helios runs an autonomous experiment loop:

1. Understand the goal — break it into experiments
2. Launch via remote_exec_background — stdout is captured, metrics are parsed live
3. Monitor via start_monitor — periodic check-ins review progress
4. Compare via compare_runs — keep improvements, discard regressions
5. Iterate — plan and launch the next experiment
6. Stop only when the goal is achieved or it hits an unrecoverable error

Metric Tracking

Processes print metrics to stdout. Helios parses them automatically:

# key=value format (detected via metric_names)
echo "build_time=42.3 binary_size=12.5 warnings=3"

# Custom patterns (detected via metric_patterns)
echo "Build completed in 42.3s"

Live sparklines appear in the dashboard. The agent uses show_metrics and compare_runs to make decisions.

Memory

Long sessions get checkpointed when the context window fills up. The agent's memory persists as a virtual filesystem:

/goal                    -> "Reduce Xcode build time below 60s"
/best                    -> "Run #3: parallel jobs=8, whole-module opt -> 58.2s"
/experiments/
  4521                   -> config, metrics, verdict
  4380                   -> config, metrics, verdict
/observations/
  parallel-helps         -> "8 parallel jobs reduces build by ~30% vs default"

After a checkpoint, the agent receives its memory tree and continues where it left off.

Skills

Skills are reusable prompt templates with tool access controls. Helios ships with bundled skills that are copied to ~/.helios/skills/ on first launch — edit them to customize.

Skill	Description
discover	Background research discovery — loops continuously, browses resources, stores findings in memory
paper <url>	Read a document and extract actionable insights for experiments
ablation	Systematic ablation study on the current best configuration
writeup	Generate a structured experiment writeup
consult	Ask the other AI provider for a second opinion

Create your own skills as Markdown files in ~/.helios/skills/ or .helios/skills/ (project-local). See the bundled skills for the format.

Consult

The agent can ask the other provider for a second opinion:

# If running on Claude, consult asks OpenAI (and vice versa)
consult("I'm stuck at 65s build time — what should I try next?")

Sleep & Wake

The agent can put itself to sleep with composable triggers:

sleep(reason: "waiting for build to finish", triggers: [
  { type: "process_exit", machine_id: "local", pid: 4521 },
  { type: "metric", metric_name: "build_time", threshold: 60, direction: "below" },
  { type: "timer", minutes: 120 }
])

When any trigger fires, the agent wakes up with context about what happened while it slept.

Project Config

Run helios init to create a helios.json in your project root:

{
  "provider": "claude",
  "model": "claude-opus-4-6",
  "defaultMachine": "local",
  "metricNames": ["build_time", "binary_size", "warnings"],
  "metricPatterns": {
    "build_time": "Build completed in ([\\d.]+)s"
  },
  "instructions": "This project uses Xcode with SPM. Focus on Swift compilation flags and module boundaries.",
  "experimentDir": "experiments",
  "notifications": {
    "channels": [{ "type": "desktop" }],
    "events": ["experiment_complete", "error"]
  }
}

Config is auto-discovered by walking up the directory tree. The instructions field is appended to the system prompt — use it for project-specific context.

Models

Claude:

• claude-opus-4-6[1m] — higher-end reasoning/coding, 1M context
• claude-opus-4-6 — higher-end reasoning/coding, 200k context (default)
• claude-sonnet-4-6[1m] — balanced speed vs reasoning, 1M context
• claude-sonnet-4-6 — balanced speed vs reasoning, 200k context

OpenAI (~400k context):

• gpt-5.4 — latest flagship, recommended (default)
• gpt-5.3-codex — codex
• gpt-5.3-codex-spark — research preview, text-only
• gpt-5.2-codex — codex
• gpt-5.2
• gpt-5.1-codex-max — max compute
• gpt-5.1
• gpt-5.1-codex — codex

Tools

The agent has access to 37 tools (33 core + 4 conditional AgentHub tools):

Tool	What it does
remote_exec	Run a quick command (ls, install, git clone)
remote_exec_background	Launch a long-running process with metric tracking
remote_upload / remote_download	rsync files between machines
read_file / write_file / patch_file	File operations on any machine
list_machines	Show configured machines
task_output	Tail stdout/stderr of a background task
kill_task	Kill a running process
show_metrics	Query metrics with sparklines and trends
compare_runs	Side-by-side comparison of two runs
clear_metrics	Wipe stale metric data
start_monitor / stop_monitor	Periodic monitoring loop
memory_ls / memory_read / memory_write / memory_rm	Persistent memory filesystem
web_search	Search the web (maps to provider's native search)
web_fetch	Fetch web pages and documentation
env_snapshot	Capture full environment snapshot (OS, toolchains, GPU, packages)
sweep	Launch parameter grid search across machines
exp_branch / exp_commit / exp_diff / exp_branches / exp_checkout	Git-based experiment branching
consult	Ask the other AI provider
writeup	Generate structured experiment report
sleep	Sleep with composable triggers (timer, process exit, metric threshold, file change, resource usage)
hub_push / hub_fetch / hub_log / hub_leaves / hub_diff	AgentHub git collaboration (if configured)
hub_post / hub_read / hub_reply	AgentHub discussion (if configured)

Data

Everything is stored locally in ~/.helios/:

~/.helios/
  helios.db          SQLite database (sessions, metrics, memory)
  machines.json      Remote machine configs
  auth/
    auth.json        OAuth tokens and API keys
  skills/            Skill templates (editable)
  preferences.json   Last provider, claude mode

Development

git clone https://github.com/snoglobe/helios.git
cd helios
npm install
npm run dev          # tsx src/index.tsx
npm run build        # tsc
npm start            # node dist/index.js

License

Apache-2.0