PatchCat

Precision prompts. Deterministic workflows.

The open-source, deterministic AI workflow orchestration engine & DAG state machine built for next-generation AI builders.

English | 简体中文 | 📖 Quick Start Guide | ⚙️ Configuration

PatchCat is an open-source, deterministic AI workflow orchestration engine and visual DAG state machine created by GuoBug. Designed for AI engineers, product engineers, and developers building robust agentic pipelines, PatchCat transforms complex multi-agent interactions, LLMs, code transforms, and conditional branches into visual, parallelized, and deterministic workflows.

With zero mandatory backend setup (Client-Only BYOK Mode) and direct connectivity to Google Gemini, DeepSeek, OpenAI, SiliconFlow, and local Ollama, PatchCat delivers high-performance AI workflow orchestration and prompt engineering directly inside your browser with enterprise-grade telemetry and zero data leakage.

Watch the full end-to-end demo: from client-side API key configuration, drag-and-drop canvas building, real-time topological execution, to interactive chat testing and API publishing.

PatchCat Visual DAG Canvas — Drag-and-drop workflow builder with real-time LLM token streaming

Why choose PatchCat over heavyweight orchestration tools?

• Built-in ReAct Loop: Enclosed Think -> Act -> Observe -> Think cycle with cycle prevention and maxIterations safeguards.
• Universal Tool Calling Client: Full support for OpenAI, Gemini, and DeepSeek standard tool schemas with streaming delta.tool_calls assembly.
• Multi-Type Tool Dispatcher: Route to sandboxed JavaScript (builtin_code), external REST endpoints (builtin_http), or delegate to canvas nodes (canvas_node).
• Loop & Sub-Workflow Primitives: Dynamic array batch iterator (LoopNode) and composite workflow encapsulation (SubWorkflowNode).

• Deterministic DAG Scheduling: Powered by Kahn's topological sort algorithm, executing parallel execution waves while eliminating race conditions and cyclic deadlocks.
• Drag-and-Drop Workflow Canvas: Built on @xyflow/react (React Flow v12) with 12 specialized node components (Input, Prompt, LLM, Agent, Loop, Sub-Workflow, Code, Output, Knowledge, Condition, Aggregator, HTTP).
• Dynamic Conditional Routing & Skipping: IF/ELSE multi-branch evaluation with dynamic downstream skipping (NODE_SKIPPED) and variable aggregation.
• Interactive Chat Debug & API Publishing: Slide-over Chat drawer (Ctrl+Shift+D) and instant FastAPI REST endpoint generation with API Key auth.

• Direct Cloud & Local LLM Connectivity:
  • 🔵 Google Gemini: Full support for gemini-2.5-flash, gemini-2.5-pro, gemini-2.0-flash, with dynamic model discovery.
  • 🐳 DeepSeek: Seamless integration with DeepSeek-R1 (with live reasoning/thought streaming) and DeepSeek-V3.
  • 🟢 OpenAI: Native support for GPT-4o, GPT-4o-mini, and custom models.
  • ⚡ SiliconFlow: High-speed hosted open-source models.
  • 🦙 Ollama & Local Models: Direct connection to local LLM instances (Llama 3, Qwen 2.5, Mistral).
  • 🛠️ Custom OpenAI-Compatible Endpoints: Connect to any proxy, OneAPI, or self-hosted vLLM instance.
• Cross-Vendor Model Auto-Remapping: Intelligently adapts preset templates to your currently selected provider without broken requests.
• Transient 503 Auto-Retry & Diagnostics: Built-in exponential backoff for high-concurrency spikes and actionable Chinese/English error diagnostics.

• Live Token Streaming: Token-by-token real-time canvas rendering with fluid animations.
• Dual-Stream Reasoning Inspection: Dedicated visualization panel for DeepSeek R1 and Gemini thinking chains.
• Precise Token & Latency Telemetry: Accurate per-node execution duration and token usage calculation.

• In-Browser Safe Execution: Execute custom JavaScript scripts directly in browser sandbox with inputs and console.log capture.
• Automatic JSON Markdown Stripping: Effortlessly parse structured outputs from LLMs wrapped in ```json blocks.
• Smart Decision Routing: Conditionally dispatch workflows based on intent, urgency, and confidence scores.

• Configurable 3-Level Logging:
  • Summary (概要): System lifecycle (START, COMPLETE, ERROR), HTTP status codes, latency, and failure traces.
  • Detailed (详细): Node IDs, runtime parameters (model, temperature, max_tokens), and DAG layer wave timing.
  • Dev (开发): Full prompt inputs, intermediate outputs, and LLM responses.
• Zero-Exposure Security Sanitization (sanitizeData):
  • Automatic recursive masking of all API Keys (sk-***, AIzaSy***), Bearer tokens, and password fields across all log levels.
• Collapsible Visual Console Drawer: Built-in IDE-style terminal drawer with search, type filters, JSON payload inspector, and one-click JSON/TXT export.

• Mustache-Style Syntax: Interpolate data with {{nodeId.propertyPath}}.
• Deep Object & Array Navigation: Access nested fields such as {{classifier.result.tags[0].name}}.
• Fallback Defaults: Built-in fallback syntax {{nodeId.output | "default_value"}} to safeguard against missing values.

• IndexedDB Asynchronous Persistence: High-capacity, non-blocking browser client storage overcoming 5MB sessionStorage limits and tab-closure data loss.
• Workflow-Scoped Isolation: Messages are strictly partitioned by ${workflowId}::${sessionId} to prevent cross-canvas contamination during testing.
• Tier-1 Global Policy & 2-Tier Configuration: Configure global defaults in Settings (SettingsPage.tsx) for sliding window rounds (1–20), token budget limit (500–16,000), and pruning strategies (hybrid, window, token_budget).
• Dynamic Context Injection: Automatically prunes historical dialogue and injects formatted multi-turn context into {{chat_history}}, {{conversation_history}}, and {{history}} variable slots.
• Storage Architecture FAQ & Q&A: Embedded interactive card disclosing client-side IndexedDB benefits, self-hosted SQLite (patchcat.db) zero-config persistence, and browser sandbox File System Access API authorization constraints.

• Recent 10 Execution Runs Timeline: Dedicated slide-over drawer (Ctrl+Shift+H or top header) displaying the latest 10 canvas execution records with duration and token consumption.
• Aggregate KPI Overview: Instant glance at total latency, Prompt/Completion token breakdown, and dynamic USD cost estimates across top model providers.
• Execution Waterfall Timeline: Visual horizontal Gantt/bar chart displaying relative start offsets and proportional execution durations per node.
• Step Data Freeze-Frame Inspector: Modal inspector to review exact inputs, outputs, error traces, and telemetry metadata captured for any historical step.
• OpenTelemetry & OpenInference Alignment: Pure-frontend W3C Trace Context generation (128-bit Trace ID, 64-bit Span ID) with hierarchical Root -> Wave -> Node spans and Time-to-First-Token (TTFT) recording.
• One-Click OTel JSON Export: Losslessly export or copy standard OTel ResourceSpans JSON ready for Langfuse, Datadog, Jaeger, or any APM platform.
• Client-Side FIFO Eviction: Enforces an automatic 10-record ring buffer per workflow in IndexedDB, preventing local storage growth while maintaining local-first privacy.

• Node.js >= 18.0.0
• npm >= 9.0.0

# Clone the repository
git clone https://github.com/GuoBug/PatchCat.git
cd PatchCat

# Install dependencies
npm install

npm run dev

Open your browser and navigate to http://localhost:5173.

1. Click the API Key button in the top navigation bar.
2. Select your preferred provider (Google Gemini, DeepSeek, OpenAI, SiliconFlow, or Ollama).
3. Enter your API Key and click 测试连通性 (Test Connection) to fetch available models.
4. Click ▶ Run Workflow to execute the pipeline!

PatchCat maintains rigorous code quality with 100% test coverage across core scheduling, variable resolution, and logging engines:

# Run all unit tests (Topological Sort, Engine, LLM Client, Logger, Routing)
npm test

# Run TypeScript type check
npm run typecheck

# Build for production
npm run build

# Preview production build locally
npm run preview

PatchCat comes with ready-to-use industrial presets:

• Visual DAG Canvas with Kahn's Algorithm & Parallel Wave Execution
• Multi-Provider Hub (Google Gemini, DeepSeek, OpenAI, SiliconFlow, Ollama)
• DeepSeek R1 Thought/Reasoning Stream Visualization
• Dynamic JavaScript Code Node & Real-Time Transformation Sandbox
• 3-Tier Enterprise Logging Console & Secret Sanitization
• Template Import & Export (JSON Schema Draft-07)
• RAG & Vector Knowledge Base Node Integration (Zero-setup SQLite / PGVector)
• Multi-Agent Autonomous Tool Calling Loop (ReAct Agent)
• One-Click Workflow Export as Standalone REST API Endpoint
• Local Python Server Backend (FastAPI + Async Engine + Alembic Migrations)
• Asuswrt-Merlin Router Plugin & Lightweight Go Gateway (v0.4.7)
• Run Observability, Step Snapshot Inspection & OpenTelemetry Tracing (v0.4.8)
• Immutable Checkpointing & Resumable Execution Subgraph (v0.4.10)
• Local Lightweight Hybrid Search (BM25 + Vectors) (v0.4.12)
• Reranker Cross-Encoder API Integration (v0.4.14)

PatchCat is created and actively maintained by GuoBug (Guo Qiang) — a Product Engineer combining platform engineering rigor (DAG state machines, deterministic orchestration, developer tooling) with product-led growth and user experience empathy.

Engineered through an AI pair programming workflow with rigorous verification and open-source milestones. Inquiries, architectural discussions, and contributions are warmly welcome!

We welcome contributions from the global open-source community!

• 🐛 Found a bug? Submit an Issue
• 💡 Have a feature idea? Start a Discussion
• 🚀 Want to contribute code? Read the Contributing Guide (中文版)
• 🛡️ Found a security vulnerability? See our Security Policy
• 📜 Community standards: Code of Conduct

Distributed under the MIT License. Free for commercial and personal use.