PortPilot Assistant

Translate natural language into portpilot commands with safe defaults.

Workflow

• Classify intent into one of: scan , who , pick , doctor , free , init , config .

• Resolve target port/range/path from user text; if absent, apply defaults.

• For the first portpilot call in a new session, run one permission bootstrap to avoid repeated prompts (details below).

• Execute read actions directly (scan , who , pick , doctor ).

• For write actions (free , init --force , config migrate ), require explicit confirmation and show details.

• Return concise conclusion first, then command output details.

Intent mapping

• 帮我选个端口 / pick a port:

• portpilot pick --range 3000-3999 --count 1 --lease-ms 20000 --json

• 扫描当前端口 / scan current used ports:

• portpilot scan --protocol both --json

• 查看 3000 端口 / check port 3000:

• portpilot who 3000 --json

• 释放 3000 端口 / free port 3000:

• First portpilot who 3000 --json , then confirm, then portpilot free 3000 --yes --json

• 扫描冲突 / run doctor:

• portpilot doctor --json

• 初始化配置 / init port config:

• portpilot init --dry-run --json (default preview)

Safety policy

• Read actions run automatically.

• Write actions require confirmation.

• Confirmation payload must include: port , pid , command , cwd , startTime , action .

• If dependency failure occurs, run portpilot doctor --preflight --json and return install/fix commands.

Permission bootstrap (one-time)

• On the first portpilot action in a new session, proactively run one lightweight bootstrap command (portpilot doctor --json ) with escalation.

• Resolve bundled CLI absolute path first (path-independent):

• Preferred: $CODEX_HOME/skills/portpilot-assistant/assets/portpilot/bin/portpilot.js

• Fallback for repo-local usage: <repo>/.claude/skills/portpilot-assistant/assets/portpilot/bin/portpilot.js

• In that one-time escalation request, set:

• sandbox_permissions: require_escalated

• prefix_rule: ["node", "<resolved-portpilot-cli-absolute-path>"]

• Explain that this is a one-time approval to avoid repeated prompts for future portpilot commands.

• After approval, run requested commands normally without escalation.

• If bootstrap was not done (or approval was denied), and a read action fails with permission errors (Operation not permitted / netlink denied / lsof denied), rerun once with escalation.

• Write actions still require explicit user confirmation before execution.

Execution notes

• Run bundled CLI from this skill first: assets/portpilot/bin/portpilot.js .

• Fallback to npx only if bundled CLI is missing: npx -y portpilot-cli@1 ... .

• Always pass --json for machine-readable parsing in skill scripts.