Complete Documentation

How Puzld Works

A complete agentic runtime: The Core Runtime, The Universal Bridge, and The Cloud API.

$

The Core Runtime

At the heart of Puzld is a powerful, locally executed agent orchestration engine. It runs directly on your machine, giving you full control over permissions, tools, and data.

Architecture

User Input
PuzldAI CLI / TUI
Orchestrator
↔
Router
Ollama / Any Agent / Auto
Executor
Plans & Pipelines
Adapters
claude
gemini
codex
ollama
mistral
→
Agent CLIs
  • Claude Code
  • Gemini CLI
  • Codex
  • Ollama Models
  • Mistral (Vibe)
↕
Memory
Sessions + RAG
↕
Indexing
AST + Search
↓
Observation
Training Data

Execution Modes

Single Mode

The simplest way to interact. Send a prompt to any agent and get a response. Auto-routing selects the best agent for your task.

# Direct agent call
$puzldai run "Explain closures in JS" -a claude
$puzldai run "Explain closures in JS"# auto-routes

Agentic Mode

Give LLMs safe access to your filesystem. Agents can explore directory structures, read files, and propose edits. You maintain full control with permission prompts.

# Start interactive agent
$puzldai agent -a claude
>fix the bug in src/utils.ts

Compare Mode

Run the same prompt across multiple models simultaneously. Compare reasoning, code quality, and speed side-by-side.

$puzldai compare "Explain async/await"

Autopilot Mode

Describe the goal, AI builds the plan. The planner agent analyzes your task and generates a multi-step execution plan.

# AI plans and executes
$puzldai autopilot "Build a REST API" -x

Pipelines

Chain agents together for complex workflows. Pipe the output of one agent as context for the next.

$puzldai run "Build API" -P "gemini:plan,claude:code"

Collaboration

Orchestrate multi-agent interactions. Have one agent review another's code, or setup a debate.

  • Correction
    Producer → Reviewer
  • Debate
    Multi-round
  • Consensus
    Voting

Core Layers

System Internals
01

Memory & RAG

Persistent session history and retrieval-augmented generation. Context flows seamlessly between execution sessions.

  • → SQLite Storage
  • → Vector Embeddings
  • → Context Injection
02

Indexing Engine

Parse your codebase into searchable semantic structures. Search across functions, classes, and dependencies.

  • → AST Parsing
  • → Dependency Graphs
  • → Semantic Search
03

Observation

Capture every interaction for training data. Export preference pairs and trajectories for model fine-tuning.

  • → Interaction Logging
  • → Diff Tracking
  • → JSONL Export
04

Agentic Tools

Safe system access with permission gates. Give agents the tools they need to read, write, and execute.

  • → File System (Glob, Grep)
  • → Bash Execution
  • → Permission System
05

Context Manager

Intelligent context window handling. Summarize history and translate context between different models.

  • → Token Counting
  • → Summarization
  • → Multi-Model Translation
06

MCP Bridge

Full support for the Model Context Protocol. Expose Puzld agents as MCP servers to other tools.

  • → MCP Server Support
  • → Tool Exposure
  • → Universal Protocol
M

The Universal Bridge

Puzld implements the Model Context Protocol (MCP), connecting your local machine to the cloud. Run agents remotely while they execute locally on your hardware with full tool access.

How It Works

MCP Client
Claude, Cursor, etc.
Puzld Cloud
Hosted Service
WebSocket
PUZLD MCP
Your Machine
Agent CLIs
  • Claude Code
  • Gemini CLI
  • Codex
  • Ollama Models

Capabilities

Protocol Server

Expose all your local Puzld agents (Claude, Gemini, Codex, Ollama) as MCP tools. Any MCP client can execute tasks through the full orchestration layer.

# Start the MCP bridge
$puzldai serve --mcp
✔ Connected to MCP cloud via WebSocket

Connect Everything

Execute tasks remotely through the Puzld Cloud. Your local agents stay on your machine while MCP clients connect via secure WebSocket.

  • Single & Compare Modes
  • Agentic File Access
  • Secure Cloud Tunnel

Setup Guide

01

Get API Key

Create one in your dashboard.

02

Add Config

Copy the configuration for your client below.

03

Restart

Changes apply after restarting your client.

Terminal
claude mcp add --transport http puzld https://api.puzld.cc/protocol \
  --header "X-PUZLD-API-KEY: YOUR_API_KEY"
{}

Programmatic Intelligence

Embed Puzld's agentic capabilities directly into your applications. Trigger complex multi-step workflows via REST API and receive structured results.

Code Examples

curl -X POST https://api.puzld.cc/mcp/execute \
  -H "X-PUZLD-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "run",
    "prompt": "Hello world",
    "agent": "claude"
  }'

Endpoint Reference

POST/mcp/execute

Execute an agent with a given prompt and configuration.

Request Body

{
  "action": "run",
  "prompt": "Your prompt here",
  "agent": "claude"
}

Response

{
  "success": true,
  "result": "Agent response...",
  "usage": { "tokens": 150 }
}

Required Headers

X-PUZLD-API-KEY: your_api_keyContent-Type: application/json