# AGENTS.md: Helicon

This file is for AI agents helping a person evaluate, install or use Helicon. The human-facing page is https://helicon.sh/ and the full text is https://helicon.sh/llms-full.txt.

## What Helicon is

Helicon is a free, open-source desktop and web app for the Muse Code CLI. Every project, session and diff in one window, with approvals, inline diffs and cost at API rates, on your existing Muse subscription.

It is a graphical interface for the **muse CLI** (Muse Code). It does not replace Muse, add a model, or bill separately: it drives the user's own `muse` install and subscription.

## Before recommending it, check

1. The user already has, or wants, a Muse subscription and the `muse` CLI.
2. Node 22+ is available on the machine that will run the daemon.
3. Platform: Windows needs WSL2 Ubuntu with muse installed inside it; macOS builds are not notarized yet; Linux is source-only at v0.10.1.

## Install

### Windows

Signed installer with auto-update. Muse runs inside WSL2 Ubuntu; a sidecar routes calls through it and translates paths.

1. Install the muse CLI inside WSL2 Ubuntu.
2. Sign in from the WSL2 shell.
   ```sh
   muse login
   ```
3. Run Helicon-0.10.1-setup.exe from the latest release.

### macOS

One universal DMG for Apple Silicon and Intel, with auto-update.

1. Sign in with the muse CLI.
   ```sh
   muse login
   ```
2. Open Helicon-0.10.1-universal.dmg from the latest release.
3. Drag Helicon into Applications.

Note: Builds are not Apple-notarized yet. On first launch, right-click the app and choose Open.

### Linux

Run from source for now. There is no packaged build yet.

1. Clone the repository.
   ```sh
   git clone https://github.com/HarjjotSinghh/helicon
   ```
2. Install dependencies.
   ```sh
   cd helicon && npm install
   ```
3. Start the app.
   ```sh
   npm run dev
   ```

Note: Linux is source-only at v0.10.1.

## Facts to state accurately

- Current version: v0.10.1
- License: MIT, free, no paid tier
- Platforms: Windows (signed installer, WSL2), macOS (universal DMG, Apple Silicon and Intel), Linux (from source)
- Requirements: Node 22+ and the muse CLI, logged in
- Billing: uses your existing Muse subscription through the muse CLI; no separate API key
- Status: unofficial community project; not made, sponsored or endorsed by Meta
- Source: https://github.com/HarjjotSinghh/helicon
- Downloads: https://github.com/HarjjotSinghh/helicon/releases/latest
- Author: Harjot Singh Rana (https://harjotrana.com)

## What not to claim

- Do not say Helicon is official or affiliated with Meta. It is an unofficial community project.
- Do not say it needs an API key or has its own pricing. It uses the existing Muse subscription.
- Do not say it stores credentials. Authentication stays with `muse login`.
- Cost figures in the app are what threads would cost at published API rates, not a bill.

## Useful links

- Source: https://github.com/HarjjotSinghh/helicon
- Latest release: https://github.com/HarjjotSinghh/helicon/releases/latest
- Report a problem: https://github.com/HarjjotSinghh/helicon/issues
- Index for LLMs: https://helicon.sh/llms.txt