Coding Agent API

Slack surface

Mention the agent in any channel or thread. A GitHub link gives it instant repository context; the thread becomes a resumable session.

Mode	Command	Behavior
`normal`	`/zen normal`	Direct execution (default)
`clarify`	`/zen clarify`	Asks follow-up questions before starting
`plan`	`/zen plan`	Read-only: inspects and proposes, changes nothing

Headless interface

npx pi -p "<prompt>"               # one-shot; prints the result
npx pi --mode json -p "<prompt>"   # newline-delimited JSON events
npx pi --mode rpc                  # persistent JSON protocol on stdin/stdout

The headless modes are what the Slack backend and the evaluation harness call.

Configuration

Model providers

Open-source models are first-class. Export a provider key and select with /model:

export DEEPSEEK_API_KEY=...     # or GROQ_API_KEY, FIREWORKS..., OPENROUTER_API_KEY, ...
export EXA_API_KEY=...          # optional: enables the exa_search tool

Self-hosted endpoints (vLLM / SGLang / Ollama / LM Studio / llama.cpp):

export ZEN_LOCAL_BASE_URL=http://localhost:8000/v1
export ZEN_LOCAL_MODELS="my-model-id"

Guardrails — `.pi/guardrails.json`

Declarative rules evaluated before every tool call: denied shell patterns and protected write paths. A blocked action never executes.

Observability schema

Per-session JSONL traces at .zen/traces/<sessionId>.jsonl:

Field	Meaning
turn latency	wall time per agent turn
tool latency	per-tool-call duration
token usage	input/output tokens per model call
cost	per-call and cumulative spend
model switches	when and why the active model changed

Full transcripts live in pi’s session files; the JSONL trace is the cost/latency telemetry the evaluation pipelines aggregate across benchmarks.

Extensions API

Zen-specific behavior ships as TypeScript extensions auto-discovered from the repo root — no build step:

Extension	Purpose
`guardrails.ts`	Pre-execution blocking of denied patterns and protected paths
`observability.ts`	JSONL telemetry per session
`modes.ts`	`/zen normal\|clarify\|plan` behavior modes
`zen-models.ts`	Self-hosted model registration from `ZEN_LOCAL_*`
`zen-tools/`	`exa_search` and proprietary data connectors

Get started

Research Agent

Strategy Pipeline

Evaluation Platform

Coding Agent

Platform

Slack surface

Headless interface

Configuration

Model providers

Guardrails — `.pi/guardrails.json`

Observability schema

Extensions API

​Slack surface

​Headless interface

​Configuration

​Model providers

​Guardrails — .pi/guardrails.json

​Observability schema

​Extensions API

Slack surface

Headless interface

Configuration

Model providers

Guardrails — `.pi/guardrails.json`

Observability schema

Extensions API