Extension design notes
Use this skill when creating or reviewing extensions so imports keep working after reloads.
Avoid this pattern
Do not import from the workspace source tree (for example /workspace/piclaw/runtime/src/... or /workspace/.../node_modules).
The running agent uses the installed package. Workspace paths can drift or break after reloads.
Use the installed package instead
Reference the installed dist paths, for example:
import { createBatchExecTool } from "/home/agent/.bun/install/global/node_modules/piclaw/dist/tools/context-tools.js";
Safety checklist
- Use installed dist paths (not workspace source).
- Avoid touching the DB before init.
- Wrap tool handlers in
try/catchto avoid crashes. - Guard filesystem access and
saveToolOutputcalls. - Keep dependencies minimal and explicit.
Quick audit
rg -n "/workspace/piclaw/runtime/src|/workspace/.*/node_modules" /workspace/.pi/extensions
Update skel when changing extensions
cp /workspace/.pi/extensions/<name>.ts /workspace/piclaw/skel/.pi/extensions/<name>.ts