helios

A head for headless coding harnesses.
Claude Code and OpenAI Codex run in a terminal with no UI of their own.
Helios owns those terminals and puts a desktop app, a phone and a tunnel in front of them.

curl -fsSL https://raw.githubusercontent.com/kamrul1157024/helios/main/scripts/install.sh | sh

   

_{The desktop app, and the same sessions on the phone: the list, a live transcript, and the real terminal.}

---

What it is

You have five agent sessions open across three projects. One is blocked on a permission prompt. One finished an hour ago. One died. You cannot tell which is which without walking your terminal tabs.

Helios is a daemon that runs each session in a terminal it owns, watches the harness hooks, and shows you every session in one place — on your desktop, on your phone, or in the terminal. When a session needs you, you hear about it and can answer from wherever you are.

• Desktop app — every session on every machine in one sidebar, with the live terminal, the transcript, git diffs, approvals and the file tree
• Mobile app — the same sessions on your phone, and a notification the moment one blocks on a permission
• Tunnel — nine providers, one keypress, so the phone can reach the daemon without you configuring a network

Everything runs on your machine. No cloud, no accounts, no subscription.

Install

curl -fsSL https://raw.githubusercontent.com/kamrul1157024/helios/main/scripts/install.sh | sh

That builds the daemon and the desktop app from source, installs them, and drops you into helios start. It needs Go 1.26+, and Node 22+ for the app — if either is missing it says where to get it, and it will install the daemon on its own if you would rather add Node later.

Or do it by hand:

git clone https://github.com/kamrul1157024/helios.git && cd helios

make install           # daemon + CLI  → ~/.local/bin/helios                     (needs Go 1.26+)
make desktop-install   # desktop app   → Applications, or apt (macOS/Linux, needs Node 22+)
make apk-install       # Android app   → the device on adb                      (needs Flutter 3.32+)

helios start           # the TUI checks your setup and walks you through the rest

Only make install is required. The daemon is the product; the apps are clients for it.

The two install targets build the newest published release, whatever your checkout is sitting on. The -dev pair builds the checkout itself, which is what you want while working on it.

Command	Builds	Installs to
make install	the newest release, from source	~/.local/bin/helios
make install-dev	this checkout	~/.local/bin/helios
make desktop-install	the newest release's Electron app	/Applications/Helios.app (macOS) or via apt (Linux)
make desktop-install-dev	this checkout's Electron app	/Applications/Helios.app (macOS) or via apt (Linux)
make desktop-app	Electron app	desktop/release/*.dmg (no install)
make apk-install	Debug APK	the connected Android device
make apk-release VERSION=x.y.z	Release APK, named that number	~/.helios/helios.apk

The daemon goes to a directory you own, and the install finishes the job rather than leaving you a list of things to do:

• Earlier installs are deleted, so exactly one helios is left on your machine. Installs used to go to /usr/local/bin, which usually belongs to root — removing that one asks for your password, once, and it is the only step that ever does. A copy installed by Homebrew or apt is left alone for that package manager to remove.
• ~/.local/bin is put on your PATH if it is not there already, by a line written to .zshrc, .bash_profile or config.fish. Open a new terminal afterwards.
• A running daemon is restarted, or it would go on serving the build you just replaced. Sessions and the tunnel stay up: each session is its own process and outlives the daemon.

Somewhere else instead: make install PREFIX=/usr/local/bin, with sudo in front of it if that path is the system's.

Prebuilt DMGs, an AppImage, a .deb and an APK are attached to every release.

For iPhone there is no prebuilt build: you connect the phone by cable and build it locally. See docs/ios.md.

Setup

1. Install a tunnel provider. Tailscale is the recommendation — tailscale.com/download has a build for every platform, or brew install tailscale on a Mac. If you want a public URL with no account, cloudflared instead.
2. Run helios start. The TUI checks the daemon, the harness hooks and the tunnel, and tells you what is missing.
3. Pick your tunnel. Tailscale Serve keeps the daemon inside your tailnet and the hostname never changes; the cost is that the VPN has to be on at the phone end. Tailscale Funnel gives you a stable public URL instead. Cloudflare needs no account but its URL changes on every restart, so paired devices have to be re-pointed.
4. Scan the download QR with your phone camera. It opens a page with the APK and the DMG.
5. Scan the pairing QR from inside the app, then press y in the terminal to approve the device.

Screen by screen, with every TUI view: docs/setup-walkthrough.md.

From your phone

Start a session anywhere:

$ helios new "fix the auth bug in login.go"

When Claude asks for permission your phone buzzes, and you answer it there:

The phone is not a read-only mirror. It carries the session list across every paired machine, the live transcript, the permission mode, the same terminal the desktop app attaches to, the session's git worktrees and its files.

Helios can also read the session out loud as it works — tool calls, permission requests, completions and errors — so you can follow along without looking.

Desktop app

On first launch the app pairs itself with the daemon on the same machine, with no QR code and no token. Add host in the sidebar pairs it with remote machines the same way the phone does.

The sidebar lists every session on every paired host. The right side is the selected session across five tabs: Chat, Terminal, Git, Approvals and Files. Tool calls in the transcript collapse to one line and expand in place, so a long run stays readable.

CLI

helios start                    # TUI: status, tunnel picker, pairing QR codes
helios new "refactor auth"      # create a session
helios sessions                 # list sessions
helios attach a3f1c2e8          # attach to a session's terminal
helios devices                  # list / approve / revoke paired devices
helios tunnel                   # start, stop or inspect the tunnel
helios logs                     # tail the daemon log
helios stop                     # stop the daemon

How it works

The daemon runs each session in a terminal host it owns (helios ptyhost) and keeps the output in memory, so any number of clients can read it at once. Clients hold no state: the desktop app, the phone, the TUI and the CLI all talk to the same HTTP API and follow the same SSE stream. Claude Code and Codex attach through the provider registry in internal/provider, which is also where the next harness will plug in.

Diagrams, endpoints and the on-disk layout: docs/architecture.md.

Requirements

• Go 1.26+ (the version in go.mod)
• A headless coding harness — Claude Code or OpenAI Codex today
• Node 22+ (only to build the desktop app from source)
• Flutter 3.32+ (only to build the mobile app from source)
• Xcode 15+ and a cabled iPhone (only to install the iOS app; it is never prebuilt)

Docs

Setup walkthrough	Every screen of the pairing flow
Architecture	Diagrams, endpoints, file layout, tech stack
iOS	Building the iPhone app yourself
Specs	Design documents — intent, not merged state
AGENTS.md	Conventions and procedures for coding agents

Status

Shipping. The latest tag is v1.5.5; binaries, DMGs, an AppImage, a .deb and an APK are attached to each release.

License

Elastic License 2.0 (ELv2)