{"_id":"@ac5tin/pi-subagents-lite","name":"@ac5tin/pi-subagents-lite","dist-tags":{"latest":"1.13.1"},"versions":{"1.13.1":{"name":"@ac5tin/pi-subagents-lite","version":"1.13.1","description":"Lightweight sub-agents for pi — spawn specialized agents with isolated sessions, tools, and models.","keywords":["pi-package","pi","pi-agent","pi-coding-agent","pi-extension","subagents","ai","agents"],"author":{"name":"AlexParamonov"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/ac5tin/pi-subagents-lite.git"},"homepage":"https://github.com/ac5tin/pi-subagents-lite#readme","bugs":{"url":"https://github.com/ac5tin/pi-subagents-lite/issues"},"publishConfig":{"access":"public"},"peerDependencies":{"@earendil-works/pi-ai":">=0.82.0","@earendil-works/pi-coding-agent":">=0.82.0","@earendil-works/pi-tui":">=0.82.0"},"dependencies":{"@sinclair/typebox":"^0.34.52"},"scripts":{"format":"prettier --write src/ test/","format:check":"prettier --check src/ test/","typecheck":"tsc --noEmit","test":"vitest run","test:any-gate":"bash scripts/test-any-gate.sh"},"pi":{"extensions":["./src/index.ts"]},"devDependencies":{"@earendil-works/pi-coding-agent":"^0.84.2","prettier":"^3.9.6","typescript":"^7.0.2","vitest":"^4.1.7"},"gitHead":"7b750685c8154b4f023a1759741f00a35769b39a","_id":"@ac5tin/pi-subagents-lite@1.13.1","_nodeVersion":"26.7.0","_npmVersion":"12.0.2","dist":{"integrity":"sha512-/5iK15Zc0lBPGR9jGHCt4vBaQ5ktTKjLyt7NBMa6wzGYdUg2h//M2VaWx01HXeJnLpAEnjMJ16ed+Pq8nCwJow==","shasum":"9488fb94d3b9d544448c0c390df29580feac7bab","tarball":"https://registry.npmjs.org/@ac5tin/pi-subagents-lite/-/pi-subagents-lite-1.13.1.tgz","fileCount":61,"unpackedSize":524577,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEf5ujaa7BO65ghjb0+03ho33MeW/beLntnyKTDt8c5lAiAeJ/+NofYYOWV5pNf0qJag0A39vT3sNuMEsexk+xqZLg=="}]},"_npmUser":{"name":"ac5tin","email":"austinchang4@gmail.com"},"directories":{},"maintainers":[{"name":"ac5tin","email":"austinchang4@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-subagents-lite_1.13.1_1788194995209_0.16591185608441106"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T16:49:54.999Z","1.13.1":"2026-08-31T16:49:55.406Z","modified":"2026-08-31T16:49:55.661Z"},"maintainers":[{"name":"ac5tin","email":"austinchang4@gmail.com"}],"description":"Lightweight sub-agents for pi — spawn specialized agents with isolated sessions, tools, and models.","homepage":"https://github.com/ac5tin/pi-subagents-lite#readme","keywords":["pi-package","pi","pi-agent","pi-coding-agent","pi-extension","subagents","ai","agents"],"repository":{"type":"git","url":"git+https://github.com/ac5tin/pi-subagents-lite.git"},"author":{"name":"AlexParamonov"},"bugs":{"url":"https://github.com/ac5tin/pi-subagents-lite/issues"},"license":"MIT","readme":"# pi-subagents-lite\n\n[![npm version](https://img.shields.io/npm/v/@ac5tin/pi-subagents-lite)](https://www.npmjs.com/package/@ac5tin/pi-subagents-lite)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nSub-agents for [pi](https://pi.dev). Schema-first, minimal token overhead.\n\nSpawn custom agents in isolated session with own tools, extensions and model. Three tools, no descriptions, minimal token overhead. Names like `Agent`, `run_in_background`, and `worktree_path` are the schema.\n\nForeground and background agents with detailed model configuration, concurrency, custom agent types, steering and continuation, cross-repo worktree support, configurable system prompt modes, a live widget and conversation viewer with cost tracking, and a watchdog for stuck agents.\n\n## Install\n\nRequires Node.js >= 18 and pi >= 0.82.0.\n\n```bash\npi install npm:@ac5tin/pi-subagents-lite\npi install -l npm:@ac5tin/pi-subagents-lite   # project-local\npi -e npm:@ac5tin/pi-subagents-lite           # try without installing\n```\n\n## Usage\n\nThe LLM calls `Agent` like any other tool. Foreground agents return inline with stats. Background agents acknowledge immediately and auto-deliver on completion.\n\n```\n◈ Agents\n  ⠧ builder  Bump all gpu_inference_proxy deps to latest  6⟳ ·↑7k↓2k 2%·$0.00·54s\n  │ MiMo V2.5 • high\n  └ running command…\n  ⠧ scout  Explore keepalive events config  25⟳ ·↑79k↓5k 8%·$0.01·2m 39s\n  │ MiMo V2.5 • high\n  └ Now I have enough information to provide a comprehensive answer.\n```\n\nThe widget shows running and recently finished agents above the editor. `↓`/`↑` highlights an agent, `Enter` opens the conversation viewer, `Esc` closes navigation. The viewer streams the live transcript: thinking blocks, tool calls, compaction summaries, and results.\n\nThe `/agents` menu covers running agents (view, steer, continue settled agents, stop, clear), manual spawns without an LLM round-trip, model settings, concurrency, and widget layout.\n\n### Agent tools\n\n- `Agent` spawns a sub-agent (see [Agent options](#agent-options) for parameters).\n- `StopAgent` stops a running or queued agent by ID. IDs come from the spawn result, the stop error, or `/agents`.\n- `AgentStatus` lists all agents with type, short ID, and status.\n\nForeground agents dont lock the session and can be stopped by parent's interrupt. Background agents are fully autonomous.\n\n### Steering and continuation\n\nSteer a running agent mid-task to redirect it: `Enter` in the conversation viewer, or `Steer` in the `/agents` menu. Settled agents (completed, errored, stopped, turn-limited) can be continued manually from the conversation viewer.\n\n## Built-in agents\n\n- `general-purpose` does general task execution using the configured session tools.\n- `Explore` does read-only codebase exploration.\n\nBuilt-ins can be overridden by custom agents or disabled from `/agents`. Disabling takes effect immediately for future `Agent` calls. Running and queued agents continue with the policy captured at spawn.\n\n## Custom agents\n\nDrop a `.md` file into `.pi/agents/` (project), `.agents/agents/` (shared), or `~/.pi/agent/agents/` (global). Frontmatter configures the agent, the body is its system prompt. The name auto-populates the `agent` parameter's enum, so nothing needs registering. On name clash, project > shared > user > built-in. Type names resolve case-insensitively.\n\n```markdown\n---\nname: security-review\ndescription: Review code for security issues\ntools: [read, bash, grep]\nextensions: false\nskills: false\nmodel: zai/glm-5.2\nthinking: high\nmax_turns: 80\n---\n\nYou are a security review specialist. Analyze code for vulnerabilities,\nfocusing on injection flaws, auth bypasses, and insecure defaults.\n```\n\nA minimal agent with just `name` and `description` gets everything, same as `general-purpose`. Set restrictions only when you want them.\n\n### Frontmatter reference\n\n| Field | Type | Default | Description |\n|---|---|---|---|\n| `name` | string | — | Agent type name. Must be unique; a file without it is skipped. |\n| `display_name` | string | `name` | Label in the UI. |\n| `color` | string | none | Agent color for icon tinting. Named colors: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. Palette aliases: `amber`, `teal`, `indigo`, `gold`, `violet`, `rose`, `lime`, `gray`, `slate`, `navy`, etc. Also accepts `#RRGGBB` hex. |\n| `description` | string | `\"\"` | One-sentence description. |\n| `tools` | `true` \\| `string[]` \\| `false` | `true` | Tool whitelist. Mutually exclusive with `exclude_tools`. |\n| `exclude_tools` | `string[]` | none | Tool blacklist. Mutually exclusive with `tools`. |\n| `extensions` | `true` \\| `string[]` \\| `false` | `true` | Which extensions load (hooks and commands). Does not control tool visibility. |\n| `exclude_extensions` | `string[]` | none | Extension blacklist. |\n| `skills` | `true` \\| `string[]` \\| `false` | `true` | Skill whitelist (metadata-only in system prompt). |\n| `preload_skills` | `string[]` \\| `false` | `false` | Dump full SKILL.md content into the system prompt. Expensive. |\n| `model` | string | inherit parent | `\"provider/model-id\"`. See [Model resolution](#model-resolution). |\n| `thinking` | string | inherit parent | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. |\n| `max_turns` | number | unlimited | Soft turn limit, then grace turns before hard abort. |\n| `max_tokens` | number | unlimited | Max output tokens per LLM response. |\n| `hidden` | boolean | `false` | Hide from the enum. Still callable by name. |\n| `output_transcript` | boolean | inherit global | Write streaming transcript to `/tmp/pi-agent-outputs/<agentId>.log` (frontmatter overrides). |\n| `include_context_files` | boolean | inherit global | Include AGENTS.md files as `<project_context>` in the system prompt. `true` = load, `false` = none, unset = global \"Include AGENTS.md\" setting. |\n| `include_system_prompt` | boolean | inherit global | Include the parent's system prompt for this agent. `true` = inherit parent, `false` = replace mode, unset = global mode. When the global mode is `custom`, the custom prompt wins over `true`. |\n\nTool and extension lists accept built-in names (`read`, `bash`, `edit`, `write`, `grep`), extension tool names (`web_search`), and `ext/*` globs (`tavily/*`). `exclude_tools: [tavily/*]` hides the tools but the extension still loads. Use `exclude_extensions: [tavily]` to prevent loading.\n\n`loadSkillsImplicitly` and `loadExtensionsImplicitly` (config, default ON) decide what an agent gets when frontmatter omits `skills` or `extensions`. Turn them OFF to default new agents to nothing and opt in explicitly.\n\n## Agent options\n\n`Agent` accepts:\n\n- `prompt` (required) is the task text.\n- `description` is a short label for the widget; defaults to the first line of the prompt.\n- `agent` is the agent type; defaults to `general-purpose`.\n- `run_in_background` makes the agent return immediately and notify the parent when complete.\n- `worktree_path` is any git repository on disk: a worktree of the parent's repo, its main checkout, or a different repo entirely. See [Worktree paths and trust](#worktree-paths-and-trust).\n\n`model`, `thinking`, `max_turns`, and `max_tokens` are injected from config and frontmatter, never passed by the LLM. Set them once and forget.\n\nSubagents cannot spawn further subagents.\n\n### Worktree paths and trust\n\n`worktree_path` accepts a path inside any git repository on disk: a linked worktree of the parent's repo, its main checkout, or a different repo entirely. The subagent runs with that directory as its working directory. A path outside any git repo is rejected.\n\nCross-repo targets are gated by pi's existing trust framework. The target's saved trust decision (nearest ancestor wins) applies, and an undecided target falls back to the global `defaultProjectTrust` setting. Anything other than \"always\" means untrusted. An untrusted target still spawns, but its project resources (`.pi/` settings, extensions, skills, prompts, themes, system prompt files, `.agents/skills`) are ignored, its `.pi/agents` types are not discovered, the extension's project config (`.pi/subagents-lite.json`) is not loaded, and pi surfaces a warning. Same-repo paths are never gated. The `/agents` spawn wizard still lists same-repo worktrees only.\n\n## Model resolution\n\nPrecedence, highest first:\n\n1. Session per-type override (`/agents` > Model settings)\n2. Session global default\n3. Config per-type override (`~/.pi/agent/subagents-lite.json`)\n4. Config global default\n5. Agent frontmatter `model`\n6. Parent model\n\n## Thinking level resolution\n\nPrecedence, highest first:\n\n1. Session per-type override (`/agents` > Model settings → type → Thinking)\n2. Config per-type override (`\"thinking:<type>\"` key)\n3. Agent frontmatter `thinking`\n4. `defaultThinking` (project over global)\n5. pi's session default (`defaultThinkingLevel` setting, else `medium`)\n\nAn explicit `thinking` param beats everything, and the effective level is clamped to the resolved model's supported levels (non-reasoning models support only `off`).\n\n## Concurrency\n\n`concurrency` caps parallel agents. A per-model limit overrides a per-provider limit, which overrides the `default` per-model limit. Excess spawns queue until a slot frees.\n\n## Settings\n\nGlobal settings live in `~/.pi/agent/subagents-lite.json`, managed via `/agents` or edited directly. \n\n`/agents` covers model settings per-type overrides, concurrency, widget, spawn defaults (thinking, max turns, force-background), system prompt mode, watchdog timeouts.\n\nPer-type model and thinking overrides live under the Model settings menu: each type row opens a submenu with a **Model** and a **Thinking** row, and each pick targets a layer (session, global, or project). A config example with per-type model and thinking overrides:\n\n```json\n{\n  \"agent\": {\n    \"default\": \"anthropic/claude-sonnet-4-20250514\",\n    \"Explore\": \"openai/gpt-4o\",\n    \"thinking:Explore\": \"low\"\n  }\n}\n```\n\n```\nSettings\n\n→ Model                           Set global default and per-type model overrides\n  Concurrency                     Set per-model slot limits\n  Agent                           Agent limit, colors, output, thinking\n  System prompt                   Prompt mode, AGENTS.md, skills, extensions\n  Widget                          Configure widget display options\n```\n\nWidget is higly customizable as the rest of the extension\n\n### Project-level config\n\nA project can commit its own defaults as `.pi/subagents-lite.json` (same file name as the global one). This is an override layer, not a full config. It may contain only model and concurrency settings (`agent.default`, per-type model overrides, per-type thinking overrides (`\"thinking:<type>\"`), `concurrency`; `defaultThinking`/`defaultMaxTurns` are also allowed), and each key it sets overrides the global file's value. Every other setting (widget, watchdog, spawn defaults) always comes from the global file. The effective value of each key resolves as: session override > project file > global file > built-in default.\n\n### System prompt mode\n\n`systemPromptMode` (default `replace`):\n\n- `replace` uses a minimal generic prompt plus the agent's instructions. Lowest cost and most isolated.\n- `inherit` uses the parent's system prompt plus the agent's instructions.\n- `custom` uses `~/.pi/agent/subagents-lite-prompt.md` plus the agent's instructions.\n\nWhen `includeContextFiles` is `true` (default), AGENTS.md files load as shared context before agent instructions, which improves KV cache prefix hits.\n\n### Watchdog\n\nThe watchdog stops agents that hang. Two independent checks, both default 45 minutes, `0` disables:\n\n- `toolTimeoutMinutes`: a single tool call running longer than this stops the agent.\n- `idleTimeoutMinutes`: no activity (tool events or streamed response text) for this long stops the agent.\n\nThe watchdog notifies the main session on a kill so it can act accordingly.\n\n### Output transcripts\n\nOutput transcripts are disabled by default. Enable them globally via the `outputTranscript` config option or per-agent via the `output_transcript` frontmatter field. When enabled, the transcript streams to `/tmp/pi-agent-outputs/<agentId>.log` (append-only, `tail -f` friendly) and the widget shows the `tail -f` line. Logs and completed results survive on disk even if a session reload (`/reload`, extension reload) kills running agents.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-9501ade328f2db30480cac8b73aba710"}