Luna

Luna is a capability layer for the pi coding agent: extensions, skills, prompts, themes and agent definitions in one pi package (@satunix/pi-system), with profiles that choose what loads. This is a beta; read Beta status first. Luna was previously published as pi-system, the name the pi package still uses, so commands and settings are unchanged.

Luna, the pi agent system: a pi session in which reads, edits and tests are allowed, a destructive delete is denied and a force push waits for approval

Use this guide if you want to:

  • install Luna and choose a profile, including lite for small local models
  • choose how hard the agent works and how much it delegates (Effort)
  • understand what the tool firewall does and does not protect (Security model)
  • keep pi, Luna and linked packages up to date (Updates)
  • run long tasks unattended in a container (Autonomous runs)
  • read the status bar, or configure model pricing (Status bar and costs)
  • build your own extension (Writing extensions)

Fast choices

Need Use
Small local model or tight context the lite profile
Daily coding with the standard guardrails the balanced profile (the default)
Long-running work with checkpoints, a task graph and delegation the long-horizon profile
A task that should keep going without you Autonomous runs
Container deployment for security engagements packages/container/README.md

Plain terms

  • Luna is the one package, installed from github.com/SATUNIX/luna.
  • A profile chooses which of Luna's extensions, skills and prompts load. Switch with /profile.
  • A channel is what you follow: latest (release tags), next (main), trunk (the opt-in integration-branch canary), or a pinned version.
  • Effort is a per-task dial (E1 to E5) for depth of work and delegation. It is not a permission and not a model setting.
  • The catalogue is the generated library of extensions in this repository.

Start here

  1. Getting started, then Installation for the reference. Every command, tool, environment variable and schema is in the interface reference.
  2. Pick a profile in Profiles; see Concepts for the vocabulary.
  3. Read the Security model, especially what it does not claim.
  4. Something wrong? Troubleshooting.
  5. Coming from the private GitLab source? Migration.

Searching the docs

python3 -m pip install --user -r requirements-docs.txt
npm run docs:serve

Open the local MkDocs URL and use the search box. Diagrams are Mermaid fenced blocks: GitHub renders them, and the local site shows them as code. npm run docs:mermaid checks that every diagram parses.

Prefer a scripted tool over typing the raw commands? See packages/core/helpers/README.md for install, setup, configure and update scripts (bash and PowerShell).