Documentation

Guides in reading order, the installation routes, and the reference pages. Start at the top if PtcRunner is new to you.

Start

  • Quickstart Install ptc, verify it without an API key, then run a model-authored program without writing PTC-Lisp yourself.
  • Understand a generated project Understand the files, result, and trace created by ptc init without writing an agent loop.
  • PtcRunner concepts Use this page as a quick lookup for the names that appear in PtcRunner files, commands, and results. You can run the Quickstart without reading it first.
  • Drive ptc as an agent Use the executable's own help and embedded documentation when a coding agent drives ptc.

Language

  • Read and write PTC-Lisp Read what a model wrote in a trace, or try the language by hand before building anything.

Configure

  • Keep a runnable project together Use ptc-project.json as one stable command target for local runs, traces, results, and the Viewer.
  • Configure an application Use ptc.json to declare code, input, selected providers, missions, and limits.
  • Install models and tools The ptc-host.json installs credentials, model routes, MCP tools, and limits. An application selects and narrows aliases without changing host configuration.

Build

  • Use a model Select, verify, and observe a model without working on PtcRunner's provider implementation.
  • Connect an MCP tool Connect one MCP server while exposing only the tools a mission needs.
  • Customize an agent Configure the shipped agent loop or replace its prompt, policy, mission composition, or complete implementation.
  • Customize agent components Try a changed prompt or agent loop without changing ptc.json. If you keep the change, give your permanent components new IDs.

Design

  • Design an agent workflow Design a small support-inbox agent in three runnable steps: provide the data, move the rules into code, then split the work between specialists.
  • Choose a workflow shape Choose how to split a task between missions, agent loops, and trusted workflow code. The shapes compose — a real design usually combines two or three.

Run and debug

  • Run and inspect a project Run, validate, and inspect a PtcRunner project through the ptc executable.
  • Explore a project interactively Inspect a workflow, mission, or immutable run capture from an interactive or unattended REPL session.
  • Debug a failed run Follow a failed run from its immutable trace into private inspection only when the trace cannot answer the question.
  • Evaluate changes with replay Compare an agent prompt or prelude change against fixed model responses before deciding whether to promote it.

Installation

  • Standalone installation Install the self-contained ptc executable from GitHub Releases.
  • Docker installation Install the self-contained Linux AMD64 or ARM64 image and run the PtcRunner CLI, Viewer, and stdio launcher without a build toolchain.
  • Source installation Build PtcRunner from a repository checkout when changing the runtime, validating an unreleased revision, or producing a standalone artifact.

Reference

  • PTC-Lisp Language Specification PTC-Lisp is a bounded Clojure-like language for data processing and tool calling through explicitly granted capabilities.
  • Agent library reference This reference defines the shipped agent.core and agent.main PTC-Lisp interfaces. For a guided workflow, see Building agents.
  • Clojure Conformance Gaps Tracked differences between PTC-Lisp and Clojure semantics, discovered via conformance testing against SCI, Babashka, Joker, and manual investigation.
  • Java Interop Reference for PTC-Lisp PTC-Lisp emulates a subset of Java interop for LLM compatibility. These are not real JVM calls — they are BEAM-native implementations that mirror the Java API …
  • Kernel limits reference Ordinary limits are positive enforced ceilings. Optional limits are disabled when omitted by the host. Two documents decide an enabled number: the host documen…
  • Shipped prelude reference PtcRunner ships 17 reusable PTC-Lisp components with 60 public exports. A component is one named source module with one namespace. A prelude is the immutable c…
  • Signature reference Use signatures to describe component and model-visible tool inputs and outputs, then validate both sides of each call.
  • Application-manifest reference This is the complete contract for ptc.json.
  • Host-configuration reference This is the complete contract for installed providers, credentials, transports, data classes, and outer limits.
  • Project-configuration reference This is the complete local path, artifact, override, and Viewer-preference contract.
  • Components-and-preludes reference This is the complete component, dependency, visibility, and shipped-library contract.
  • MCP reference This is the complete MCP installation, mapping, effect, authentication, and lifecycle contract.
  • Command-line reference This is the complete ptc command and process contract.
  • REPL reference This is the complete interactive, unattended, analysis-profile, and private-session contract.
  • Debug-navigation reference This is the complete frozen-evidence graph and debug.nav contract.