pi-remote-agent

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

<p align="center">
  <img src="https://img.shields.io/badge/pi-extension-6C5CE7?style=for-the-badge" alt="pi extension" />
  <img src="https://img.shields.io/badge/tailscale-mesh-blue?style=for-the-badge&logo=tailscale" alt="Tailscale" />
  <img src="https://img.shields.io/npm/v/pi-remote-agent?style=for-the-badge&color=critical" alt="npm version" />
</p>

<h1 align="center">🌙 pi-remote-agent</h1>
<p align="center"><em>Delegate tasks to a friend's pi agent — securely, over Tailscale.</em></p>

---

## 🧠 What is this?

**pi-remote-agent** is a pi extension that lets your pi session talk to another pi instance running on a friend's machine. Think pair programming, second opinions, or delegating subtasks — all from within your pi TUI.

Your LLM can even call the remote agent *automatically* via the `ask_remote_agent` tool.

<p align="center">
  <img src="https://placehold.co/600x200/6C5CE7/white?text=You+%E2%86%94+Remote+Agent+via+Tailscale" alt="architecture diagram" />
</p>

---

## 🚀 Quick Start

### 1. Your friend sets up the bridge

On their machine, they run pi with the bridge enabled:

```bash
pi --bridge --rpc-port 18777
```

Their bridge will be reachable at `https://<their-tailscale-node>.ts.net/rpc`.

### 2. You configure the peer

Add their bridge URL to your remote agents config:

```bash
# ~/.pi/agent/remote-agents.json
{
  "friend": "https://friend-mac.tail1234.ts.net/rpc"
}
```

Or set it once via environment variable:

```bash
export REMOTE_AGENT_URL="https://friend-mac.tail1234.ts.net/rpc"
```

### 3. Install the extension

```bash
pi install npm:pi-remote-agent
```

### 4. Start delegating

```
# Command (manual)
/ask-agent @friend Refactor the auth module to use JWT instead of sessions

# Tool (LLM auto-invokes)
"When should I use a connection pool vs a single connection?"
→ LLM automatically calls ask_remote_agent
```

---

## 📖 Usage

### `/ask-agent` Command

```
/ask-agent <prompt>                → Uses default peer (REMOTE_AGENT_URL)
/ask-agent @friend <prompt>        → Targets a named peer from remote-agents.json
```

The command streams the response in real-time, showing which tools the remote agent is using (read, bash, edit, write).

### `ask_remote_agent` Tool

The LLM can also call the remote agent automatically. It's registered as a tool in your session, so you don't need to manually decide when to delegate — your model routes tasks that benefit from an external perspective.

```
┌──────────────────────────────────────────────────┐
│  You: "Is this SQL query vulnerable to injection?"│
│                                                   │
│  Arienz: 🔒 Asking Security SME (remote)...        │
│  Remote: ❌ Yes — 3 vulnerabilities found.        │
│          • Unsanitized input on line 12            │
│          • No parameterized query on line 18       │
│          • User input in ORDER BY clause           │
└──────────────────────────────────────────────────┘
```

---

## ⚙️ Configuration

| Key | Location | Description |
|-----|----------|-------------|
| `REMOTE_AGENT_URL` | Environment | Default bridge URL (fallback) |
| `remote-agents.json` | `~/.pi/agent/` | Named peers with bridge URLs |

```jsonc
// ~/.pi/agent/remote-agents.json
{
  "alice":   "https://alice-dev.tail1234.ts.net/rpc",
  "bob":     "https://bob-server.tail1234.ts.net/rpc",
  "work":    "https://ci-bot.work-net.ts.net/rpc"
}
```

---

## 🔒 Security

- All traffic routes through **Tailscale's encrypted mesh** — no open ports, no public exposure
- Sessions are ephemeral — created, used, and destroyed per-request
- Your API keys and credentials are never sent to the remote agent
- Extensions have full system access — review the source before installing (this repo is MIT-licensed and auditable at [index.ts](https://github.com/amanasmuei/pi-remote-agent/blob/HEAD/index.ts))

---

## 📁 Project Structure

```
pi-remote-agent/
├── index.ts          # Extension entry point (single file)
├── package.json      # pi package manifest
└── README.md         # You are here
```

---

## 🛠️ Development

```bash
# Clone and test locally
git clone https://github.com/aman-asmuei/pi-remote-agent
cd pi-remote-agent
pi install ./    # Install from local path

# Or test without installing
pi -e ./index.ts
```

---

## 📄 License

MIT © Aman — share, remix, and build on it freely.

---

<p align="center">
  <sub>Built with 🤲 for the pi ecosystem. <a href="https://pi.dev/packages">View on pi.dev →</a></sub>
</p>

🌙 pi-remote-agent

Delegate tasks to a friend's pi agent — securely, over Tailscale.

🧠 What is this?

pi-remote-agent is a pi extension that lets your pi session talk to another pi instance running on a friend's machine. Think pair programming, second opinions, or delegating subtasks — all from within your pi TUI.

Your LLM can even call the remote agent automatically via the ask_remote_agent tool.

architecture diagram

🚀 Quick Start

1. Your friend sets up the bridge

On their machine, they run pi with the bridge enabled:

pi --bridge --rpc-port 18777

Their bridge will be reachable at https://<their-tailscale-node>.ts.net/rpc.

2. You configure the peer

Add their bridge URL to your remote agents config:

# ~/.pi/agent/remote-agents.json
{
  "friend": "https://friend-mac.tail1234.ts.net/rpc"
}

Or set it once via environment variable:

export REMOTE_AGENT_URL="https://friend-mac.tail1234.ts.net/rpc"

3. Install the extension

pi install npm:pi-remote-agent

4. Start delegating

# Command (manual)
/ask-agent @friend Refactor the auth module to use JWT instead of sessions

# Tool (LLM auto-invokes)
"When should I use a connection pool vs a single connection?"
→ LLM automatically calls ask_remote_agent

📖 Usage

`/ask-agent` Command

/ask-agent <prompt>                → Uses default peer (REMOTE_AGENT_URL)
/ask-agent @friend <prompt>        → Targets a named peer from remote-agents.json

The command streams the response in real-time, showing which tools the remote agent is using (read, bash, edit, write).

`ask_remote_agent` Tool

The LLM can also call the remote agent automatically. It's registered as a tool in your session, so you don't need to manually decide when to delegate — your model routes tasks that benefit from an external perspective.

┌──────────────────────────────────────────────────┐
│  You: "Is this SQL query vulnerable to injection?"│
│                                                   │
│  Arienz: 🔒 Asking Security SME (remote)...        │
│  Remote: ❌ Yes — 3 vulnerabilities found.        │
│          • Unsanitized input on line 12            │
│          • No parameterized query on line 18       │
│          • User input in ORDER BY clause           │
└──────────────────────────────────────────────────┘

⚙️ Configuration

Key	Location	Description
`REMOTE_AGENT_URL`	Environment	Default bridge URL (fallback)
`remote-agents.json`	`~/.pi/agent/`	Named peers with bridge URLs

// ~/.pi/agent/remote-agents.json
{
  "alice":   "https://alice-dev.tail1234.ts.net/rpc",
  "bob":     "https://bob-server.tail1234.ts.net/rpc",
  "work":    "https://ci-bot.work-net.ts.net/rpc"
}

🔒 Security

All traffic routes through Tailscale's encrypted mesh — no open ports, no public exposure
Sessions are ephemeral — created, used, and destroyed per-request
Your API keys and credentials are never sent to the remote agent
Extensions have full system access — review the source before installing (this repo is MIT-licensed and auditable at index.ts)

📁 Project Structure

pi-remote-agent/
├── index.ts          # Extension entry point (single file)
├── package.json      # pi package manifest
└── README.md         # You are here

🛠️ Development

# Clone and test locally
git clone https://github.com/aman-asmuei/pi-remote-agent
cd pi-remote-agent
pi install ./    # Install from local path

# Or test without installing
pi -e ./index.ts

📄 License

_{Built with 🤲 for the pi ecosystem. View on pi.dev →}