plumb-chat - interactive terminal for plumbing pipelines

SYNOPSIS

plumb-chat [--thinking] [--docroot dir] [--provider name] [--model name] spec.plumb

DESCRIPTION

plumb-chat loads a pipeline specification from spec.plumb, verifies that the main binding has string -> string boundary types, and provides a readline-based interactive CLI.

Each line of user input is JSON-encoded and sent to the pipeline. Output is displayed directly. Agent telemetry (thinking traces, token usage, tool calls) is shown on stderr with per-agent ANSI colours.

Each agent is assigned a colour from a curated palette on first appearance. The palette is ordered for readability — most distinct colours appear first, which matters because pipelines typically have only 2–4 agents. Colours are only emitted when stderr is a terminal.

OPTIONS

--thinking: Show LLM thinking blocks on stderr. Without this flag, thinking traces are suppressed even when agents use extended thinking.
--docroot dir: Set the document root directory for builtin tools.
--provider name: Set the default LLM provider for agents that do not specify one in their config. Sets the PLUMB_PROVIDER environment variable. See plumb-agent(1) for supported providers.
--model name: Set the default model for agents that do not specify one in their config. Sets the PLUMB_MODEL environment variable.
--help: Print usage and exit.

TELEMETRY

When connected to a terminal, chat displays agent telemetry on stderr using ANSI colour codes:

[agent] N in / M out (cache: R read, C create): Token usage summary after each API call.
[agent thinking] text: Reasoning traces (only with --thinking).
[agent] tool_name args -> summary: Tool invocations and their results.
[agent] output: Intermediate agent output in multi-agent pipelines.

ENVIRONMENT

PLUMB_PATH: Colon-separated list of directories for bare use resolution. See plumb(1).
PLUMB_RESOURCES: Colon-separated list of directories for bare prompt file resolution. See plumbing(5).
PLUMB_PROVIDER: Default LLM provider for agents without an explicit provider in config. Overridden by the --provider flag. See plumb-agent(1).
PLUMB_MODEL: Default model for agents without an explicit model in config. Overridden by the --model flag. See plumb-agent(1).
ANTHROPIC_API_KEY, OPENAI_API_KEY: API keys for LLM providers. See plumb(1).
PIPELINE_DEBUG: Set to 1 for debug logging. See plumb(1).

EXIT STATUS

0: Normal exit (EOF or Ctrl-D).
1: Runtime error or subprocess terminated unexpectedly.
2: Configuration error.

EXAMPLES

Start an interactive session with a writer pipeline:

plumb-chat examples/writer/writer.plumb

Enable thinking traces:

plumb-chat --thinking my-pipeline.plumb