v0.2.95 Beta Release

PuzldAI

Runtime Core

The terminal-native orchestration framework. Use the CLI or TUI to route tasks, explore codebases, execute file edits, and generate training data.

$
npm install -g puzldai
Requires Node.js 18+ • Works on Mac, Linux, Windows
View on GitHub

How It Works

A local-first orchestration layer for your AI tools.

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

Multiple ways to run your AI agents.

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 for every tool execution.

# Start interactive agent
$puzldai agent -a claude
>fix the bug in src/utils.ts
Reading src/utils.ts...
I found the issue. The null check is missing. May I apply this fix?

Compare Mode

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

$puzldai compare "Explain async/await"
CLAUDE
Async/await is syntactic sugar...
GEMINI
To understand async/await...

Autopilot Mode

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

# AI plans and executes
$puzldai autopilot "Build a REST API" -x
Generated Plan:
1. gemini:plan → Design API structure
2. claude:code → Implement endpoints
3. codex:review → Code review

Pipelines

Chain agents together for complex workflows. Pipe the output of one agent as context for the next. Perfect for research-then-write tasks.

$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 to find the best architectural decision.

  • Correction
    Producer → Reviewer loop
  • Debate
    Multi-round argumentation
  • Consensus
    Voting and synthesis

Core Layers

The infrastructure powering your agents.

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

Security & Auth

PuzldAI acts as a local orchestrator and does not handle your API keys directly. It wraps the official CLI tools you already have installed and authenticated.

  • No credential exposure: Keys stay with official CLIs.
  • Local Execution: Everything runs on your machine.
  • Open Source: Inspect the code at any time.

Configuration

~/.puzldai/config.json

{ "defaultAgent": "auto", "routerModel": "llama3.2", "fallbackAgent": "claude", "confidenceThreshold": 0.6, "logLevel": "info", "adapters": { "claude": { "enabled": true, "path": "claude" }, "gemini": { "enabled": true, "path": "gemini" }, "codex": { "enabled": false, "path": "codex" }, "ollama": { "enabled": true, "model": "llama3.2", "host": "http://localhost:11434" }, "mistral": { "enabled": true, "path": "vibe" } }, "api": { "port": 3000, "host": "0.0.0.0" }, "ttyd": { "port": 3001, "enabled": true } }