Interface reference
Auto-generated by
packages/core/reference.tsfrom eachextension.jsonand theregisterCommand/registerToolcalls in the extension sources. Do not hand-edit; runnpm run catalog.npm run verifyfails when this page is stale.
Luna's external interface: what an operator types, what the model can call, the environment it reads and the files it is configured by. Which extensions a profile loads is in the capability matrix; each extension's purpose is in the extension catalogue. A command or tool exists only while its extension is loaded.
Slash commands
Typed at the pi prompt as /name [arguments]. The arguments are free text the command parses;
each description below is the one pi shows, and names the forms it accepts. A command prints its
result in the session (a notice, a picker or a status block) and changes only the state it
describes. Commands are for the operator: the model cannot call them.
| Command | Extension | Description | Documented in |
|---|---|---|---|
/auto |
tool-firewall |
Auto mode: /auto [status|on|off|explain [n]|learned|forget |
autonomy-gate |
/autonomy |
autonomy-run |
Start and manage autonomous runs in a hardened container: /autonomy templates|init|plan|start|status|pause|resume|steer|cancel|promote|export|inbox|boundary|reconfigure. A run only starts after you confirm its boundary. | autonomy |
/away |
tool-firewall |
/away [--for 2h] [--budget 5] | off | status. Automatic approvals for a bounded time and budget; anything that would need your approval is refused with the reason. Needs the terminal of an interactive session. | autonomy |
/boost |
progress-guard |
Auto-boost control: /boost reassesses now; /boost [on|off|status]. 'on' auto-nudges on detected loops this session. | efficiency-and-loops |
/capture |
tool-capture |
Tool I/O capture: status, or prune to apply the disk budget now. |
tool-capture |
/caveman |
caveman |
Toggle/set output compression: /caveman [on|off|lite|full|ultra|micro|status] | control-center |
/checkpoints |
git-checkpoint |
List this session's working-tree checkpoints (kept under refs/luna/checkpoints, never on your branch) | profiles |
/clear |
session-helpers |
Start a new session (asks first). --handoff writes HANDOFF.md before leaving. | control-center |
/compact-threshold |
trigger-compact |
View or change the kit auto-compact trigger: /compact-threshold [amount|off|on|reset], e.g. /compact-threshold 500k | INSTALL |
/compaction |
session-helpers |
Show or change auto-compaction: /compaction [status|on|off|trigger on|trigger off] | model-resilience |
/compress |
compress |
Instant deterministic compaction: keeps user asks and assistant replies, drops tool output. No model call. Optional note: /compress |
control-center |
/console |
web-console |
Start/stop the bundled Pi Console web UI. Usage: /console [start|stop|status|open]. | web-console |
/effort |
effort |
Choose how deep and broad the agent works and how much it delegates: /effort (picker), /effort <minimal\|focused\|standard\|thorough\|exhaustive \| E1..E5>, /effort status, /effort reset, /effort memento [status\|on\|off] [provider/model] (per-model Memento opt-in, off by default), /effort ultracode [--size N] [--budget N\|none] \| off (alias uc, or e5 --standing: E5 plus standing workflow mode). Independent of thinking level, profile and permissions. |
effort |
/engagement |
conductor |
Manage engagement lifecycle: /engagement start | status | phase |
security |
/engagement:actions |
engagement-governance |
Show where action approvals are audited | security |
/engagement:reload-policy |
engagement-governance |
Reload engagement policy metadata and scope/ROE files from disk immediately | security |
/engagement:status |
engagement-governance |
Show engagement data-root and governance status | security |
/firewall |
tool-firewall |
Tool firewall: /firewall [status | list | revoke |
autonomy-gate |
/footer |
custom-footer |
Status bar: /footer default|light|heavy, /footer on|off, /footer status (every detail the bar drops when narrow), /footer reload, /footer todos on|off, /footer ascii on|off, /footer cat on|off, /footer config | troubleshooting |
/goal |
goal-core |
Set or clear the mission goal: /goal |
control-center |
/handoff |
handoff |
Write a handoff note to HANDOFF.md. Usage: /handoff |
control-center |
/improve |
self-improvement |
Self-improvement cycle: mine traces → propose a reviewable diff. /improve arm [id] applies a written proposal (default: the newest) to AGENTS.md. |
control-center |
/loop |
autonomous-loop |
Enable autonomous loop: /loop |
efficiency-and-loops |
/memory |
memory-vault |
Memory vault: /memory [status|recent|search |forget |
memory |
/menu |
control-center |
Open the control centre: profile, effort, thinking, security and every page (also …) | control-center |
/orchestrate |
orchestrator |
Control autonomous delegation: /orchestrate [on|off|auto|status] | agent-orchestration |
/orchestrate-implement-review |
orchestrator |
Delegate the full plan → implement → review loop: /orchestrate-implement-review |
agent-orchestration |
/orchestrate-plan |
orchestrator |
Delegate planning only, no changes: /orchestrate-plan |
agent-orchestration |
/plan |
plan-mode |
Toggle plan mode (read-only exploration) | — |
/profile |
session-helpers |
Switch the Luna profile in place, all-or-nothing: /profile picker, /profile <name>, /profile status (effective configuration), /profile list. Rewrites the kit's settings entry (keeping overrides.json customisations), verifies the result, rolls back on any failure, then reloads - no restart. |
security |
/remember |
memory-vault |
Save a memory: /remember |
memory |
/remote |
remote-control |
Drive this pi from the pi remote Android app: share this session, link phones, manage the host | remote-control |
/review |
dual-review |
Spawn a reviewer agent on the current git diff. Optionally pass a path argument. | control-center |
/save |
save |
Write a check-in snapshot of this session to disk without compacting. Usage: /save [--project "Name"] [--no-update] [note] | control-center |
/security |
tool-firewall |
/security [off|balanced|guarded|strict] | status | explain [level] | reset. Changes apply immediately. Weakening needs a confirmation at the terminal of an interactive root session. off is unavailable. | control-center |
/skills |
skill-router |
List installed skills: which are listed in the prompt, which are on-demand (skill_search / hints), and their triggers. | control-center |
/status |
control-center |
Show what is installed and running, one line each with the command for detail | control-center |
/tips |
custom-footer |
Show or hide usage tips while the agent works: /tips on|off | control-center |
/todos |
todo |
Show this session's todo list and its file path | control-center |
/trace |
trace-ledger |
Summarize the action ledger (.pi/trace.jsonl): call counts, errors, and repeated reads. | efficiency-and-loops |
/trigger-compact |
trigger-compact |
Trigger compaction immediately, optionally with custom instructions | — |
/undo |
git-checkpoint |
Put the working tree back to the latest checkpoint (or /undo |
profiles |
/update |
kit-update |
Check for and apply updates to pi, Luna (on its latest/next/trunk channel, from git or npm) and linked packages: /update, /update status, /update all\|kit\|pi\|packages, /update channel <latest\|next\|trunk\|X.Y.Z>. |
updates |
/usage |
trace-ledger |
Where this session's tokens and money went: by model, child and tool, cache hit rate, the largest results. | status-bar-and-costs |
/verdicts |
verifier-board |
Show the verifier board and what done means here. /verdicts clear resets the board. | packages/extensions/src/verifier-board/README.md |
/verify |
verify-gate |
Check that the goal, todos, and requests are done: runs the project check (if any) and an independent read-only reviewer. /verify [focus] | INSTALL |
/workflows |
subagent |
Every workflow, subagent and autonomous run, live or finished: list them, show one, stop one or all. … | workflows |
Tools
Called by the model, never typed. Every call passes through the tool firewall first
(Security model). Parameters are a JSON object with the fields below (? marks an
optional one); a tool returns text content to the model, and an error result when it refuses or fails.
ask_human
Extension human-console. Ask the operator a concise clarifying question.
| Parameter | Type | Description |
|---|---|---|
question |
string | — |
options? |
string[] | — |
context? |
string | — |
timeoutMs? |
number | — |
branch_create
Extension branch-lab. Create a git worktree branch for isolated work.
| Parameter | Type | Description |
|---|---|---|
taskId? |
string | Task identifier |
baseBranch? |
string | Base branch or commit |
branch_discard
Extension branch-lab. Remove a branch-lab worktree and lease. Refuses a worktree with uncommitted changes or a branch not merged into HEAD unless force is true.
| Parameter | Type | Description |
|---|---|---|
taskId? |
string | Task identifier |
force? |
boolean | Discard even uncommitted changes and unmerged commits |
branch_list
Extension branch-lab. List branch-lab leases.
Parameters: none.
branch_merge
Extension branch-lab. Merge a branch-lab branch into the current git branch.
| Parameter | Type | Description |
|---|---|---|
taskId? |
string | Task identifier |
strategy? |
string | Optional git merge strategy: ort, recursive, resolve, ours, or subtree |
branch_switch
Extension branch-lab. Return the worktree path for an isolated branch.
| Parameter | Type | Description |
|---|---|---|
taskId? |
string | Task identifier |
dispatch_specialist
Extension conductor. Dispatch a materialized specialist in an isolated child process after durably enforcing Conductor recursion and per-run dispatch caps.
| Parameter | Type | Description |
|---|---|---|
agent |
string | Materialized synthesized agent name |
task |
string | Scoped specialist task |
dispatch_validator
Extension conductor. Run an isolated read-only validator with only raw evidence and requirement, then parse and record its verdict atomically.
| Parameter | Type | Description |
|---|---|---|
findingId |
string | Stable kebab-case finding identifier |
evidence |
string | Raw evidence only: request/response, PoC, diff, or test output |
requirement |
string | Requirement or scope stanza the evidence must satisfy |
dual_review
Extension dual-review. Run a second-agent review on a diff or file. Returns immediately; review arrives as a displayed result without starting another turn.
| Parameter | Type | Description |
|---|---|---|
content |
string | Diff or code to review |
loop_complete
Extension autonomous-loop. End the autonomous loop (/loop) because its goal is met. Call once the work is done and verified.
| Parameter | Type | Description |
|---|---|---|
reason |
string | Why the goal is met (for example, the check that now passes) |
mem0_add
Extension memory-mem0. Add a memory to the mem0 service. Requires MEM0_API_URL env var and a running mem0 instance.
| Parameter | Type | Description |
|---|---|---|
text |
string | Memory text to store |
mem0_search
Extension memory-mem0. Search memories in the mem0 service. Requires MEM0_API_URL env var.
| Parameter | Type | Description |
|---|---|---|
query |
string | Search query |
limit? |
number | Max results (default 5) |
memory_delete
Extension memory-local. Delete a memory entry by ID.
| Parameter | Type | Description |
|---|---|---|
id |
string | Memory ID to delete |
memory_forget
Extension memory-vault. Forget a memory by id, name or path (moved to the vault's .trash, recoverable). Use when the user says a memory is wrong or asks to forget it.
| Parameter | Type | Description |
|---|---|---|
id |
string | — |
memory_save
Extension memory-vault. Save a durable memory to the vault. Use when asked to remember something, for a stated preference, or for a non-obvious decision or gotcha that should outlive the session. Updates an existing memory rather than duplicating it. Do not save what code or git history already records.
| Parameter | Type | Description |
|---|---|---|
title |
string | Short title (becomes the note name) |
content |
string | The memory itself: the fact, and for decisions/gotchas the why and how to apply it |
type? |
see source | — |
tags? |
string[] | — |
scope? |
"project" | "global" | project (default) or global (applies in every project, e.g. personal preferences) |
pinned? |
boolean | Show at the start of every session in this project |
memory_search
Extension memory-local. Search persistent local memory by semantic vector when configured, otherwise by keyword.
| Parameter | Type | Description |
|---|---|---|
query |
string | Search query |
limit? |
number | Max results (default 5) |
memory_search
Extension memory-vault. Search saved memories (this project and global) by keywords. Returns titles, types, snippets and note paths.
| Parameter | Type | Description |
|---|---|---|
query |
string | — |
scope? |
"project" | "global" | "all" | — |
limit? |
number | — |
memory_stats
Extension memory-local. Return count and date range of stored memories.
Parameters: none.
memory_store
Extension memory-local. Save a note to persistent local memory. Use for facts, decisions, or context that should survive across sessions.
| Parameter | Type | Description |
|---|---|---|
text |
string | The memory text to store |
tags? |
string[] | Optional tags for retrieval |
record_verdict
Extension verifier-board. Record a verdict from a check or reviewer, never your own grade. The mission is not done until all verdicts pass.
| Parameter | Type | Description |
|---|---|---|
source |
string | Who produced it: 'reviewer', 'tests', 'lint' |
pass |
boolean | — |
summary |
string | One line, or what must be fixed |
evidence? |
string | Command and exit code, or a file path |
skill_archive
Extension skill-forge. Archive a superseded skill proposal or skill into .pi/skill-archive/ (non-destructive move; an existing archive of the same name is kept and the new one gets a
| Parameter | Type | Description |
|---|---|---|
skill_name |
string | Skill name to archive |
reason? |
string | Reason for archiving |
skill_score
Extension skill-forge. Score Luna against its own eval harness (real, eval-tied number) as the skill's regression baseline.
| Parameter | Type | Description |
|---|---|---|
skill_name |
string | Skill name being evaluated (recorded in the score record) |
skill_search
Extension skill-router. Search all installed skills (runbooks for specific kinds of work) — including ones not listed in the system prompt. Returns the best matches with their SKILL.md paths; read the one that fits before doing the work.
| Parameter | Type | Description |
|---|---|---|
query |
string | What you are about to do, in a few words |
limit? |
number | Max results (default 5) |
skill_synthesise
Extension skill-forge. Mine the trace-ledger and synthesise a candidate SKILL.md into .pi/skill-proposals/ for review.
| Parameter | Type | Description |
|---|---|---|
skill_name |
string | Name for the synthesised skill (kebab-case) |
category? |
string | Skill category (default: efficiency) |
trace_path? |
string | Path to a trace JSONL to mine (default: .pi/trace.jsonl) |
StructuredOutput
Extension subagent. Return your final result. Call this exactly once, when the work is done, with {"…":
Parameters: built from a shared schema; see the extension source.
subagent
Extension subagent. Delegate to subagents with isolated context: one agent+task, or parallel tasks. Roles: scout, planner, implementer, reviewer, plus ~/.pi/agent/agents. A subagent cannot see this conversation: make each task self-contained; background detaches long work.
Parameters: built from a shared schema; see the extension source.
task_clear
Extension task-graph. Remove every task from the shared task graph, to start a new plan or mission in the same project.
Parameters: none.
task_complete
Extension task-graph. Mark a task as done.
| Parameter | Type | Description |
|---|---|---|
id |
string | Task ID |
task_create
Extension task-graph. Create a task in the shared task graph. Returns its id. Use depends_on to order work.
| Parameter | Type | Description |
|---|---|---|
title |
string | Task title |
description? |
string | Task detail |
depends_on? |
string[] | IDs of prerequisite tasks |
task_list
Extension task-graph. List tasks in the graph, optionally filtered by status.
| Parameter | Type | Description |
|---|---|---|
status? |
string | Filter by status |
task_next
Extension task-graph. Return the next actionable task: a pending task whose dependencies are all done. Claims it (marks in_progress) so a second call does not hand out the same task twice. A claim not renewed by task_update within the lease (PI_KIT_TASK_GRAPH_LEASE_MS, default 1 hour) returns to pending.
Parameters: none.
task_update
Extension task-graph. Update a task's status (pending|in_progress|done|blocked) and/or notes.
| Parameter | Type | Description |
|---|---|---|
id |
string | Task ID |
status? |
string | pending | in_progress | done | blocked |
notes? |
string | Progress notes |
todo
Extension todo. The session's todo list. Actions: list, add (text or items), start, done, toggle, remove (id), clear. Add the plan first, then start and finish items. Returns the whole list.
| Parameter | Type | Description |
|---|---|---|
action |
"list" | "add" | "start" | "done" | "toggle" | "remove" | "clear" | — |
text? |
string | For add |
items? |
string[] | Several texts, for add |
id? |
number | For start, done, toggle, remove |
verdict_status
Extension verifier-board. Report the definition-of-done board: each recorded verdict, the goal, the todo and task progress, the latest verification report, and whether the mission may be considered complete.
Parameters: none.
verify_completion
Extension verify-gate. Run an independent check that the task is done. It runs the project check command if one exists, then a read-only reviewer that compares the repository against the goal, todo list, task graph, and recent user requests. Use it before you report that the work is complete. It records the result on the verifier board.
| Parameter | Type | Description |
|---|---|---|
focus? |
string | The acceptance criteria or scope to check. Leave empty to use the goal, todos, and recent requests. |
workflow
Extension subagent. Run a JavaScript workflow script in the background (deterministic orchestration: agent(), parallel(), pipeline(), phase(), log(), args, budget, workflow()). Pass exactly one of script (inline, starting export const meta = {name, description, phases}), scriptPath or name (registered). Returns runId and scriptPath at once; the result follows as a message. Resume with {scriptPath or edited script, resumeFromRunId}; an edited script needs operator approval.
| Parameter | Type | Description |
|---|---|---|
script? |
string | Inline script (plain JavaScript) |
scriptPath? |
string | A saved run script or workflow-directory script |
name? |
string | Registered script workflow |
args? |
unknown | The script's args: a JSON value, not a string |
resumeFromRunId? |
string | Run whose unchanged agent() prefix is reused |
workflow_control
Extension subagent. Control a live workflow run in this session: pause (start no new agents; running ones finish), resume (unpause; a pause the console's safety stop set yields only to the operator), stop (a live run's agents stop and it ends interrupted, resumable with workflow_run {resume}; a background subagent run id stops that child; all stops every live run and every background subagent, orphans included), or skip (stop the agents running now and record their steps as skipped; a skipped required step can fail the run or leave it partial).
| Parameter | Type | Description |
|---|---|---|
runId? |
string | The live run's id, or a background subagent run id (workflow_status lists both) |
action |
union | — |
all? |
boolean | With action "stop": stop every live workflow run and every background subagent, orphans included |
workflow_run
Extension subagent. Run subagent steps with a shared directory, gates and resume. Pass exactly one of: name (a saved workflow; "list" shows them), steps (a plan as data) or resume (a run id). A step is {id?, agent?, task, tools?, skills?, outputs?, when?, gate?, continue_on_error?, expand?} or {parallel: [steps], gate?}. agent defaults to implementer; tools narrow. outputs are files to write relative to the run directory. {previous} is the prior step's output (after expand, its answer); {{steps.
| Parameter | Type | Description |
|---|---|---|
name? |
string | Saved workflow name, or "list" |
steps? |
unknown[] | The plan's steps |
inputs? |
record | Inputs, e.g. {goal: "..."} |
resume? |
string | Run id to resume |
workflow_status
Extension subagent. List runs of every format — workflow YAML, workflow script, subagent and autonomous container — live or finished. With id: YAML steps, script counters, a subagent's log tail, or an autonomous run's template, spend, blocker and liveness.
| Parameter | Type | Description |
|---|---|---|
id? |
string | One run's id; without it, the newest runs of every format |
limit? |
number | How many runs to list (default 20, max 100) |
tail? |
number | Lines of a background subagent's log to show with id (default 40) |
Environment variables
Read when the extension loads or when it acts, never written back. Values are strings; a path is absolute or relative to the working directory.
| Variable | Read by | Purpose | Documented in |
|---|---|---|---|
DUAL_REVIEW_MODEL |
dual-review |
Second model name for reviewer agent | INSTALL |
HERDR_ENV |
herdr |
— | herdr |
HERDR_PANE_ID |
herdr |
— | herdr |
HERDR_SOCKET_PATH |
herdr |
— | herdr |
LMSTUDIO_BASE_URL |
memory-local |
— | — |
LUNA_AGENT_STATE_DIR |
herdr |
— | autonomy |
MEM0_API_KEY |
memory-mem0 |
mem0 API key (if auth enabled) | INSTALL |
MEM0_API_URL |
memory-mem0 |
mem0 REST service URL | INSTALL |
MEM0_USER_ID |
memory-mem0 |
mem0 user/agent ID (default pi-agent) |
INSTALL |
NO_COLOR |
control-center |
— | control-center |
PI_AUTONOMY_CLI |
autonomy-run |
— | — |
PI_AUTONOMY_GATE_SLOTS |
autonomy-run |
— | autonomy |
PI_AUTONOMY_HOME |
autonomy-run |
— | autonomy |
PI_CODING_AGENT_DIR |
control-center, finish-reason-retry, caveman, protected-paths, trigger-compact |
— | autonomy-gate |
PI_CONSOLE_ALLOWED_HOSTS |
web-console |
— | web-console |
PI_CONSOLE_ALLOW_REMOTE |
web-console |
— | web-console |
PI_CONSOLE_AUTH |
web-console |
— | web-console |
PI_CONSOLE_HOST |
web-console |
— | web-console |
PI_CONSOLE_PORT |
web-console |
— | web-console |
PI_CONSOLE_TOKEN |
web-console |
— | web-console |
PI_CONSOLE_TOKEN_FILE |
web-console |
— | web-console |
PI_KIT_AGENTS_DIR |
subagent |
— | — |
PI_KIT_ASCII |
control-center, custom-footer |
— | control-center |
PI_KIT_AUTO_MODE |
tool-firewall |
— | autonomy-gate |
PI_KIT_AUTO_MODE_MODEL |
tool-firewall |
— | autonomy-gate |
PI_KIT_AUTO_MODE_STATE_DIR |
tool-firewall |
— | autonomy-gate |
PI_KIT_AUTO_PROFILE |
session-helpers |
Profile applied on the first interactive start; 0 disables (default balanced) |
INSTALL |
PI_KIT_BRANCH_LEASES_FILE |
branch-lab |
— | security |
PI_KIT_CAPTURE |
tool-capture |
— | tool-capture |
PI_KIT_CAPTURE_DIR |
tool-capture |
— | tool-capture |
PI_KIT_CAPTURE_INLINE_BYTES |
tool-capture |
— | tool-capture |
PI_KIT_CAPTURE_MAX_BLOB_BYTES |
tool-capture |
— | tool-capture |
PI_KIT_CAPTURE_MAX_BYTES |
tool-capture |
— | tool-capture |
PI_KIT_CAPTURE_MIN_FREE_BYTES |
tool-capture |
— | tool-capture |
PI_KIT_CAPTURE_REDACT |
tool-capture |
— | tool-capture |
PI_KIT_CAPTURE_SEGMENT_BYTES |
tool-capture |
— | tool-capture |
PI_KIT_CAT |
custom-footer |
— | status-bar-and-costs |
PI_KIT_CAVEMAN_LEVEL |
caveman |
— | — |
PI_KIT_CEILING_SECONDS |
goal-core |
— | autonomy |
PI_KIT_CEILING_TURNS |
goal-core |
— | autonomy |
PI_KIT_CEILING_USD |
goal-core |
— | autonomy |
PI_KIT_CHECKPOINT_MAX |
git-checkpoint |
— | profiles |
PI_KIT_CHILD_REQUIRE |
delegation-guard |
— | — |
PI_KIT_COMPACT_COOLDOWN_MS |
trigger-compact |
— | — |
PI_KIT_COMPACT_THRESHOLD_TOKENS |
trigger-compact |
Token count that triggers auto-compaction; locks out /compact-threshold when set. Without it, /compact-threshold <amount> (e.g. 500k) persists to ~/.pi/agent/pi-kit/trigger-compact.json (default 100000) |
INSTALL |
PI_KIT_COMPRESS_MAX_CHARS |
compress |
— | — |
PI_KIT_COST_CACHE_READ_PER_MTOK |
custom-footer |
Optional cache-read dollars per million tokens | INSTALL |
PI_KIT_COST_CACHE_WRITE_PER_MTOK |
custom-footer |
Optional cache-write dollars per million tokens | INSTALL |
PI_KIT_COST_INPUT_PER_MTOK |
custom-footer |
Override input-token dollars per million tokens | INSTALL |
PI_KIT_COST_OUTPUT_PER_MTOK |
custom-footer |
Override output-token dollars per million tokens | INSTALL |
PI_KIT_CTX_BUDGET_TOKENS |
context-sieve |
— | — |
PI_KIT_CTX_MESSAGE_BUDGET_TOKENS |
context-sieve |
— | — |
PI_KIT_DELIVERY |
kit-update |
— | updates |
PI_KIT_EFFORT |
effort |
— | INSTALL |
PI_KIT_EFFORT_CAP |
effort |
— | effort |
PI_KIT_EFFORT_CONFIG |
effort |
Saved effort default and limit overrides (Effort) (default <agent dir>/pi-kit/effort.json) |
INSTALL |
PI_KIT_EFFORT_LEDGER |
effort |
— | — |
PI_KIT_EFFORT_POLICY_DIR |
effort |
— | — |
PI_KIT_EFFORT_PROMPT |
effort |
— | — |
PI_KIT_EMBED_MODEL |
memory-local |
— | — |
PI_KIT_EXTENSIONS_ROOT |
delegation-guard |
— | — |
PI_KIT_FIREWALL_APPROVALS |
secret-guard, tool-firewall, protected-paths |
Where remembered approvals are stored (Security) (default <agent dir>/pi-kit/firewall-approvals.json) |
INSTALL |
PI_KIT_FIREWALL_AUDIT_LOG |
secret-guard, tool-firewall |
— | autonomy-gate |
PI_KIT_FIREWALL_CONFIG |
tool-firewall, custom-footer, protected-paths |
— | — |
PI_KIT_FIREWALL_FEEDBACK |
tool-firewall, protected-paths |
— | — |
PI_KIT_FIREWALL_JUDGEMENTS |
tool-firewall |
— | — |
PI_KIT_FIREWALL_JUDGE_TIMEOUT_MS |
tool-firewall |
— | autonomy-gate |
PI_KIT_FIREWALL_LEARNED_PROFILE |
tool-firewall |
— | — |
PI_KIT_FIREWALL_POLICY |
secret-guard, tool-firewall |
Path to a custom firewall policy JSON (default shipped default-deny policy) | INSTALL |
PI_KIT_FIREWALL_PROFILE |
tool-firewall, protected-paths |
— | autonomy-gate |
PI_KIT_FIREWALL_PROMPT_TIMEOUT_MS |
tool-firewall |
How long an approval card waits before the call is refused as uncertain (default 900000) |
INSTALL |
PI_KIT_FIREWALL_ROOT_SESSION |
tool-firewall |
— | autonomy-gate |
PI_KIT_FIREWALL_SESSIONS_DIR |
tool-firewall, protected-paths |
— | — |
PI_KIT_GUARD_ESCALATE |
progress-guard |
— | efficiency-and-loops |
PI_KIT_GUARD_MODE |
progress-guard |
— | efficiency-and-loops |
PI_KIT_GUARD_OSC |
progress-guard |
— | efficiency-and-loops |
PI_KIT_GUARD_REPEAT |
progress-guard |
— | efficiency-and-loops |
PI_KIT_GUARD_STALL |
progress-guard |
— | agent-orchestration |
PI_KIT_GUIDELINES_PATH |
guidelines |
Path to guidelines file (default GUIDELINES.md) |
INSTALL |
PI_KIT_HANDOFF_AUTO |
handoff |
— | — |
PI_KIT_HANDOFF_FILE |
handoff |
— | — |
PI_KIT_HERDR |
herdr |
— | herdr |
PI_KIT_HERDR_NOTIFY_MIN_SECONDS |
herdr |
— | herdr |
PI_KIT_HUMAN_CONSOLE_DIR |
engagement-governance, human-console, tool-firewall |
— | future-work |
PI_KIT_HUMAN_CONSOLE_TIMEOUT_MS |
engagement-governance, tool-firewall |
— | autonomy-gate |
PI_KIT_INTERNAL_CHILD |
control-center, trigger-compact |
— | control-center |
PI_KIT_LEAN_CTX |
session-helpers |
Set to 0 to disable the lean-ctx preflight warning |
INSTALL |
PI_KIT_LOOP_MAX |
autonomous-loop |
— | efficiency-and-loops |
PI_KIT_MAX_BRANCHES |
branch-lab |
— | — |
PI_KIT_MEMORY_AUTOPROMOTE |
memory-vault |
— | memory |
PI_KIT_MEMORY_BACKEND |
memory-mem0 |
— | — |
PI_KIT_MEMORY_DIR |
memory-local, memory-vault |
Memory store directory (default ~/.pi/agent/memory-local) |
INSTALL |
PI_KIT_MEMORY_MAX_ENTRIES |
memory-local |
— | — |
PI_KIT_MEMORY_MCP_ARGS |
memory-mem0 |
— | — |
PI_KIT_MEMORY_MCP_COMMAND |
memory-mem0 |
— | — |
PI_KIT_MEMORY_MIN_SCORE |
memory-vault |
— | memory |
PI_KIT_MEMORY_RECALL_LIMIT |
memory-vault |
— | memory |
PI_KIT_NODE |
autonomy-run, kit-update, remote-control, session-helpers, web-console, subagent |
— | remote-control |
PI_KIT_NOTIFY |
notify |
— | — |
PI_KIT_NOTIFY_MIN_SECONDS |
notify |
— | — |
PI_KIT_NPM_REGISTRY |
kit-update |
— | updates |
PI_KIT_ORCH_DISABLE |
orchestrator |
— | agent-orchestration |
PI_KIT_ORCH_THRESHOLD |
orchestrator |
— | agent-orchestration |
PI_KIT_PROTECTED_PATHS |
protected-paths |
Semicolon-separated protected paths (denylist) | INSTALL |
PI_KIT_RECAPS |
memory-vault |
— | memory |
PI_KIT_RECAP_MODEL |
memory-vault |
— | memory |
PI_KIT_RECOVERY_MAX_ATTEMPTS |
recovery-orchestrator |
— | efficiency-and-loops |
PI_KIT_RECOVERY_SCOUTS |
recovery-orchestrator |
— | — |
PI_KIT_REDUCED_MOTION |
control-center |
— | control-center |
PI_KIT_ROOT |
kit-update, session-helpers |
— | security |
PI_KIT_ROUTING_POLICY |
provider-router |
— | model-resilience |
PI_KIT_SAVE_DIR |
save |
— | — |
PI_KIT_SAVE_ON_COMPACT |
save |
— | — |
PI_KIT_SAVE_PROJECT |
save |
— | — |
PI_KIT_SAVE_RESERVE_TOKENS |
save |
— | — |
PI_KIT_SAVE_TIMEOUT_MS |
save |
— | — |
PI_KIT_SAVE_VAULT |
save |
— | — |
PI_KIT_SECURITY_CONFIG |
tool-firewall |
— | security-level |
PI_KIT_SECURITY_LEVEL |
tool-firewall |
— | security-level |
PI_KIT_SKILL_DIRS |
subagent |
— | — |
PI_KIT_SPEC_PLAN_MIN_LINES |
spec-plan |
— | — |
PI_KIT_SPEC_PLAN_STRICT |
spec-plan |
— | — |
PI_KIT_STRUCTURED_OUTPUT_SCHEMA |
subagent |
— | structured-output |
PI_KIT_SUBAGENT_APPROVAL_TIMEOUT_MS |
subagent |
— | agent-orchestration |
PI_KIT_SUBAGENT_CONCURRENCY |
subagent |
— | model-resilience |
PI_KIT_SUBAGENT_DEPTH |
subagent |
— | — |
PI_KIT_SUBAGENT_DETACH_SIGNAL |
subagent |
— | agent-orchestration |
PI_KIT_SUBAGENT_DISCOVERY |
subagent |
— | agent-orchestration |
PI_KIT_SUBAGENT_EXTENSIONS |
delegation-guard, subagent |
— | agent-orchestration |
PI_KIT_SUBAGENT_HEARTBEAT_MS |
subagent |
— | agent-orchestration |
PI_KIT_SUBAGENT_IDLE_TIMEOUT_MS |
subagent |
— | agent-orchestration |
PI_KIT_SUBAGENT_INHERIT_MODEL |
subagent |
— | agent-orchestration |
PI_KIT_SUBAGENT_MAX_DEPTH |
subagent |
— | effort |
PI_KIT_SUBAGENT_MAX_RUNTIME_MS |
subagent |
— | agent-orchestration |
PI_KIT_SUBAGENT_RETRIES |
subagent |
— | — |
PI_KIT_SUBAGENT_RETRY_BACKOFF_MS |
subagent |
— | — |
PI_KIT_SUBAGENT_STATE_DIR |
subagent |
— | — |
PI_KIT_SUBAGENT_STREAM_CAP_BYTES |
subagent |
— | — |
PI_KIT_TASK_GRAPH_LEASE_MS |
task-graph |
How long a task_next claim lasts without a task_update; an older claim returns to pending. 0 disables expiry (default 3600000) |
INSTALL |
PI_KIT_TIPS |
custom-footer |
0 hides usage tips on the working line (default on) |
INSTALL |
PI_KIT_TODO_FILE |
custom-footer, todo |
Path to todo file (default TODO.md) |
INSTALL |
PI_KIT_TODO_WIDGET |
custom-footer |
0 hides the todo checklist widget (default on) |
INSTALL |
PI_KIT_TOOL_RESULT_MAX_CHARS |
subagent |
— | efficiency-and-loops |
PI_KIT_TRUSTED_PROJECT_ROLES |
subagent |
— | agent-orchestration |
PI_KIT_TRUSTED_WORKFLOWS |
subagent |
— | workflows |
PI_KIT_UNATTENDED |
tool-firewall |
— | autonomy-gate |
PI_KIT_UNATTENDED_BOUNDARY |
tool-firewall |
— | autonomy-gate |
PI_KIT_UNATTENDED_CONTRACT |
secret-guard, tool-firewall, protected-paths |
— | autonomy-gate |
PI_KIT_UPDATE_CHECK |
kit-update |
0 turns the background update check off (Updates) (default on) |
INSTALL |
PI_KIT_UPDATE_CHECK_HOURS |
kit-update |
— | updates |
PI_KIT_VAULT |
memory-vault |
— | memory |
PI_KIT_VERIFY_CMD |
verify-gate |
Check command for /verify; overrides scripts.verify (default unset) |
INSTALL |
PI_KIT_VERIFY_ON_TURN |
verify-gate |
Set to 1 to run the check command after successful write/edit tools when the assistant finishes its tool sequence; projects without a verify script are skipped (default 0) |
INSTALL |
PI_KIT_VERIFY_PENDING_TTL_MS |
verify-gate |
How long a "verification pending" marker stays valid, in ms; an older marker is treated as absent (default 1800000) |
INSTALL |
PI_KIT_VERIFY_REVIEW |
verify-gate |
0 turns off the independent completion reviewer in /verify and verify_completion (default on) |
INSTALL |
PI_KIT_VERIFY_REVIEW_MODEL |
verify-gate |
Reviewer model as provider/id (default current model) |
INSTALL |
PI_KIT_VERIFY_REVIEW_TIMEOUT_MS |
verify-gate |
Reviewer timeout (default 900000) |
INSTALL |
PI_KIT_WEBUI_ROOT |
remote-control, web-console |
— | remote-control |
PI_KIT_WORKFLOWS_DIR |
subagent |
— | — |
PI_KIT_WORKFLOW_RUN_ID |
tool-firewall, subagent |
— | script-workflows |
PI_KIT_WORKFLOW_STEP |
tool-firewall, subagent |
— | — |
PI_KIT_WRITE_ALLOWLIST |
protected-paths |
Semicolon-separated allowlist; blocks writes outside it (dream/print mode) | INSTALL |
PI_LENS_DISABLE_LSP_INSTALL |
tool-firewall |
— | supply-chain |
PI_LENS_DISABLE_TOOL_INSTALL |
tool-firewall |
— | supply-chain |
PI_OFFLINE |
kit-update |
— | updates |
PI_REMOTE_ADVERTISE |
remote-control |
— | remote-control |
PI_REMOTE_AUTO_ATTACH |
remote-control |
— | remote-control |
PI_REMOTE_BIND |
remote-control |
— | operator-checklist |
PI_REMOTE_NAME |
remote-control |
— | remote-control |
PI_REMOTE_PORT |
remote-control |
— | remote-control |
PI_REMOTE_STATE_DIR |
remote-control, tool-firewall, protected-paths |
— | remote-control |
PI_REMOTE_TOKEN_TTL_MIN |
remote-control |
— | remote-control |
PI_SYSTEM_GIT_SOURCE |
kit-update |
— | migration |
XDG_STATE_HOME |
herdr |
— | autonomy |
Configuration files
| File | What it configures | Defined in |
|---|---|---|
packages/kit/profiles/<name>.json |
A profile: which extensions, skills and prompts load, and the firewall mode | profiles |
packages/extensions/src/tool-firewall/default-policy.json |
The shipped firewall policy (a custom one is named by PI_KIT_FIREWALL_POLICY) |
security |
packages/core/.env.example |
Every environment variable Luna reads, with defaults | INSTALL |
JSON schemas
| Schema | Title | Description |
|---|---|---|
packages/core/schema/extension.schema.json |
Extension metadata | |
packages/core/schema/sources.schema.json |
External sources registry | |
packages/autonomy/schema/run-contract.schema.json |
pi-autonomy run contract, schemaVersion 1 | The declarative description of one autonomous run: what it is for, what it may touch and when it is finished. This schema documents the structure and is checked against the hand-written validator in lib/contract.ts (which is authoritative: it also applies defaults and the rules JSON Schema cannot express, such as unique ids, that every backlog acceptance id names a declared check, that service images come from the allowlist, and that effort tiers exist in packages/core/policies). Unknown keys under permissions, generations, promotion and authorisation, and unknown top-level keys, are errors; unknown keys elsewhere are warnings, which is why those objects allow additional properties here. |