---
slug: "to-agent"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/sanatankc/to-agent@main/README.md"
repo: "https://github.com/sanatankc/to-agent"
source_file: "README.md"
branch: "main"
---
# to-agent

Send the current file or selection from Cursor or VS Code to a running [pi](https://github.com/earendil-works/pi-mono) coding-agent session.

Press `cmd+alt+l` on macOS or `ctrl+alt+l` on Windows/Linux. A whole file is inserted as an `@file` reference; a selection is inserted as a path-labelled fenced code block with line numbers.

## Install

```bash
npx to-agent install
```

The installer detects Cursor and VS Code, installs the editor extension, installs the matching pi adapter, and keeps both sides on the same version.

For an explicit, non-interactive installation:

```bash
npx to-agent install --editor cursor --agent pi
npx to-agent install --editor vscode --agent pi
```

Restart the editor after installation, start pi in a terminal, and click the **to-agent** status item to select a running session.

## Commands

```bash
npx to-agent install
npx to-agent doctor
npx to-agent uninstall
```

## How it works

Each pi instance publishes discovery metadata under `~/.to-agent/instances/` and listens on a local Unix socket (macOS/Linux) or named pipe (Windows):

```text
~/.to-agent/instances/<id>.json
~/.to-agent/instances/<id>.sock   # macOS/Linux
```

The editor discovers live instances and holds one persistent socket connection to the selected session. The connection is also the presence signal shown on both sides.

The local JSONL protocol is versioned. Version 1 accepts:

```json
{ "type": "attach", "file": "/abs/path.ts", "startLine": 10, "endLine": 20, "text": "..." }
```

Selection fields are omitted for whole-file attachments.

## Current support

| Editor | Agent | Status |
| --- | --- | --- |
| Cursor | pi | Beta |
| VS Code | pi | Beta |
| Zed | — | Planned; subject to extension API support |
| — | Claude Code, Codex, OpenCode | Exploring plugin capabilities |

## Development

Requirements: Node.js 18+, npm, and pi. Install dependencies and build:

```bash
npm install
npm run check
```

Useful paths:

```text
cursor-extension/src/extension.ts  Cursor / VS Code adapter
pi-extension/to-agent.ts          pi adapter
bin/to-agent.js                    installer and diagnostics CLI
artifacts/to-agent.vsix            generated editor package
```

Test the install plan without changing the machine:

```bash
node bin/to-agent.js install --editor cursor --agent pi --dry-run
```

For pi extension development, load the source directly:

```bash
pi -e ./pi-extension/to-agent.ts
```

## License

MIT