MCP Server
Usage Guide
Which tool to reach for, with patterns worth copying and cases worth skipping.
When to use each tool
| Situation | Tool | Example |
|---|---|---|
| Long task finished | hwip_notify | Build complete, test results, deploy done |
| Need a decision, buttons plus optional free text | hwip_ask | "Tests green. Deploy?" with a custom-instruction escape hatch |
| Free-form input only | hwip_ask without actions | Commit message, env var value, description |
| Share code or logs | hwip_file | Error logs, test reports, generated config |
| Share a snippet | hwip_clipboard | URL, shell command |
| Label this session | hwip_session_rename | Name the run "Prod deploy" so parallel sessions stay distinguishable on the phone |
| Pass work to another agent | hwip_agent_send | "Send the summary to the pi session on my other PC" |
| See what agents on this machine are doing | hwip_agent_list, then hwip_agent_read | "What is the Codex session working on?" |
Patterns worth copying
Decision gate with an escape hatch — the preferred shape, because it lets the user answer something you did not anticipate:
hwip_ask(
title: "Tests green. Deploy to production?",
actions: [
{ id: "deploy", label: "Deploy", style: "primary" },
{ id: "hold", label: "Hold", style: "secondary" }
],
placeholder: "Or tell me what to do instead...",
fallback: "hold"
)Task completion notification:
hwip_notify(
title: "Build complete: web app",
body: "All 42 tests passed. Bundle size: 1.2MB (-3%)"
)Error alert with a link:
hwip_notify(
title: "CI failed: lint errors",
body: "2 errors in src/auth.ts",
url: "https://github.com/org/repo/actions/runs/456",
priority: "high"
)When not to use these
- Short responses the user can see immediately in the terminal.
- Read-only operations such as file search or code analysis.
- Every single tool call. Notify on meaningful milestones only.
Multi-session workflow
When running several agent sessions in parallel, use hwip_notify to signal completion so the
user knows which session finished without checking each terminal. Use hwip_session_rename to
give each one a name, and hwip_agent_send to hand work from one session to another.
For the plugin that wires these tools into Claude Code sessions, see the plugin.