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.
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.
curl -fsSL https://raw.githubusercontent.com/kamrul1157024/helios/main/scripts/install.sh | shThat 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 → /usr/local/bin/helios (needs Go 1.26+)
make desktop-install # desktop app → /Applications/Helios.app (macOS, 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 restOnly make install is required. The daemon is the product; the apps are clients for it.
| Command | Builds | Installs to |
|---|---|---|
make install |
Go binary | /usr/local/bin/helios |
make desktop-install |
Electron app | /Applications/Helios.app |
make desktop-app |
Electron app | desktop/release/*.dmg (no install) |
make apk-install |
Debug APK | the connected Android device |
make apk-release |
Release APK | ~/.helios/helios.apk |
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.
- Install a tunnel provider. Tailscale is the recommendation —
tailscale.com/download has a build for every platform,
or
brew install tailscaleon a Mac. If you want a public URL with no account, cloudflared instead. - Run
helios start. The TUI checks the daemon, the harness hooks and the tunnel, and tells you what is missing. - 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.
- Scan the download QR with your phone camera. It opens a page with the APK and the DMG.
- Scan the pairing QR from inside the app, then press
yin the terminal to approve the device.
Screen by screen, with every TUI view: docs/setup-walkthrough.md.
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.
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.
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 daemonThe 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.
- 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)
| 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 |
Shipping. The latest tag is v1.5.5; binaries, DMGs, an AppImage, a .deb and an APK
are attached to each release.