{"_id":"@ar-llm/pi-plan-mode","_rev":"2-b99b994727d004a2b030b8a23ae6f939","name":"@ar-llm/pi-plan-mode","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@ar-llm/pi-plan-mode","version":"0.1.0","keywords":["pi-package","pi-extension","pi","plan","plan-mode","exploration"],"license":"MIT","_id":"@ar-llm/pi-plan-mode@0.1.0","maintainers":[{"name":"arichiardi","email":"a.richiardi.work@gmail.com"}],"homepage":"https://github.com/arichiardi/ar-llm/tree/main/extensions/pi-plan-mode#readme","bugs":{"url":"https://github.com/arichiardi/ar-llm/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"4868b80147959a75e0118be9e7ec5d0f5c84c618","tarball":"https://registry.npmjs.org/@ar-llm/pi-plan-mode/-/pi-plan-mode-0.1.0.tgz","fileCount":7,"integrity":"sha512-DQqxunPPMF+AEtMxjP0HnTYh3hcHAFORlBiDw8LuOEZzfLBm44j5cUuf2o/pf0XDxKeznuSG0Tp19tSZO/F9Kw==","signatures":[{"sig":"MEUCIGcbMQwOjuw9bT2d66/gKE4IAmjWwkE9WY2ZbmIE5y6ZAiEAzwqRuI+BqCMa1pHcVHQ+RKTyRqazIrFaw8h6ZbemXBU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":33871},"type":"module","gitHead":"d7abbcc88ded6ce3c5ef85d607941cb3c897062d","private":false,"scripts":{"typecheck":"tsc --noEmit"},"_npmUser":{"name":"arichiardi","email":"a.richiardi.work@gmail.com"},"repository":{"url":"git+https://github.com/arichiardi/ar-llm.git","type":"git","directory":"extensions/pi-plan-mode"},"_npmVersion":"11.17.0","description":"Pi extension that adds a read-only plan mode for safe code exploration, step tracking, and constrained tool execution.","directories":{},"_nodeVersion":"26.5.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^6.0.3","@types/node":"^25.6.0","@earendil-works/pi-coding-agent":"0.79.10"},"peerDependencies":{"@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-agent-core":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-plan-mode_0.1.0_1786120282024_0.07776372501262574","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"pi":{"extensions":["./src/index.ts"]},"_id":"@ar-llm/pi-plan-mode@0.2.0","bugs":{"url":"https://github.com/arichiardi/ar-llm/issues"},"dist":{"shasum":"9fb44f2a809cf822806c52d795b82616f39e11e4","tarball":"https://registry.npmjs.org/@ar-llm/pi-plan-mode/-/pi-plan-mode-0.2.0.tgz","integrity":"sha512-i1COvvKXy2Vih48riGC9O/i+JC2vm7nvy9rCCl+aHK/6RLLcsltTf9GxbgpbaRHBOlo976yapd2TGW4w5A91Qw==","fileCount":10,"unpackedSize":43050,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC3mGq8CD2tHzxT/i7sg+at60yW1CsK716tWVJHIbkz5wIgDkkUVm2mCPwr1+KSGL40RnAJiypY0zw+ie/urND0Kg8="}]},"name":"@ar-llm/pi-plan-mode","type":"module","gitHead":"12298a182f56c3dadc87c2c6b76500e40cb7b52d","license":"MIT","private":false,"scripts":{"test":"node --test \"test/**/*.test.ts\"","typecheck":"tsc --noEmit"},"version":"0.2.0","_npmUser":{"name":"arichiardi","email":"a.richiardi.work@gmail.com","approver":{"name":"arichiardi","email":"a.richiardi.work@gmail.com"}},"homepage":"https://github.com/arichiardi/ar-llm/tree/main/extensions/pi-plan-mode#readme","keywords":["pi-package","pi-extension","pi","plan","plan-mode","exploration"],"repository":{"url":"git+https://github.com/arichiardi/ar-llm.git","type":"git","directory":"extensions/pi-plan-mode"},"_npmVersion":"12.0.2","description":"Pi extension that adds a read-only plan mode for safe code exploration, step tracking, and constrained tool execution.","directories":{},"maintainers":[{"name":"arichiardi","email":"a.richiardi.work@gmail.com"}],"_nodeVersion":"26.5.0","devDependencies":{"typescript":"^6.0.3","@types/node":"^25.6.0","@earendil-works/pi-coding-agent":"0.79.10"},"peerDependencies":{"@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-agent-core":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-plan-mode_0.2.0_1790017567979_0.5252428210544282"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-07T16:31:21.699Z","modified":"2026-09-21T19:06:08.206Z","0.1.0":"2026-08-07T16:31:22.203Z","0.2.0":"2026-09-21T19:06:08.082Z"},"bugs":{"url":"https://github.com/arichiardi/ar-llm/issues"},"license":"MIT","homepage":"https://github.com/arichiardi/ar-llm/tree/main/extensions/pi-plan-mode#readme","keywords":["pi-package","pi-extension","pi","plan","plan-mode","exploration"],"repository":{"url":"git+https://github.com/arichiardi/ar-llm.git","type":"git","directory":"extensions/pi-plan-mode"},"description":"Pi extension that adds a read-only plan mode for safe code exploration, step tracking, and constrained tool execution.","maintainers":[{"name":"arichiardi","email":"a.richiardi.work@gmail.com"}],"readme":"# @ar-llm/pi-plan-mode\n\n[![MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)\n\nPi extension that adds a read-only plan mode for safe code exploration. Restricts tools, tracks numbered plan steps with `/plan` and `/todos`, and shows progress in a widget.\n\n## Install\n\n```bash\npi install 'npm:@ar-llm/pi-plan-mode'\n```\n\nOr try without installing:\n\n```bash\npi -e 'npm:@ar-llm/pi-plan-mode'\n```\n\n## Usage\n\n### Toggle Plan Mode\n\n- **Command**: `/plan` - Toggle plan mode on/off\n- **Shortcut**: `Ctrl+Alt+P` - Toggle plan mode on/off\n- **Flag**: `--plan` - Start in plan mode\n\n### Commands\n\n- `/plan` - Toggle plan mode (read-only exploration)\n- `/todos` - Show current plan todo list\n\n## How It Works\n\nPlan mode provides a safe, read-only environment for code exploration and planning:\n\n1. **Tool Restrictions**: Only the configured read-only tools are available (default: `read`, `bash`, `grep`, `find`, `ls`, `questionnaire`)\n2. **Command Allowlist**: Bash commands are restricted to a configurable allowlist of safe, read-only commands\n3. **Plan Extraction**: Detects numbered plans under a configurable header (default: `Plan:`)\n4. **Progress Tracking**: Track completion with `[DONE:n]` markers (e.g., `[DONE:1]` marks step 1 complete)\n5. **UI Widgets**: Shows a progress widget and status bar during execution\n\n### Workflow\n\n1. Enable plan mode with `/plan` or `Ctrl+Alt+P`\n2. Ask the agent to explore and create a plan\n3. Agent generates a numbered plan under the configured header\n4. You are asked what to do next:\n   - **Execute the plan (track progress)** - when steps were detected; full tool access is restored and progress is tracked\n   - **Create the plan** - when no steps were detected; the agent is asked to produce an extractable plan and try again\n   - **Stay in plan mode** - keep exploring without executing\n   - **Refine the plan** - edit the plan before execution\n5. During execution, mark steps complete with `[DONE:n]` tags\n6. Widget shows progress (e.g., \"📋 2/5\")\n\n## Configuration\n\nCreate a config file at `~/.config/pi/agent/ar-llm/plan-mode.json` to customize behavior. Every section is optional and deep-merged over the built-in defaults.\n\n### Example Configuration\n\n```json\n{\n  \"commands\": {\n    \"safePatterns\": [\n      \"/^\\\\s*cat\\\\b/\",\n      \"/^\\\\s*grep\\\\b/\",\n      \"/^\\\\s*find\\\\b/\",\n      \"/^\\\\s*ls\\\\b/\",\n      \"/^\\\\s*git\\\\s+(status|log|diff)/i\"\n    ],\n    \"destructivePatterns\": [\n      \"/\\\\brm\\\\b/i\",\n      \"/\\\\bgit\\\\s+(add|commit|push)/i\"\n    ]\n  },\n  \"tools\": {\n    \"planModeTools\": [\"read\", \"bash\", \"grep\", \"find\", \"ls\"],\n    \"normalModeTools\": [\"read\", \"bash\", \"edit\", \"write\"]\n  },\n  \"planFormat\": {\n    \"planHeaderPattern\": \"/\\\\*{0,2}Plan:\\\\*{0,2}\\\\s*\\\\n/i\",\n    \"stepNumberPattern\": \"/^\\\\s*(\\\\d+)[.)]\\\\s+\\\\*{0,2}([^*\\\\n]+)/gm\",\n    \"doneMarkerPattern\": \"/\\\\[DONE:(\\\\d+)\\\\]/gi\",\n    \"maxStepLength\": 50,\n    \"cleanStepText\": true,\n    \"hints\": {\n      \"planHeader\": \"Plan:\",\n      \"stepPrefix\": \"1.\"\n    }\n  },\n  \"prompts\": {\n    \"planModeContext\": \"[PLAN MODE ACTIVE]\\nYou are in plan mode - read-only...\\nTools: {tools}\\nCreate a plan under a \\\"{planHeader}\\\" header\",\n    \"executionContext\": \"[EXECUTING PLAN]\\nRemaining steps:\\n{todoList}\\nUse [DONE:n] to mark complete\",\n    \"planCreationPrompt\": \"Your response had no extractable plan. Respond under a \\\"{planHeader}\\\" header with a numbered list, e.g. {stepPrefix} First step\"\n  },\n  \"ui\": {\n    \"showStatusBar\": true,\n    \"showProgressWidget\": true,\n    \"statusBarFormat\": \"📋 {completed}/{total}\",\n    \"notifications\": {\n      \"planModeEnabled\": \"Plan mode enabled. Tools: {tools}\",\n      \"planModeDisabled\": \"Plan mode disabled. Full access restored.\",\n      \"noTodos\": \"No todos. Create a plan first with /plan\",\n      \"planNotDetected\": \"No plan steps detected - the model did not use the expected plan format.\"\n    },\n    \"choices\": {\n      \"executeWithTodos\": \"Execute the plan (track progress)\",\n      \"createPlan\": \"Create the plan\",\n      \"stayInPlanMode\": \"Stay in plan mode\",\n      \"refinePlan\": \"Refine the plan\"\n    }\n  }\n}\n```\n\n### Config Fields\n\n#### `commands`\n\nCommand allowlist configuration.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `safePatterns` | `string[]` | Regex patterns for commands allowed in plan mode. A command must match at least one pattern. |\n| `destructivePatterns` | `string[]` | Regex patterns for commands blocked in plan mode. A command matching any pattern is blocked. |\n\n**Pattern format**: patterns are strings in the `/source/flags` form, e.g. `\"/^\\\\s*cat\\\\b/\"` or `\"/^\\\\s*git\\\\s+status/i\"`. The flags after the closing slash are honoured.\n\n#### `tools`\n\nTool restriction configuration.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `planModeTools` | `string[]` | Tools available in plan mode (read-only). Default: `[\"read\", \"bash\", \"grep\", \"find\", \"ls\", \"questionnaire\"]` |\n| `normalModeTools` | `string[]` | Tools available in normal mode (full access). Default: `[\"read\", \"bash\", \"edit\", \"write\"]` |\n\n#### `planFormat`\n\nThe plan format contract: regex patterns for parsing, plus the words used in prompts.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `planHeaderPattern` | `string` | Regex to detect the plan header. Default: `\"/\\\\*{0,2}Plan:\\\\*{0,2}\\\\s*\\\\n/i\"` |\n| `stepNumberPattern` | `string` | Regex for numbered steps. Default: `\"/^\\\\s*(\\\\d+)[.)]\\\\s+\\\\*{0,2}([^*\\\\n]+)/gm\"` |\n| `doneMarkerPattern` | `string` | Regex for `[DONE:n]` markers. Default: `\"/\\\\[DONE:(\\\\d+)\\\\]/gi\"` |\n| `maxStepLength` | `number` | Maximum step text length before truncation. Default: `50` |\n| `cleanStepText` | `boolean` | Remove markdown formatting from step text. Default: `true` |\n| `hints.planHeader` | `string` | Header the model is told to use. Must match `planHeaderPattern`. Default: `\"Plan:\"` |\n| `hints.stepPrefix` | `string` | First-step prefix shown as an example. Must match `stepNumberPattern`. Default: `\"1.\"` |\n\nUnlike the pattern fields above, `hints` are plain strings (no regex) injected into the prompt templates. They must describe the same format the patterns parse. If you change the vocabulary (for example to `Action Items:` and `1)`), change both the pattern and the matching hint.\n\n#### `prompts`\n\nPrompt template configuration. Templates support `{planHeader}`, `{stepPrefix}` and `{maxStepLength}` (from `planFormat`) plus the call-specific placeholders listed below; unknown placeholders are left untouched.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `planModeContext` | `string` | Injected when plan mode starts. Placeholder: `{tools}`. |\n| `executionContext` | `string` | Injected while executing a plan. Placeholder: `{todoList}`. |\n| `planCreationPrompt` | `string` | Sent when no plan steps could be extracted. |\n\n#### `ui`\n\nUI configuration.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `showStatusBar` | `boolean` | Show the plan-mode indicator in the status bar. Default: `true` |\n| `showProgressWidget` | `boolean` | Show the todo-list widget during execution. Default: `true` |\n| `statusBarFormat` | `string` | Status bar format. Placeholders: `{completed}`, `{total}`, `{mode}`. Default: `\"📋 {completed}/{total}\"` |\n| `notifications.planModeEnabled` | `string` | Notification when plan mode is enabled. Placeholder: `{tools}`. |\n| `notifications.planModeDisabled` | `string` | Notification when plan mode is disabled. |\n| `notifications.noTodos` | `string` | Shown by `/todos` when there are no todos. |\n| `notifications.planNotDetected` | `string` | Shown when the last message had no extractable plan. |\n| `choices.executeWithTodos` | `string` | Selection label for executing a detected plan. |\n| `choices.createPlan` | `string` | Selection label for asking the model to produce a plan. |\n| `choices.stayInPlanMode` | `string` | Selection label for staying in plan mode. |\n| `choices.refinePlan` | `string` | Selection label for refining the plan. |\n\n### Resolution Order\n\nConfiguration is resolved in this order (later overrides earlier):\n\n1. **Built-in defaults** - Safe, conservative defaults\n2. **Config file settings** - Your preferences in `plan-mode.json`\n\n## License\n\n[MIT](./LICENSE) — derived from [earendil-works/pi](https://github.com/earendil-works/pi), copyright Mario Zechner.","readmeFilename":"README.md"}