@huntye1/pi-remote-tools

简体中文

A Pi package that adds SSH-backed tools for multiple named remote workspaces without replacing Pi's ordinary local tools.

It registers four additive tools:

• remote_read
• remote_write
• remote_edit
• remote_bash

Every remote tool call requires a workspace argument. There is no default workspace: Pi is prompted to distinguish the local workspace from every configured remote workspace and to ask when the intended workspace is ambiguous.

Local read, write, edit, bash, and user-entered ! commands remain local.

Install

Install globally for your Pi user:

pi install npm:@huntye1/pi-remote-tools

Or add it only to the current trusted project:

pi install --local npm:@huntye1/pi-remote-tools

The extension invokes the system ssh command. Configure authentication, host aliases, ProxyJump, and other transport behavior in ~/.ssh/config; authentication must be non-interactive.

Configure a project

Create <project>/.pi/remote-tools.json:

{
  "local": {
    "desc": "Local integration and tooling repository"
  },
  "workspaces": {
    "frontend": {
      "desc": "Frontend application and browser tests",
      "target": "frontend-box",
      "cwd": "/srv/frontend"
    },
    "backend": {
      "desc": "Backend APIs, data model, and service tests",
      "target": "backend-box",
      "cwd": "/srv/backend",
      "path": "/home/user/.local/bin:/usr/local/bin:/usr/bin:/bin"
    }
  }
}

local.desc and every remote workspace's desc are required. They tell the agent what each project is responsible for and help it route a request without treating any workspace as the default.

Each remote workspace requires:

• a unique alias matching [A-Za-z][A-Za-z0-9_-]*
• desc
• target

cwd is optional. If omitted, it is resolved with remote pwd -P on first use. path is optional; when omitted, the extension probes the remote login shell on first use to preserve PATH entries from tools such as nvm or fnm.

local is a reserved remote workspace alias.

Project configuration is read only after Pi trusts the project.

Breaking change: the former single-workspace top-level target, cwd, and path schema and the --remote-ssh, --remote-cwd, and --remote-path flags are no longer supported.

Tool calls

Every call explicitly names a remote workspace:

{
  "workspace": "frontend",
  "path": "src/app.ts"
}

{
  "workspace": "backend",
  "command": "npm test",
  "timeout": 300
}

Passing workspace: "local" to a remote tool is rejected. Use Pi's ordinary local tools for the local workspace.

Workspace instructions

The extension does not eagerly read instruction files from every host. Instead, its prompt tells the agent to select the relevant workspace and then read applicable AGENTS.md files on demand:

• local AGENTS.md files are read with local tools
• remote AGENTS.md files are read with remote_read or remote_bash and an explicit workspace
• nested AGENTS.md files are checked between the workspace root and the target directory
• unrelated workspaces are not contacted or injected into context

This avoids startup SSH traffic, stale instruction caches, unrelated prompt growth, and cross-workspace instruction conflicts.

Status

Use /remote-tools-status in an interactive Pi session to list the local workspace and every configured remote workspace, including paths and descriptions.

Notes

• Relative remote paths resolve from the selected workspace's configured or discovered cwd.
• Absolute paths inside the local project root are translated to the corresponding path under the selected remote cwd; other absolute paths are treated as remote paths.
• Remote cwd and PATH discovery are lazy and cached independently per workspace. A failed connection does not disable other workspaces.
• Remote file operations are included in Pi compaction summaries as remote:<workspace>:<path>.
• User-entered ! and !! commands remain local.

Development and publishing

Pi runs package TypeScript extensions through its extension loader; no JavaScript compilation step is required.

npm run check
npm run pack:check
pi --extension ./packages/pi-remote-tools
npm publish --access public

Pi host APIs are optional peer dependencies supplied by Pi. The published package contains the extension source, both READMEs, license, and package metadata.

License

MIT