https://github.com/stefanwebb/named-pipes
Low-latency IPC library for building persistent agentic tool servers (LLM inference, TTS, vector search, browser automation) over named pipes on the same machine.
https://github.com/stefanwebb/named-pipes
agent-skills agents claude-code cli-tool mcp named-pipes
Last synced: 2 months ago
JSON representation
Low-latency IPC library for building persistent agentic tool servers (LLM inference, TTS, vector search, browser automation) over named pipes on the same machine.
- Host: GitHub
- URL: https://github.com/stefanwebb/named-pipes
- Owner: stefanwebb
- License: cc-by-sa-4.0
- Created: 2026-03-15T20:01:15.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-13T01:55:07.000Z (2 months ago)
- Last Synced: 2026-04-13T03:28:46.499Z (2 months ago)
- Topics: agent-skills, agents, claude-code, cli-tool, mcp, named-pipes
- Language: Python
- Homepage:
- Size: 1.03 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
Named Pipes as Agentic Tools
Low-latency IPC for persistent AI tool servers — LLM inference, TTS, STT, vector search, and more — all on one machine, no network stack required.
---
## ✨ Highlights
- **Persistent servers** — model weights and state stay loaded between calls; no per-request startup cost
- **Kernel-speed IPC** — named pipes route through kernel memory, not a network stack; lower latency than local HTTP
- **Multi-client fanout** — one server handles many concurrent clients; each gets its own downstream pipe
- **Decorator API** — register command handlers with a single `@ch.handler("CMD")` line
- **`cpipe` CLI** — send ad-hoc commands to any running server from the terminal, like `curl` for pipes
- **Claude Code skill** — an included skill teaches the assistant to discover and query live servers without leaving the session
- **Ready-made servers** — drop-in pipes for LLM chat, text-to-speech, and speech-to-text
## Overview
This library uses named pipes as the transport layer for **agentic tool servers** — persistent background processes that expose capabilities such as LLM inference, text-to-speech, vector search, or browser automation to a Python orchestrator running on the same machine.
Because named pipes route data through kernel memory rather than a network stack, they offer lower latency than local HTTP and far less complexity than shared memory — a practical sweet spot for real-time applications like voice agents.
The same servers can be driven directly from Claude Code. An included agent skill teaches the assistant how to discover running pipe servers with `cpipe --list`, inspect their capabilities, and send commands.
For a deeper look at the design decisions and API reference, see [DOCS.md](DOCS.md).
## Installation
```bash
# Core library only
pip install -e .
# With LLM inference support
pip install -e ".[llm]"
# With TTS support (macOS: mlx-audio + sounddevice)
pip install -e ".[tts]"
# With STT support (sounddevice; Voxtral weights vendored)
pip install -e ".[stt]"
```
Requires **Python 3.11+**. See [DOCS.md](DOCS.md) for platform-specific dependency details.
## Quick start
**1. Start a server** (Terminal 1):
```bash
conda activate named-pipes
python src/ex_chat_pipe/server.py # LLM server on /tmp/tool-chat
```
**2. Query it from the CLI** (Terminal 2):
```bash
cpipe /tmp/tool-chat chat --data '{"messages": [{"role":"user","content":"Hello!"}]}'
```
**3. Or write a client in Python:**
```python
from named_pipes.tool_named_pipe import ToolNamedPipe, Role
with ToolNamedPipe("tool-chat", role=Role.CLIENT) as ch:
ch.send_message("chat", '{"messages": [{"role":"user","content":"Hello!"}]}')
for msg in ch.receive_stream():
print(msg)
```
## Examples
Start order matters — **server first**, then client (server creates the FIFOs).
```bash
# LLM chat
python src/ex_chat_pipe/server.py # Terminal 1
python src/ex_chat_pipe/client.py # Terminal 2
# LLM → TTS pipeline (spoken output)
python src/ex_chat_pipe/server.py # Terminal 1: LLM (/tmp/tool-chat)
python src/ex_tts_pipe/server.py # Terminal 2: TTS (/tmp/tool-tts)
python src/ex_tts_pipe/client.py # Terminal 3: pipeline client
# Speech-to-text
python src/ex_stt_pipe/server.py # Terminal 1: STT (/tmp/tool-stt)
python src/ex_stt_pipe/client.py # Terminal 2: subscriber
# Basic channel (no-frills text + binary)
python src/ex_basic_pipe/server.py # Terminal 1
python src/ex_basic_pipe/client.py # Terminal 2
```
## `cpipe` — CLI tool
```bash
cpipe /tmp/tool-chat chat --data '{"messages": [{"role":"user","content":"Hello"}]}'
cpipe --list # discover running pipe servers
cpipe --pid # same, plus PIDs that have each pipe open
cpipe --clear # delete orphaned pipes
```
See [DOCS.md](DOCS.md) for all options and the full protocol reference.
## Claude Code skill
An included skill at [`.claude/skills/named-pipe-tools/SKILL.md`](.claude/skills/named-pipe-tools/SKILL.md) teaches Claude Code how to use `cpipe` to discover, inspect, and interact with live servers — so the LLM can query a local inference server or trigger TTS playback without leaving the coding session.
## Resources
- [DOCS.md](DOCS.md) — architecture, API reference, protocol spec, and design rationale
- [`named-pipe-tools.md`](named-pipe-tools.md) — `ToolNamedPipe` protocol specification
- [`src/ex_chat_pipe/`](src/ex_chat_pipe/) — LLM chat example
- [`src/ex_tts_pipe/`](src/ex_tts_pipe/) — TTS example
- [`src/ex_stt_pipe/`](src/ex_stt_pipe/) — STT example
- [`src/ex_basic_pipe/`](src/ex_basic_pipe/) — basic channel example