Subshell Docs

pi

Run pi as a Subshell agent.

Before you start

Install pi using the vendor instructions and authenticate it under the execution account. Ask an administrator to enable the harness under Settings → Server Settings → Plugins in the server dashboard's sidebar. Follow Install an agent CLI to confirm detection on the target node.

Launch

  1. In the server dashboard's sidebar, choose Subshells, select New subshell, and choose pi.
  2. Select a preset or configure the supported launch settings.
  3. Choose the target node and an existing project directory.
  4. Launch and confirm that the CLI opens normally.

The plugin detects pi through PATH and its known locations. PI_PATH can identify the binary explicitly in the execution environment. Before changing that override, see Files and paths for configuration locations and service-environment guidance.

MCP and session behavior

pi needs the community MCP adapter extension and a registered MCP server on each execution host. The built-in plugin declares MCP and settings capabilities; it doesn't declare automatic conversation resumption or attention hooks.

Subshell runs the real CLI rather than proxying its provider API. Provider configuration, usage limits, and CLI-specific permissions remain the agent's own settings.

Install the adapter

pi install npm:pi-mcp-adapter

Register the server in ~/.config/mcp/mcp.json or your project's .mcp.json, using the actual executable for that host:

{
  "mcpServers": {
    "subshell": { "command": "subshell", "args": ["mcp"] }
  }
}

The MCP child inherits its identity from the launched pane. A normal shell outside Subshell lacks that identity.

Next steps

Read MCP configuration, Presets, and Agent and launch errors.

Edit on GitHub

Last updated on

On this page