pi-soloterm-tools

Optional Pi extension that exposes a focused set of SoloTerm MCP features as native Pi tools.

The extension also provides a bundled solo skill as a fallback. If Pi already has a solo skill available, this package leaves it alone; otherwise it contributes its bundled skill during resource discovery so agents know to use the SoloTerm bridge.

Install

From npm:

pi install pi-solo-term-tools

From GitHub:

pi install https://github.com/scottwater/pi-soloterm-tools

For live child-agent testing, install it with pi install; pi -e only affects the current parent process.

SoloTerm tools and skill are enabled when installed

Once the package is installed, new Pi sessions expose the SoloTerm tools automatically. You do not need to pass --soloterm just to use them.

If Pi does not already have a solo skill, the extension adds its bundled fallback skill automatically. Existing user or project solo skills take precedence.

--soloterm is still accepted as an explicit enable/compatibility flag, and /soloterm can be used inside Pi:

/soloterm on
/soloterm off
/soloterm status

When active, the footer/status line shows ◫ soloterm.

Tools

• solo_status — verifies SoloTerm/Pi mode, Solo MCP state, session identity, and feature support.
• solo_task — spawns Solo agent panes through Solo MCP, sends prompts, waits for idle output, and optionally uses scratchpad artifacts.
• solo_process — lists, inspects, reads output from, sends input to, and closes Solo-managed processes. Use action: "send" with processId and non-empty input (or message) to answer a prompt or grant a required approval. Use action: "close_subagents" to safely close Pi-spawned --soloterm child-agent panes in the current/effective project.
• solo_todo — mirrors task lists to Solo todos when available and keeps a Pi fallback.
• solo_scratchpad — lists, reads, and writes Solo scratchpads.

This is a focused Pi surface: status and identity, agent dispatch, process list/status/output/input/close, todos, and scratchpads. Timers, locks, project management, ports, and broader Solo MCP catalog operations are not currently exposed as native Pi tools. The extension intentionally does not provide a generic passthrough because that would bypass operation-specific safety guards. Direct non-Pi MCP harnesses may independently discover optional tools from Solo's catalog.

Spawned agents are not approved automatically. Monitor them with solo_process actions status and output; when an agent requires an answer or permission, use action: "send" with submit semantics.

Solo setup

1. Install and run Solo from https://soloterm.com.
2. In Solo, open Settings → MCP and enable the MCP server.
3. Optional but recommended: enable Scratchpads and Todos.
4. In Settings → Agents, add a Generic agent tool with command:

pi

solo_task looks for an enabled Solo agent tool whose command or name is pi. Child Pi agents get --soloterm when they are Pi agents, so install this package globally with pi install before testing child agents.

Troubleshooting

solo_status says MCP is disabled or unavailable

Make sure Solo is running and MCP is enabled in Settings → MCP. If Solo uses a non-default app data directory, set SOLOTERM_APP_DATA_DIR. If Solo is installed somewhere unusual, set SOLO_MCP_HELPER to the bundled helper path.

solo_task cannot find a Pi agent tool

In Solo Settings → Agents, add or enable a Generic agent tool with command pi.

Validation

npm test
npm pack --dry-run

License and attribution

MIT. See NOTICE.md.