Getting started
Luna is one pi package. You install it once, then a profile chooses which of its
extensions load. It is delivered from its public git repository, github.com/SATUNIX/luna:
releases are vX.Y.Z tags and the next channel follows main.
This is a beta. See Beta status for what that means.
1. Requirements
- Node.js 22.19 or newer (pi's own requirement) and npm
- git
- pi itself:
npm install -g @earendil-works/pi-coding-agent
Luna supports pi 0.85.1 and newer; the version it is tested against is pinned in
package.json (currently 1.4.0). See Supply chain.
2. Install Luna
pi install git:github.com/SATUNIX/luna@v0.4.0-beta.0
pi clones the release into ~/.pi/agent/git/github.com/SATUNIX/luna and runs
npm install --omit=dev there, as it does for every git package. Luna has one runtime
dependency, quickjs-wasi (pinned), so this step fetches it from the npm registry.
To follow main instead of a release, leave the tag off:
pi install git:github.com/SATUNIX/luna. Switching channels later is
/update channel latest|next|trunk|X.Y.Z (trunk is the opt-in canary that follows the
integration branch).
Choosing the profile up front
With a bare pi install the first interactive start applies the balanced profile and asks for
/reload: pi lets only a command, not a start-up hook, reload itself, so that one reload stays. The
installer below applies the profile before pi starts, so it needs none (tests/clean-install-smoke.ts). To pick another
profile before starting, or to script the install, use the installer from a clone:
git clone https://github.com/SATUNIX/luna.git
cd luna
node packages/core/install.ts --channel latest --profile lite
--channel latest needs at least one release tag; until the first tag exists the installer stops
with a message saying so, and --channel next follows main. The installer keeps exactly one copy
of Luna registered, so this replaces a pi install copy rather than adding a second one.
3. Start pi
pi
The first time pi starts in a folder it asks whether to trust it (pi's own prompt: trusting lets
the project's .pi/ settings and extensions load). If pi warns No models available, run
/login to sign in to a provider or add an API key; Luna works with any provider pi supports.
Until you send a first prompt, the launch screen carries a short first-run card (how to get a model,
including /llama for a local one, and one prompt to try); it is shown until then and never again
(tests/control-center-smoke.ts). With no model configured Luna stays quiet about the context
window: it warns only for a model that reports none (tests/compaction-state-smoke.ts).
Then:
/menuopens the control centre./footer statusconfirms the status bar is active and shows every detail it drops when narrow./effortshows how hard the agent is set to work (Effort). The default is E3 Standard./profileshows and switches the profile (Profiles).
4. Profiles at a glance
| Profile | Good for |
|---|---|
balanced |
Daily coding with verification and context helpers (the default) |
long-horizon |
Multi-hour work with task graph, branches and delegation, and unattended runs |
engagement |
Authorised security engagements: strict firewall, scope and rules of engagement |
self-improving |
Research setup with Docker-backed memory (experimental) |
lite |
Quick tasks, small local models and short contexts |
Switch inside pi with /profile (a picker) or /profile <name>. The switch is verified and rolled
back if anything fails; nothing is reinstalled. The exact contents are in the generated
capability matrix.
5. Staying up to date
Once a day Luna checks in the background whether pi, Luna or a linked package can be
updated, and tells you. Run /update to apply updates. Every step is verified afterwards, and a
failed step is reported as failed. See Updates.
Working on Luna itself
Register a checkout in place instead: edits take effect on /reload.
git clone https://github.com/SATUNIX/luna.git && cd luna
npm ci --ignore-scripts
node packages/core/install.ts --profile balanced --yes
CLAUDE.md and CONTRIBUTING.md (both in the repository root) describe the development workflow.
If something goes wrong
See Troubleshooting.