Luna

The pi agent system · public beta

Luna

An opinionated distribution of the pi coding agent. A permission gate for tool calls, governed delegation to sub-agents, verification, durable memory and bounded recovery, chosen together as profiles. One pi package, installed once.

A pi session under Luna: reads, edits and tests are allowed, a reviewer sub-agent is delegated, rm -rf ~ is denied, a force push waits for your approval, and the checks finish with recorded evidence.
Releasev0.3.0-beta.3 pi0.85.1 or newer Node.js22.19 or newer Package@satunix/pi-system LicenceMIT

Guard rails, not a sandbox.

The tool firewall gates every call and records every decision, but it is not an isolation boundary. Read what it does and does not protect in the security model.

01 · Install

Install once.

Needs Node.js 22.19 or newer, git and pi 0.85.1 or newer.

  1. Install pi

    $ npm install -g @earendil-works/pi-coding-agent
  2. Install Luna from the release tag

    $ pi install git:github.com/SATUNIX/luna@v0.3.0-beta.3
  3. Start pi

    $ pi
    # first start: the balanced profile is applied; /reload when asked
    # no models listed? sign in with /login

The repository is public, so no credentials are involved. Other channels, the scripted installer, uninstalling and troubleshooting are in Installation and Getting started.

ChannelCommandFor
Releasepi install git:github.com/SATUNIX/luna@v0.3.0-beta.3Normal use. The tag is the release.
NotesGitHub ReleasesRelease notes and source archives for each tag.
Installernode packages/core/install.ts --channel latest --profile balancedThe profile chosen up front, or a scripted install, from a clone.
Checkoutnode packages/core/install.ts --profile balanced --yesDeveloping Luna: pi loads the checkout in place.
Upgrade/updateInside pi: what pi, Luna and packages can update to.

02 · How it works

Gated, bounded, verified.

Three rules hold in every profile that loads them.

Three tool calls meet the Luna firewall: a read is allowed, a force push waits for your approval, and rm -rf ~ is denied; each decision lands in the audit record.
Tool firewall

Every tool call meets the gate.

The firewall parses each call into its effects and tiers it: routine work is allowed, riskier calls ask you, critical ones are denied, and every decision goes to the audit record. See the autonomy gate.

The lead agent delegates a bounded search to a scout and a diff to a reviewer while its budget meter drains, then reports back with evidence.
Delegation guard

Delegation stays bounded.

A lead agent hands sub-agents a bounded question and integrates what comes back. The delegation guard decides what each child loads, reserves its budget before it starts, and checks inside the child that its protections loaded. Repeated multi-step work runs as a workflow, where code rather than the model decides the next step. See agent orchestration.

A change goes to the checks; lint fails on the first pass and loops back for a fix, then tests, lint and types pass and the work is marked done.
Verify gate

Nothing counts as done unverified.

/verify and the agent's verify_completion tool run the project's check command and an isolated, read-only reviewer against the definition of done, and record the verdict. A review that did not run never reads as a pass. See concepts.

03 · Profiles

One package, five shapes.

A profile chooses which extensions, skills and prompts load, and the firewall mode. Switch with /profile.

The five profiles highlighted in turn: balanced, long-horizon, self-improving, engagement and lite.
ProfileFor
balancedEveryday work with verification and context helpers (the default).
long-horizonMulti-hour work and unattended runs in a container: goals, task graph, branches, delegation.
self-improvingResearch use: adds memory services, dual review and skill mining (experimental).
engagementAuthorised security engagements: strict firewall policy, scope and rules of engagement.
liteQuick tasks, small local models and short contexts.

What each profile loads is generated in the capability matrix.

04 · Documentation

Read before you trust it.

The documentation describes what the code does now, and names the test that pins each claim.

05 · Status

A public beta.

Tested, not stable.

Expect rough edges. Read Beta status for what is and is not covered, report problems in the issue tracker, and report vulnerabilities privately as SECURITY.md describes.