AgentLink

AgentLink is a local bridge for connecting IDE plugins to running CLI agents such as Codex, Claude, or any command that can accept terminal/stdin input. It starts the agent process, publishes connection metadata, and accepts text from an IDE over a local transport so the text can be pasted into the running agent.

This MVP has no JSON protocol and no message framing: whatever the IDE plugin writes to the AgentLink socket is pasted into the agent.

On Linux/macOS, AgentLink uses a PTY by default for interactive commands so terminal applications work normally. Use --pipe for ordinary stdin/stdout programs when you need pipe behavior instead.

Install

Install from npm:

npm install -g ide-agent-link

Then run either CLI name:

ide-agent-link --help
ial --help

For local development:

npm install
npm run build

Using Bun as the package manager/script runner also works:

bun install
bun run build

Run from the repository:

npm run dev -- --help
npm start -- --help

CLI

ial codex
ial claude
ial my-agent xxx xxx
ial -n test codex
ial --name test claude xxx
ial -p 48721 codex
ial -h 127.0.0.1 my-agent
ial --pipe node ./agent.js

AgentLink only parses these options before the agent command:

-n, --name <name>
-h, --host <host>
-p, --port <port>
--pty
--pipe

Everything after the command is passed through unchanged as an argument array. AgentLink does not rebuild a command string.

Example:

ial -n project-a codex --full-auto

This starts:

codex --full-auto

If --name is omitted, AgentLink generates a random name.

--pty starts the command in an interactive terminal session. This is the default on Linux/macOS.

--pipe starts the command with ordinary stdin/stdout/stderr pipes. Use this for non-interactive programs when terminal echo, line buffering, or ANSI terminal behavior would get in the way. In pipe mode, stdout is also forwarded to connected clients.

Transports

Default transport is local IPC:

• Linux/macOS: Unix socket
• Windows: Named Pipe

If --host or --port is specified, AgentLink uses TCP. When only --port is specified, host defaults to 127.0.0.1.

ial -p 48721 codex

This publishes a TCP endpoint at:

127.0.0.1:48721

If --host is supplied without --port, AgentLink binds that host with an OS-assigned port and writes the actual port to connections.json.

Connection Registry

AgentLink writes active connections to:

~/.agent-link/connections.json

On Windows this resolves under:

%USERPROFILE%\.agent-link\connections.json

Example Unix socket entry:

{
  "version": 1,
  "connections": [
    {
      "id": "01JXXX",
      "name": "project-a",
      "agent": "codex",
      "pid": 12345,
      "transport": "unix",
      "address": "/tmp/agent-link/agent-link-project-a.sock",
      "createdAt": 1755390000000
    }
  ]
}

Example TCP entry:

{
  "id": "01JXXX",
  "name": "project-b",
  "agent": "codex",
  "pid": 12346,
  "transport": "tcp",
  "host": "127.0.0.1",
  "port": 48721,
  "createdAt": 1755390000000
}

Example Windows Named Pipe entry:

{
  "id": "01JXXX",
  "name": "project-c",
  "agent": "codex",
  "pid": 12347,
  "transport": "named-pipe",
  "address": "\\\\.\\pipe\\agent-link-project-c",
  "createdAt": 1755390000000
}

Each AgentLink startup scans the registry and removes stale entries by checking both the process PID and the published endpoint.

IDE Plugin Contract

An IDE plugin can integrate with this MVP using four steps:

1. Read ~/.agent-link/connections.json.
2. Pick a connection by name, agent, or transport metadata.
3. Connect to the Unix socket, Named Pipe, or TCP endpoint.
4. Send the text to paste.

For your shortcut workflow, the plugin can format the IDE selection however you want, for example:

File: src/example.ts
Lines: 10-24

<selected text>

Then write that text to the AgentLink socket. AgentLink pastes it directly into the agent session.

Unix sockets are not regular files, so shell redirection like > path.sock will not work. Use a socket-aware client instead:

printf 'hello\n' | nc -U /tmp/agent-link/agent-link-project-a.sock

For TCP transports:

printf 'hello\n' | nc 127.0.0.1 48721

Development

Run tests:

npm test
bun run test

Run typecheck:

npm run typecheck
bun run typecheck

Build the published JavaScript output:

npm run build

Current Limits

This MVP does not implement MCP, file editing APIs, remote agents, a Web UI, structured events, auth, permissions, or session state. Those can be layered onto the same registry and transport abstraction later.