cli-pipe-provider

A pi-ai provider for CLI tools that produce stream-json output, with built-in MCP tool bridge support.

Prerequisites

• A CLI that supports -p --output-format stream-json (pipe mode with JSON streaming)
• Node.js >= 20
• @mariozechner/pi-ai ^0.54.0 (peer dependency)

Install

npm install cli-pipe-provider

Usage

There are two modes: simple streaming (no tools) and streaming with MCP tool bridge.

Simple streaming (no tools)

If you just need text/thinking streaming without tool use:

import { createCliPipeProvider } from "cli-pipe-provider";

const pipe = createCliPipeProvider({
  command: "claude",
  bridgeEntryPoint: "/dev/null",  // not used when tools are disabled
  mcpServerName: "unused",
});

pipe.register();

const model = pipe.createModel({ modelId: "claude-sonnet-4-6" });

const stream = pipe.stream(
  model,
  {
    systemPrompt: "You are a helpful assistant.",
    messages: [{ role: "user", content: "Hello!" }],
  },
  { enableTools: false },
);

for await (const event of stream) {
  if (event.type === "text_delta") {
    process.stdout.write(event.delta);
  }
}

Streaming with tool use

To give the CLI access to your tools, you need two files:

1. Write a bridge entry script

This is a standalone Node.js file that the CLI spawns as an MCP server. It exposes your tools over the MCP protocol.

Using serveMcpBridge with pi-ai agent tools:

// bridge.ts
import { serveMcpBridge } from "cli-pipe-provider";
import type { AgentTool } from "@mariozechner/pi-agent-core";
import { Type } from "@sinclair/typebox";

const tools: AgentTool[] = [
  {
    name: "get_weather",
    description: "Get the weather for a city",
    parameters: Type.Object({
      city: Type.String({ description: "City name" }),
    }),
    async execute(callId, args) {
      return {
        content: [{ type: "text", text: `Weather in ${args.city}: sunny, 22°C` }],
      };
    },
  },
];

await serveMcpBridge(tools, { serverName: "my-app" });

Or using a raw MCP server with @modelcontextprotocol/sdk:

// bridge.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({ name: "my-tools", version: "1.0.0" });

server.tool("get_weather", { city: { type: "string" } }, async ({ city }) => ({
  content: [{ type: "text", text: `Weather in ${city}: sunny, 22°C` }],
}));

const transport = new StdioServerTransport();
await server.connect(transport);

2. Create the provider and stream

Point bridgeEntryPoint at the compiled bridge script:

import { createCliPipeProvider } from "cli-pipe-provider";

const pipe = createCliPipeProvider({
  command: "claude",
  bridgeEntryPoint: "/absolute/path/to/dist/bridge.js",
  mcpServerName: "my-app",
});

pipe.register();

const model = pipe.createModel({ modelId: "claude-sonnet-4-6" });

const stream = pipe.stream(
  model,
  {
    systemPrompt: "You have a get_weather tool. Use it to answer questions.",
    messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
  },
);

for await (const event of stream) {
  if (event.type === "text_delta") {
    process.stdout.write(event.delta);
  }
  if (event.type === "toolcall_end") {
    console.log("\nTool called:", event.toolCall.name, event.toolCall.arguments);
  }
}

The provider writes a temporary MCP config, spawns the CLI with --mcp-config, and the CLI discovers and calls your tools during its agentic loop. The config is cleaned up automatically when the stream ends.

Using with the pi coding agent

This package is also a pi package that registers cli-pipe as a model provider for the pi coding agent.

Install as a pi package

pi install git:github.com/robzolkos/cli-pipe-provider

Then use /model to select cli-pipe/claude-sonnet-4-6 or cli-pipe/claude-opus-4-6.

Or try it without installing:

pi -e git:github.com/robzolkos/cli-pipe-provider --model cli-pipe/claude-sonnet-4-6

As an SDK integration

import { createCliPipeProvider } from "cli-pipe-provider";
import {
  AuthStorage,
  createAgentSession,
  ModelRegistry,
  SessionManager,
} from "@mariozechner/pi-coding-agent";

const pipe = createCliPipeProvider({
  command: "claude",
  bridgeEntryPoint: "/dev/null",
  mcpServerName: "unused",
});
pipe.register();

const model = pipe.createModel({ modelId: "claude-sonnet-4-6" });

// cli-pipe doesn't need a real API key (the local CLI handles auth),
// but the coding agent requires one to be set.
const authStorage = AuthStorage.create();
authStorage.setRuntimeApiKey("cli-pipe", "not-needed");
const modelRegistry = new ModelRegistry(authStorage);

const { session } = await createAgentSession({
  model,
  sessionManager: SessionManager.inMemory(),
  authStorage,
  modelRegistry,
});

session.subscribe((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

await session.prompt("What files are in the current directory?");

See examples/ for runnable versions.

Stream options

pipe.stream(model, context, {
  // Enable/disable MCP tool bridge (default: true)
  enableTools: true,

  // Thinking/reasoning level
  reasoning: "high",

  // Additional CLI args for the bridge script
  bridgeArgs: ["--verbose"],

  // Session ID for conversation continuity
  sessionId: "my-session",

  // Abort signal
  signal: controller.signal,
});

Events emitted

Event	Description
start	Stream opened, partial output available
text_start / text_delta / text_end	Text content streaming
thinking_start / thinking_delta / thinking_end	Reasoning/thinking blocks
toolcall_start / toolcall_delta / toolcall_end	Tool use blocks
done	Stream completed successfully
error	Stream ended with an error

API

createCliPipeProvider(options)

Factory that returns a provider object with register(), createModel(), stream(), and streamSimple().

const pipe = createCliPipeProvider({
  command: string;               // CLI binary to spawn
  bridgeEntryPoint: string;      // absolute path to compiled bridge script
  mcpServerName: string;         // used for --allowedTools glob
  bridgeArgs?: string[];         // default CLI args passed to bridge script
  resolveBridgeArgs?: (model) => string[];  // dynamic args from model metadata
});

Args are merged in order: resolveBridgeArgs(model) + provider bridgeArgs + per-stream bridgeArgs.

serveMcpBridge(tools, options?)

Start an MCP stdio server that exposes the given AgentTool[] array. Called from your bridge entry script.

await serveMcpBridge(tools, {
  serverName: "my-app",       // default: "cli-pipe-provider"
  serverVersion: "1.0.0",     // default: "0.1.0"
});

checkCliAvailable(command)

Check whether the CLI binary is installed and accessible.

import { checkCliAvailable } from "cli-pipe-provider";

const { available, version, error } = await checkCliAvailable("claude");
if (!available) {
  console.error("CLI not found:", error);
}

typeboxToJsonSchema(schema)

Utility to convert a TypeBox schema to a clean JSON Schema object (strips TypeBox-internal symbols). Used internally by serveMcpBridge but exported for convenience.

How it works

1. Registers a custom cli-pipe provider with pi-ai
2. On each stream() call, writes a temporary MCP config pointing at your bridge entry script
3. Spawns the CLI in pipe mode with --output-format stream-json --mcp-config <config> --allowedTools "mcp__<name>__*"
4. The CLI spawns your bridge script, discovers tools via MCP, and calls them during its agentic loop
5. Text, thinking, and tool-use events are parsed from stdout and emitted as standard pi-ai AssistantMessageEvents
6. The temporary MCP config is cleaned up when the stream ends

License

MIT