\n\nlunR is a terminal coding agent derived from [pi](https://github.com/badlogic/pi-mono). It ships with interactive TUI, print/JSON, RPC, and SDK modes, plus baked-in MCP, subagents, permissions, read-only planning, todos, cron, and a Telegram/Discord gateway.\n\nExtend it with TypeScript [Extensions](#extensions), [Skills](#skills), [Prompt Templates](#prompt-templates), and [Themes](#themes). Bundle those as [packages](#packages) and share them via npm or git.\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Providers & Models](#providers--models)\n- [Interactive Mode](#interactive-mode)\n - [Editor](#editor)\n - [Copyable response blocks](#copyable-response-blocks)\n - [Commands](#commands)\n - [Keyboard Shortcuts](#keyboard-shortcuts)\n - [Message Queue](#message-queue)\n- [Sessions](#sessions)\n - [Branching](#branching)\n - [Compaction](#compaction)\n- [Settings](#settings)\n- [Context Files](#context-files)\n- [Customization](#customization)\n - [Prompt Templates](#prompt-templates)\n - [Skills](#skills)\n - [Extensions](#extensions)\n - [Themes](#themes)\n - [Packages](#packages)\n- [Programmatic Usage](#programmatic-usage)\n- [Philosophy](#philosophy)\n- [CLI Reference](#cli-reference)\n\n---\n\n## Quick Start\n\nRequires **Node.js ≥ 22.19**.\n\n```bash\nnpm i -g @ashx-j/lunr\n```\n\nNormal installation also installs matching Chromium for the built-in [browser](docs/browser.md). Turn Browser off in `/settings` if you do not want its tool. `--ignore-scripts` and offline installs skip Chromium; the rest of lunR remains usable, and `lunr browser install` repairs missing binaries later.\n\nThen run it in a project directory:\n\n```bash\ncd /path/to/project\nlunr\n```\n\nAuthenticate with an API key:\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\nlunr\n```\n\nOr use a subscription / stored credential:\n\n```bash\nlunr\n/login # Then select provider\n```\n\nFirst-run setup installs Chromium and offers the optional Telegram/Discord gateway:\n\n```bash\nlunr setup\nlunr features list\n```\n\nTo remove the CLI, keep `~/.lunr/agent` unless you pass `--purge`:\n\n```bash\nlunr uninstall # remove this lunR install; keeps ~/.lunr/agent\nlunr uninstall --purge # also wipe ~/.lunr/agent (settings, credentials, sessions)\nlunr uninstall npm:@foo/bar # remove an extension package (alias for lunr remove)\n```\n\nYou can also `npm uninstall -g @ashx-j/lunr`. That leaves `~/.lunr/agent` in place.\n\nConfig lives in `~/.lunr/agent` (global) and project `.lunr/` (`piConfig.configDir`). Override the agent dir with `PI_CODING_AGENT_DIR`. **Do not use `~/.pi/` as the lunR home.**\n\nThen just talk to lunR. By default it gives the model four tools: `read`, `write`, `edit`, and `bash`. `grep`, `find`, and `ls` exist but start off. Add more via [skills](#skills), [prompt templates](#prompt-templates), [extensions](#extensions), or [packages](#packages). See [built-in features](docs/features.md) for MCP, subagents, read-only planning, cron, and the gateway.\n\n**Platform notes:** [Windows](docs/windows.md) | [Termux (Android)](docs/termux.md) | [tmux](docs/tmux.md) | [Terminal setup](docs/terminal-setup.md) | [Shell aliases](docs/shell-aliases.md)\n\n---\n\n## Providers & Models\n\nlunR ships a built-in catalog. First paint is **cache-only** (no GitHub or live `/models` at startup). Authenticate with `/login` or an API key, then pick a model with `/model` (or Ctrl+L).\n\n`/model` lists **stored-credential** providers only (`~/.lunr/agent/auth.json`, subscriptions, or `--api-key`). An ambient `OPENROUTER_API_KEY` does not make OpenRouter models appear in `/model`.\n\nModel catalogs refresh automatically after startup and periodically while lunR is idle. Startup itself uses cached or bundled data. **`/refresh`** forces an immediate check for providers with stored credentials; `lunr update` only reinstalls the global CLI.\n\nFor ChatGPT/Codex, lunR discovers the models available to your account directly, including new model IDs. Provider-supplied context and reasoning capabilities take priority over older published metadata; explicit `models.json` overrides remain yours. Failed requests keep the last successful catalog for the same account. Models with missing pricing are marked as such in the model picker; new IDs do not trigger metadata questions.\n\n**Subscriptions:**\n- Anthropic Claude Pro/Max\n- OpenAI ChatGPT Plus/Pro (Codex)\n- GitHub Copilot\n- xAI SuperGrok (Grok/X subscription)\n- Radius\n\n**Local / live:**\n- Ollama and LM Studio via `/login` (localhost probe)\n- OpenCode Zen: `/login opencode` then `/refresh` (free rows rotate from live `/v1/models`)\n\n**API keys:** Anthropic, Ant Ling, OpenAI, Azure OpenAI, DeepSeek, NVIDIA NIM, Google Gemini, Google Vertex, Amazon Bedrock, Mistral, Groq, Cerebras, Cloudflare AI Gateway, Cloudflare Workers AI, xAI, OpenRouter, Vercel AI Gateway, ZAI Coding Plan, OpenCode Zen/Go, Hugging Face, Fireworks, Together AI, Kimi For Coding, MiniMax, Xiaomi MiMo, Qwen Token Plan.\n\nSee [docs/providers.md](docs/providers.md) for setup. **xAI SuperGrok:** `/login xai` can import `~/.grok/auth.json` from the Grok CLI; `/logout xai` does **not** delete that file.\n\n**Custom providers & models:** Add providers via `~/.lunr/agent/models.json` if they speak a supported API (OpenAI, Anthropic, Google). For custom APIs or OAuth, use extensions. See [docs/models.md](docs/models.md) and [docs/custom-provider.md](docs/custom-provider.md).\n\n---\n\n## Interactive Mode\n\n
\n\nThe interface from top to bottom:\n\n- **Startup header** - Shows shortcuts (`/hotkeys` for all), loaded AGENTS.md files, prompt templates, skills, and extensions\n- **Messages** - Your messages, assistant responses, tool calls and results, notifications, errors, and extension UI\n- **Editor** - Where you type; border color indicates thinking level\n- **Footer** - Working directory, git branch, session name, token/cache usage, cost, context usage, plan bar, current model. Customize its segments under `/settings` → Customize.\n\nThe editor can be temporarily replaced by other UI, like built-in `/settings` or custom UI from extensions. [Extensions](#extensions) can also replace the editor, add widgets above/below it, a status line, custom footer, or overlays.\n\n### Editor\n\n| Feature | How |\n|---------|-----|\n| File reference | Type `@` to fuzzy-search project files |\n| Path completion | Tab to complete paths |\n| Multi-line | Shift+Enter (or Ctrl+Enter on Windows Terminal) |\n| External editor | Ctrl+G opens `externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere |\n| Clipboard | Ctrl+V normally, Alt+V on Windows. VS Code must forward Alt+V, or use `/paste-image` without a shortcut. Images insert `[image_n]` chips, not a temp path. |\n| Bash commands | `!command` runs and sends output to LLM, `!!command` runs without sending |\n\nStandard editing keybindings for delete word, undo, etc. See [docs/keybindings.md](docs/keybindings.md).\n\n### Copyable response blocks\n\nAssistant responses can mark a reusable excerpt, prompt, or code fragment as click-to-copy. The marked section appears in a plain background box. Click anywhere in that box to copy only its contents.\n\nThe source format is a fenced Markdown block with the exact info string `lunr-copy`:\n\n````markdown\n```lunr-copy\nnpm test\n```\n````\n\nThe payload starts after the opening fence's line break and ends before the line break immediately preceding the closing fence. lunR copies it without trimming whitespace and excludes both fence lines. A longer backtick or tilde fence can contain shorter fenced code. Incomplete streamed blocks remain readable but become clickable only after the closing fence arrives. Print, JSON, RPC, and gateway output keep the raw fences and never write to the clipboard.\n\n### Commands\n\nType `/` in the editor to trigger commands. [Extensions](#extensions) can register custom commands, [skills](#skills) are available as `/skill:name`, and [prompt templates](#prompt-templates) expand via `/templatename`.\n\n| Command | Description |\n|---------|-------------|\n| `/login`, `/auth` | Configure provider authentication |\n| `/logout`, `/deauth` | Remove provider authentication |\n| `/model` | Switch models (stored-cred providers) |\n| `/refresh` | Refresh model catalogs |\n| `/scoped-models` | Enable/disable models for Ctrl+P cycling |\n| `/settings` | Theme, thinking, agent memory, message delivery, transport |\n| `/thinking`, `/effort`, `/reasoning` | Set thinking level (`xhigh`/`max` are opt-in when the model supports them) |\n| `/off`, `/minimal`, `/low`, `/medium`, `/high`, `/xhigh`, `/max` | Set that thinking level when the current model supports it |\n| `/mode` | Set permission mode: `yolo`, `auto`, or `read` (Shift+Tab cycles) |\n| `/plan` | Switch to read-only mode for planning, or `/plan ` to plan a task |\n| `/read`, `/yolo`, `/auto` | Activate that permission mode |\n| `/cron` | Scheduled prompts (`~/.lunr/agent/cron/`) |\n| `/goal` | Session goal (forces session auto permission mode) |\n| `/processes` | Background processes started this session |\n| `/usage` | This-session token totals, context, and every stored subscription plan |\n| `/fast` | Toggle Fast mode for OpenAI Codex subscriptions |\n| `/context` | Estimated context-window breakdown |\n| `/resume`, `/sessions` | Pick from previous sessions |\n| `/new` | Start a new session |\n| `/name`, `/title` | Set session display name |\n| `/session` | Show session info |\n| `/tree` | Jump to any point in the session (`ctrl+o` cycles filters) |\n| `/undo`, `/edit`, `/redo` | Same-session rewind; `/edit` pastes the last prompt |\n| `/rollback` | Undo the last turn's file changes (forks) |\n| `/trust` | Save project trust decision |\n| `/fork` | Create a new session from a previous user message |\n| `/clone` | Duplicate the current active branch |\n| `/compact [prompt]` | Manually compact context |\n| `/copy` | Copy last assistant message |\n| `/paste-image` | Paste an image from the clipboard |\n| `/export [file]` | Export session to HTML or JSONL |\n| `/import ` | Import and resume a JSONL session |\n| `/share` | Upload as a private GitHub gist (HTML viewer still defaults to https://pi.dev/session/ — leftover, not lunR-hosted) |\n| `/reload` | Reload keybindings, extensions, skills, prompts, themes, and context files |\n| `/hotkeys` | Show all keyboard shortcuts |\n| `/init` | Generate a starter AGENTS.md |\n| `/quit`, `/exit` | Quit lunR |\n\nThere is no `/changelog` or `/token-usage` command.\n\n### Keyboard Shortcuts\n\nSee `/hotkeys` for the full list. Customize via `~/.lunr/agent/keybindings.json`. See [docs/keybindings.md](docs/keybindings.md).\n\n**Commonly used:**\n\n| Key | Action |\n|-----|--------|\n| Ctrl+C | Clear editor |\n| Ctrl+C twice | Quit |\n| Escape | Cancel/abort |\n| Escape twice within 500ms | Stop this session's active async subagents; otherwise open `/tree` when idle |\n| Ctrl+L | Open model selector |\n| Ctrl+P / Shift+Ctrl+P | Cycle scoped models forward/backward |\n| Shift+Tab | Cycle permission mode (`yolo` → `auto` → `read`) |\n| Ctrl+O | Cycle `/tree` filters (not tool expand) |\n| Ctrl+T | Cycle thinking level for the selected model |\n| Ctrl+X | Copy the last assistant message |\n\nClick a thinking or tool card to expand or collapse that item. `app.tools.expand` is unbound.\n\n### Message Queue\n\nSubmit messages while the agent is working:\n\n- **Enter** queues a *steering* message, delivered after the current assistant turn finishes executing its tool calls. If the parent is executing `subagent_wait`, Enter instead ends only that wait. The current tool batch settles, background children keep running, and the text starts a fresh parent turn without appearing in the steering queue.\n- **Alt+Enter** queues a *follow-up* message, delivered only after the agent finishes all work\n- **Escape** aborts and restores queued messages to editor\n- **Alt+Up** retrieves queued messages back to editor\n\nOn Windows Terminal, `Alt+Enter` is fullscreen by default. Remap it in [docs/terminal-setup.md](docs/terminal-setup.md) so lunR can receive the follow-up shortcut.\n\nParallel tools beside `subagent_wait` finish before the fresh Enter prompt starts. Alt+Enter and Enter outside an executing wait keep their normal queue behavior.\n\nConfigure delivery in [settings](docs/settings.md): `steeringMode` and `followUpMode` can be `\"one-at-a-time\"` (default, waits for response) or `\"all\"` (delivers all queued at once). `transport` selects provider transport preference (`\"sse\"`, `\"websocket\"`, or `\"auto\"`) for providers that support multiple transports.\n\n---\n\n## Sessions\n\nSessions are stored as JSONL files with a tree structure. Each entry has an `id` and `parentId`, enabling in-place branching without creating new files. See [docs/session-format.md](docs/session-format.md) for file format.\n\n### Management\n\nSessions auto-save to `~/.lunr/agent/sessions/` organized by working directory.\n\n```bash\nlunr -c # Continue most recent session\nlunr -r # Browse and select from past sessions\nlunr --no-session # Ephemeral mode (don't save)\nlunr --name \"my task\" # Set session display name at startup\nlunr --session # Use specific session file or ID\nlunr --session-id # Use exact project session ID, creating it if missing\nlunr --fork # Fork specific session file or ID into a new session\n```\n\nUse `/session` in interactive mode to see the current session ID before reusing it with `--session ` or `--fork `.\n\n### Branching\n\n**`/tree`** - Navigate the session tree in-place. Select any previous point, continue from there, and switch between branches. All history preserved in a single file.\n\n
\n\n- Search by typing, fold/unfold and jump between branches with Ctrl+←/Ctrl+→ or Alt+←/Alt+→, page with ←/→\n- Filter modes (Ctrl+O): default → no-tools → user-only → labeled-only → all\n- Press Ctrl+X to copy the selected message\n- Press Shift+L to label entries as bookmarks and Shift+T to toggle label timestamps\n\n**`/fork`** - Create a new session file from a previous user message on the active branch.\n\n**`/clone`** - Duplicate the current active branch into a new session file at the current position.\n\n**`--fork `** - Fork an existing session file or partial session UUID directly from the CLI.\n\n### Compaction\n\nLong sessions can exhaust context windows. Compaction summarizes older messages while keeping recent ones.\n\n**Manual:** `/compact` or `/compact `\n\n**Automatic:** Enabled by default. Triggers on context overflow (recovers and retries) or when approaching the limit (proactive). Configure via `/settings` or `settings.json`.\n\nCompaction is lossy. The full history remains in the JSONL file; use `/tree` to revisit. Customize compaction behavior via [extensions](#extensions). See [docs/compaction.md](docs/compaction.md) for internals.\n\n---\n\n## Settings\n\nUse `/settings` to modify common options, or edit JSON files directly:\n\n| Location | Scope |\n|----------|-------|\n| `~/.lunr/agent/settings.json` | Global (all projects) |\n| `.lunr/settings.json` | Project (overrides global) |\n\nSee [docs/settings.md](docs/settings.md) for all options.\n\n### Project Trust\n\nOn interactive startup, lunR asks before trusting a project folder that contains project-local settings, resources, or project `.agents/skills` and has no saved decision for the folder or a parent folder in `~/.lunr/agent/trust.json`. Trusting a project allows lunR to load `.lunr/settings.json` and `.lunr` resources, install missing project packages, and execute project extensions.\n\nBefore the trust decision, lunR loads only context files, user/global extensions, and CLI `-e` extensions so they can handle the `project_trust` event. Project-local extensions, project package-managed extensions, and project settings are loaded only after the project is trusted.\n\nNon-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, they use `defaultProjectTrust` from global settings: `ask` (default) and `never` ignore those project resources, while `always` trusts them. Pass `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.\n\n`lunr config` and package commands use the same project trust flow. Pass `--approve` to trust project-local settings for one command or `--no-approve` to ignore them. `lunr update` never prompts (it only reinstalls the global CLI).\n\nUse `/trust` in interactive mode to save a project trust decision for future sessions. It writes `~/.lunr/agent/trust.json` only; the current session is not reloaded, so restart lunR for changes to take effect.\n\n### Offline and updates\n\nUse `--offline` or `PI_OFFLINE=1` to skip startup network operations (npm update check, package update checks, live catalog probes). First interactive paint is already cache-only.\n\n`lunr update` / `lunr update --self` reinstalls global `@ashx-j/lunr` from npm. It is not a catalog refresh and does not take `--models`, `--all`, or `--force`. Workspace `npx lunr` (this repo) refuses to self-update; install the published package to use `lunr update`.\n\n---\n\n## Context Files\n\nlunR loads `AGENTS.md` (or `CLAUDE.md`) at startup from:\n- `~/.lunr/agent/agents/AGENTS.md` (global)\n- `~/.lunr/agent/agents//AGENTS.md` (optional model-specific instructions)\n- Parent directories (walking up from cwd)\n- Current directory\n\nUse `~/.lunr/agent/agents/AGENTS.md` for optional global behavior and instructions; the model cannot change this user-managed file. `/settings` can enable model-specific instructions and choose whether they append to or replace global instructions. Model folders use a provider-independent, filesystem-safe name derived from the active model. Use project files for project conventions and commands; they remain independent of that mode. Run `/reload` after adding or editing a context file while lunR is open.\n\nDisable context file loading with `--no-context-files` (or `-nc`).\n\n### System Prompt\n\nReplace the default system prompt with `.lunr/SYSTEM.md` (project) or `~/.lunr/agent/SYSTEM.md` (global). Append without replacing via `APPEND_SYSTEM.md`.\n\n---\n\n## Customization\n\n### Prompt Templates\n\nReusable prompts as Markdown files. Type `/name` to expand.\n\n```markdown\n\nReview this code for bugs, security issues, and performance problems.\nFocus on: {{focus}}\n```\n\nPlace in `~/.lunr/agent/prompts/`, `.lunr/prompts/`, or a [package](#packages) to share with others. See [docs/prompt-templates.md](docs/prompt-templates.md).\n\n### Skills\n\nOn-demand capability packages following the [Agent Skills standard](https://agentskills.io). Invoke via `/skill:name` or let the agent load them automatically.\n\n```markdown\n\n# My Skill\nUse this skill when the user asks about X.\n\n## Steps\n1. Do this\n2. Then that\n```\n\nPlace in `~/.lunr/agent/skills/`, `~/.agents/skills/`, `.lunr/skills/`, or `.agents/skills/` (from `cwd` up through parent directories) or a [package](#packages) to share with others. See [docs/skills.md](docs/skills.md).\n\n### Extensions\n\n
\n\nTypeScript modules that extend lunR with custom tools, commands, keyboard shortcuts, event handlers, and UI components.\n\n```typescript\nimport type { ExtensionAPI } from \"@ashx-j/lunr\";\n\nexport default function (pi: ExtensionAPI) {\n pi.registerTool({ name: \"deploy\", ... });\n pi.registerCommand(\"stats\", { ... });\n pi.on(\"tool_call\", async (event, ctx) => { ... });\n}\n```\n\nThe factory argument is conventionally named `pi` (`export default function (pi: ExtensionAPI)`). Keep that. The jiti loader aliases both `@ashx-j/lunr` and `@earendil-works/pi-coding-agent` when loading extensions.\n\nThe default export can also be `async`. lunR waits for async extension factories before startup continues.\n\nPlace in `~/.lunr/agent/extensions/`, `.lunr/extensions/`, or a [package](#packages). See [docs/extensions.md](docs/extensions.md) and [examples/extensions/](examples/extensions/). Sample extensions such as `examples/extensions/plan-mode`, `todo.ts`, and `subagent/` are **Extension API samples**, not the product implementation. lunR ships read-only planning, todos, and subagents as built-ins; see [docs/features.md](docs/features.md).\n\n### Themes\n\nBuilt-in theme: **`moon` only** (`getDefaultTheme()` returns `\"moon\"`). Themes hot-reload: modify the active theme file and lunR immediately applies changes.\n\nPlace custom themes in `~/.lunr/agent/themes/`, `.lunr/themes/`, or a [package](#packages). Schema: [theme-schema.json](https://github.com/ashx-j/lunR/blob/master/packages/coding-agent/src/modes/interactive/theme/theme-schema.json) (also packed as `dist/modes/interactive/theme/theme-schema.json`). See [docs/themes.md](docs/themes.md).\n\n### Packages\n\nBundle and share extensions, skills, prompts, and themes via npm or git. The package resource manifest key in `package.json` is still `\"pi\"` (`extensions`, `skills`, `prompts`, `themes`). Keep that key.\n\n> **Security:** Packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.\n\n```bash\nlunr install npm:@foo/lunr-tools\nlunr install npm:@foo/lunr-tools@1.2.3 # pinned version\nlunr install git:github.com/user/repo\nlunr install git:github.com/user/repo@v1 # tag or commit\nlunr remove npm:@foo/lunr-tools\nlunr uninstall npm:@foo/lunr-tools # alias for remove (requires a source)\nlunr list\nlunr config # enable/disable extensions, skills, prompts, themes\nlunr update # reinstall global @ashx-j/lunr only\n```\n\n`lunr update` does **not** refresh model catalogs or extension packages. Use `/refresh` for catalogs and `lunr install ` to move a git package to a new ref.\n\nPackages install to `~/.lunr/agent/git/` (git) or `~/.lunr/agent/npm/` (npm). Use `-l` for project-local installs (`.lunr/git/`, `.lunr/npm/`). Git `@ref` values are pinned tags or commits. Git packages install dependencies with `npm install --omit=dev` by default, so runtime deps must be listed under `dependencies`; when `npmCommand` is configured, git packages use plain `install` for compatibility with wrappers.\n\nCreate a package by adding a `pi` key to `package.json`:\n\n```json\n{\n \"name\": \"my-lunr-package\",\n \"keywords\": [\"pi-package\"],\n \"pi\": {\n \"extensions\": [\"./extensions\"],\n \"skills\": [\"./skills\"],\n \"prompts\": [\"./prompts\"],\n \"themes\": [\"./themes\"]\n }\n}\n```\n\nWithout a `pi` manifest, lunR auto-discovers from conventional directories (`extensions/`, `skills/`, `prompts/`, `themes/`).\n\nSee [docs/packages.md](docs/packages.md).\n\n---\n\n## Programmatic Usage\n\n### SDK\n\n```typescript\nimport { createAgentSession, ModelRuntime, SessionManager } from \"@ashx-j/lunr\";\n\nconst modelRuntime = await ModelRuntime.create();\nconst { session } = await createAgentSession({\n sessionManager: SessionManager.inMemory(),\n modelRuntime,\n});\n\nawait session.prompt(\"What files are in the current directory?\");\n```\n\nDefault `agentDir` is `~/.lunr/agent`. For advanced multi-session runtime replacement, use `createAgentSessionRuntime()` and `AgentSessionRuntime`.\n\nSee [docs/sdk.md](docs/sdk.md) and [examples/sdk/](examples/sdk/).\n\n### RPC Mode\n\nFor non-Node.js integrations, use RPC mode over stdin/stdout:\n\n```bash\nlunr --mode rpc\n```\n\nRPC mode uses strict LF-delimited JSONL framing. Clients must split records on `\\n` only. Do not use generic line readers like Node `readline`, which also split on Unicode separators inside JSON payloads.\n\nSee [docs/rpc.md](docs/rpc.md) for the protocol.\n\n---\n\n## Philosophy\n\nlunR keeps a small core and still lets you shape the product with [extensions](#extensions), [skills](#skills), and [packages](#packages). Unlike upstream pi, lunR **does** ship the workflows most coding agents expect:\n\n- **MCP** — `/mcp`, `/mcp-auth`\n- **Subagents** — always fresh; children use a configured tier by default, or an explicit model when the user names one; 3+ children receive one large-launch confirmation in yolo; default parallel concurrency is unlimited\n- **Permission modes** — `yolo | auto | read-only`; Shift+Tab cycles that order (read-only appears as `read` in the TUI)\n- **Read-only mode** — `/read` blocks changes; `/plan` and `present_plan` handle plan approval\n- **Todos** — lunr-todos is a full-replace list and can be disabled in `/settings`\n- **Background processes** — `/processes`\n- **Cron** — `/cron`, `~/.lunr/agent/cron/` (TUI live session or gateway origin)\n- **Gateway** — `lunr gateway` for Telegram and Discord\n- **Web search, LSP, agent memory, goals, intercom, skill-creator, model tiers**\n\nSee [docs/features.md](docs/features.md) for how those work. Build anything else with extensions.\n\n---\n\n## CLI Reference\n\n```bash\nlunr [options] [@files...] [messages...]\n```\n\n### Product Commands\n\n```bash\nlunr setup # Install Chromium and configure optional features\nlunr browser install # Repair missing Chromium after a skipped/failed install\nlunr features [list|enable|disable]\nlunr gateway […] # Chat gateway daemon (requires chat-platforms feature)\nlunr uninstall [--purge] # Remove this lunR install (keeps ~/.lunr/agent unless --purge)\nlunr uninstall [-l] # Remove an extension package (alias for remove)\nlunr install [-l] # Install package, -l for project-local\nlunr remove [-l] # Remove package\nlunr list # List installed packages\nlunr config # Enable/disable package resources\nlunr update # Reinstall global @ashx-j/lunr only\nlunr update --self # Same as lunr update\n```\n\n`lunr update` does not take `--models`, `--all`, `--force`, or `--extensions`. Refresh catalogs with `/refresh`.\n\n`lunr config` and project package commands accept `--approve`/`--no-approve` to trust or ignore project-local settings for one command.\n\n### Modes\n\n| Flag | Description |\n|------|-------------|\n| (default) | Interactive mode |\n| `-p`, `--print` | Print response and exit |\n| `--mode json` | Output all events as JSON lines (see [docs/json.md](docs/json.md)) |\n| `--mode rpc` | RPC mode for process integration (see [docs/rpc.md](docs/rpc.md)) |\n| `--export [out]` | Export session to HTML |\n\nIn print mode, lunR also reads piped stdin and merges it into the initial prompt:\n\n```bash\ncat README.md | lunr -p \"Summarize this text\"\n```\n\n### Model Options\n\n| Option | Description |\n|--------|-------------|\n| `--provider ` | Provider (anthropic, openai, google, etc.) |\n| `--model ` | Model pattern or ID (supports `provider/id` and optional `:`) |\n| `--api-key ` | API key (overrides env vars) |\n| `--thinking ` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |\n| `--models ` | Comma-separated patterns for Ctrl+P cycling |\n| `--list-models [search]` | List available models |\n\n### Session Options\n\n| Option | Description |\n|--------|-------------|\n| `-c`, `--continue` | Continue most recent session |\n| `-r`, `--resume` | Browse and select session |\n| `--session ` | Use specific session file or partial UUID |\n| `--session-id ` | Use exact project session ID, creating it if missing |\n| `--fork ` | Fork specific session file or partial UUID into a new session |\n| `--session-dir ` | Custom session storage directory |\n| `--no-session` | Ephemeral mode (don't save) |\n| `--name `, `-n ` | Set session display name at startup |\n\n### Tool Options\n\n| Option | Description |\n|--------|-------------|\n| `--tools `, `-t ` | Allowlist specific tool names across built-in, extension, and custom tools |\n| `--exclude-tools `, `-xt ` | Disable specific tool names across built-in, extension, and custom tools |\n| `--no-builtin-tools`, `-nbt` | Disable built-in tools by default but keep extension/custom tools enabled |\n| `--no-tools`, `-nt` | Disable all tools by default |\n\nAvailable built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`\n\n### Resource Options\n\n| Option | Description |\n|--------|-------------|\n| `-e`, `--extension ` | Load extension from path, npm, or git (repeatable) |\n| `--no-extensions` | Disable extension discovery |\n| `--skill ` | Load skill (repeatable) |\n| `--no-skills` | Disable skill discovery |\n| `--prompt-template ` | Load prompt template (repeatable) |\n| `--no-prompt-templates` | Disable prompt template discovery |\n| `--theme ` | Load theme (repeatable) |\n| `--no-themes` | Disable theme discovery |\n| `--no-context-files`, `-nc` | Disable AGENTS.md and CLAUDE.md context file discovery |\n\nCombine `--no-*` with explicit flags to load exactly what you need, ignoring settings.json (e.g., `--no-extensions -e ./my-ext.ts`).\n\n### Other Options\n\n| Option | Description |\n|--------|-------------|\n| `--system-prompt ` | Replace default prompt (context files and skills still appended) |\n| `--append-system-prompt ` | Append to system prompt |\n| `--verbose` | Force verbose startup |\n| `-a`, `--approve` | Trust project-local files for this run |\n| `-na`, `--no-approve` | Ignore project-local files for this run |\n| `--offline` | Disable startup network operations (same as `PI_OFFLINE=1`) |\n| `-h`, `--help` | Show help |\n| `-v`, `--version` | Show version |\n\n### File Arguments\n\nPrefix files with `@` to include in the message:\n\n```bash\nlunr @prompt.md \"Answer this\"\nlunr -p @screenshot.png \"What's in this image?\"\nlunr @code.ts @test.ts \"Review these files\"\n```\n\n### Examples\n\n```bash\n# Interactive with initial prompt\nlunr \"List all .ts files in src/\"\n\n# Non-interactive\nlunr -p \"Summarize this codebase\"\n\n# Non-interactive with piped stdin\ncat README.md | lunr -p \"Summarize this text\"\n\n# Named one-shot session\nlunr --name \"release audit\" -p \"Audit this repository\"\n\n# Different model\nlunr --provider openai --model gpt-4o \"Help me refactor\"\n\n# Model with provider prefix (no --provider needed)\nlunr --model openai/gpt-4o \"Help me refactor\"\n\n# Model with thinking level shorthand\nlunr --model sonnet:high \"Solve this complex problem\"\n\n# Limit model cycling\nlunr --models \"claude-*,gpt-4o\"\n\n# Read-only mode\nlunr --tools read,grep,find,ls -p \"Review the code\"\n\n# Disable one extension or built-in tool while keeping the rest available\nlunr --exclude-tools ask_question\n\n# High thinking level\nlunr --thinking high \"Solve this complex problem\"\n\n# Offline (no startup network)\nlunr --offline\n```\n\n### Environment Variables\n\nThese names stay `PI_*`. Do not invent `LUNR_*` replacements for them.\n\n| Variable | Description |\n|----------|-------------|\n| `PI_CODING_AGENT_DIR` | Override config directory (default: `~/.lunr/agent`) |\n| `PI_CODING_AGENT_SESSION_DIR` | Override session storage directory (overridden by `--session-dir`) |\n| `PI_PACKAGE_DIR` | Override package directory (useful for Nix/Guix where store paths tokenize poorly) |\n| `PI_OFFLINE` | Disable startup network operations when set to `1`/`true`/`yes` |\n| `PI_SHARE_VIEWER_URL` | Base URL for `/share` HTML viewer (default: `https://pi.dev/session/` — leftover) |\n| `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache (Anthropic: 1h, OpenAI: 24h) |\n| `VISUAL`, `EDITOR` | Fallback external editor for Ctrl+G when `externalEditor` is unset; defaults to Notepad on Windows and `nano` elsewhere |\n\nGateway bot tokens (optional) use `LUNR_TELEGRAM_BOT_TOKEN` / `LUNR_DISCORD_BOT_TOKEN` (or `TELEGRAM_BOT_TOKEN` / `DISCORD_BOT_TOKEN`) and are stored in `~/.lunr/agent/gateway.json`.\n\n---\n\n## Development\n\nSee [docs/development.md](docs/development.md) for setup, forking, and debugging. Source: [github.com/ashx-j/lunR](https://github.com/ashx-j/lunR).\n\n## License\n\nMIT\n\n## See Also\n\n- [@ashx-j/lunr-ai](https://www.npmjs.com/package/@ashx-j/lunr-ai): Core LLM toolkit\n- [@ashx-j/lunr-agent](https://www.npmjs.com/package/@ashx-j/lunr-agent): Agent framework\n- [@ashx-j/lunr-tui](https://www.npmjs.com/package/@ashx-j/lunr-tui): Terminal UI components\n","readmeFilename":"README.md"}
![\"npm\"](\"https://img.shields.io/npm/v/@ashx-j/lunr?style=flat-square\")
\n ![\"GitHub\"](\"https://img.shields.io/badge/github-ashx--j%2FlunR-181717?style=flat-square&logo=github\"){kind=icon}
\n![\"Interactive](\"docs/images/interactive-mode.png\")
![\"Tree](\"docs/images/tree-view.png\")
![\"Doom](\"docs/images/doom-extension.png\")