Puzld.ai

Name: Puzld.ai
Author: MedChaouch

by MedChaouch

Warning

Multi-LLM orchestration framework

273stars

25forks

TypeScript

Added 12/27/2025

Installation

# Add to your Claude Code skills
git clone https://github.com/MedChaouch/Puzld.ai

Getting Started

Guides for using ai agents skills like Puzld.ai.

Caveman: Cut Claude Token Use by 65%
How agent-side prompt compression works, when to use it, and when not to.
What is an AI Skills Marketplace?
Definitions, how marketplaces work, and how to choose between them in 2026.
Getting Started with AI Skills

Security ReportWarning

Last scanned: 5/30/2026

{
  "issues": [
    {
      "type": "npm-audit",
      "message": "@fastify/static: @fastify/static vulnerable to path traversal in directory listing",
      "severity": "medium"
    },
    {
      "type": "npm-audit",
      "message": "@isaacs/brace-expansion: @isaacs/brace-expansion has Uncontrolled Resource Consumption",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "ajv: ajv has ReDoS when using `$data` option",
      "severity": "medium"
    },
    {
      "type": "npm-audit",
      "message": "diff: jsdiff has a Denial of Service vulnerability in parsePatch and applyPatch",
      "severity": "low"
    },
    {
      "type": "npm-audit",
      "message": "fast-uri: fast-uri vulnerable to path traversal via percent-encoded dot segments",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "fastify: Fastify Vulnerable to DoS via Unbounded Memory Allocation in sendWebStream",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "minimatch: minimatch has a ReDoS via repeated wildcards with non-matching literal in pattern",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "ws: ws: Uninitialized memory disclosure",
      "severity": "medium"
    }
  ],
  "status": "WARNING",
  "scannedAt": "2026-05-30T15:12:44.414Z",
  "npmAuditRan": true,
  "pipAuditRan": true
}

README.md

Frequently Asked Questions

What is Puzld.ai?

Puzld.ai is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by MedChaouch. Multi-LLM orchestration framework. It has 273 GitHub stars.

Is Puzld.ai safe to use?

Puzld.ai returned warnings in SkillsLLM's automated security scan. It has no critical vulnerabilities, but review the flagged issues in the Security Report section before adding it to your workflow.

How do I install Puzld.ai?

Clone the repository with "git clone https://github.com/MedChaouch/Puzld.ai" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is Puzld.ai written in?

Puzld.ai is primarily written in TypeScript. It is open-source under MedChaouch on GitHub, so you can review or fork the full source.

Are there alternatives to Puzld.ai?

Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh Puzld.ai against similar tools.

Agentic AI for Beginners

Build your first AI agent from scratch - tool use, ReAct pattern, memory, deployment

41 minBeginner

Comments (0)

to leave a comment.

No comments yet. Be the first to share your thoughts!

Related Skills

superpowers

by obra

An agentic skills framework & software development methodology that works.

234,966

Cognitive-Core-Skills swarmzero

Beyond CLI wrappers. PuzldAI is a complete AI orchestration framework — route tasks, explore codebases, execute file edits, build memory, and generate training data.

PuzldAI is a terminal-native framework for orchestrating multiple AI agents. Route tasks to the best agent, compare responses, chain agents in pipelines, or let them collaborate. Agentic Mode gives LLMs tools to explore your codebase (view, glob, grep, bash) and propose file edits with permission prompts — like Claude Code, but for any LLM. Memory/RAG stores decisions and code for future context. Observation Layer logs everything for DPO fine-tuning. One framework that grows with your AI workflow.

Why PuzldAI?

Problem	Solution
Claude is great at code, Gemini at research	Auto-routing picks the best agent
Need specific model versions	Model selection — pick sonnet, opus, haiku, etc.
Want multiple opinions	Compare mode runs all agents in parallel
Complex tasks need multiple steps	Pipelines chain agents together
Repetitive workflows	Workflows save and reuse pipelines
Need agents to review each other	Collaboration — correct, debate, consensus
Want LLM to explore & edit files safely	Agentic mode — tools, permission prompts, apply
Context gets lost between sessions	Memory/RAG — semantic retrieval of past decisions
Need data to fine-tune models	Observations — export DPO training pairs
Need AI to understand your codebase	Indexing — AST parsing, semantic search, AGENTS.md

Features

Auto-routing — Ask anything. The right agent answers.
Model Selection — Pick specific models per agent (sonnet, opus, haiku, etc.)
Compare — Same question, multiple agents, side-by-side.
Pipelines — Chain agents on-the-fly: gemini:analyze → claude:code (CLI)
Workflows — Save pipelines as templates, run anywhere (TUI & CLI)
Autopilot — Describe the goal. AI builds the plan.
Multi-Agent Collaboration — Correct, debate, and build consensus across agents.
Agentic Mode — LLMs explore your codebase, propose edits, you approve with permission prompts.
Codebase Indexing — AST parsing, semantic search, AGENTS.md support.
Memory/RAG — Semantic retrieval injects relevant context into prompts.
Observation Layer — Logs all interactions for training data generation.
Sessions — Persist chat history, resume conversations.
TUI — Full terminal UI with autocomplete, history, keyboard nav.

Supported Agents

Agent	Source	Requirement	Agentic Mode
Claude	Anthropic	Claude CLI	✅ Full support
Gemini	Google	Gemini CLI	⚠️ Auto-reads files
Codex	OpenAI	Codex CLI	⚠️ Auto-reads files
Ollama	Local	Ollama running	✅ Full support
Mistral	Mistral AI	Vibe CLI	⚠️ Inconsistent

Note: Some CLIs (Gemini, Codex) have built-in file reading that bypasses permission prompts. Claude and Ollama respect the permission system fully.

Install

npm install -g puzldai

Or try without installing:

npx puzldai

Update:

npm update -g puzldai

Quick Start

# Interactive TUI
puzldai

# Single task
puzldai run "explain recursion"

# Compare agents
puzldai compare claude,gemini "best error handling practices"

# Pipeline: analyze → code → review
puzldai run "build a logger" -P "gemini:analyze,claude:code,gemini:review"

# Multi-agent collaboration
puzldai correct "write a sort function" --producer claude --reviewer gemini
puzldai debate "microservices vs monolith" -a claude,gemini
puzldai consensus "best database choice" -a claude,gemini,ollama

# Check what's available
puzldai check

puzld also works as a shorter alias.

Interface

Execution Modes

Mode	Pattern	Use Case	Category
Single	One agent processes task	Quick questions, simple tasks	Basic
Compare	Same task → multiple agents in parallel	See different perspectives	Parallel
Pipeline	Agent A → Agent B → Agent C	Multi-step processing	Sequencing
Workflow	Saved pipeline, reusable	Repeatable workflows	Sequencing
Autopilot	LLM generates plan → executes	Complex tasks, unknown steps	AI Planning
Correct	Producer → Reviewer → Fix	Quality assurance, code review	Collaboration
Debate	Agents argue in rounds, optional moderator	Find flaws in reasoning	Collaboration
Consensus	Propose → Vote → Synthesize	High-confidence answers	Collaboration
Agentic	LLM explores → Tools → Permission prompts → Apply	Codebase exploration + file edits	Execution
Plan	LLM analyzes task → Describes approach	Planning before implementation	Execution
Build	LLM explores + edits with full tool access	Direct implementation with tools	Execution

Mode Options

Mode	Option	Type	Default	Description
Single	`agent`	AgentName	`auto`	Which agent to use
	`model`	string	—	Override model (e.g., sonnet, opus)
Compare	`agents`	AgentName[]	—	Agents to compare (min 2)
	`sequential`	boolean	`false`	Run one-at-a-time vs parallel
	`pick`	boolean	`false`	LLM selects best response
Pipeline	`steps`	PipelineStep[]	—	Sequence of agent:action
	`interactive`	boolean	`false`	Confirm between steps
Workflow	`name`	string	—	Workflow to load
	`interactive`	boolean	`false`	Confirm between steps
Autopilot	`planner`	AgentName	`ollama`	Agent that generates plan
	`execute`	boolean	`false`	Auto-run generated plan
Correct	`producer`	AgentName	`auto`	Agent that creates output
	`reviewer`	AgentName	`auto`	Agent that critiques
	`fixAfterReview`	boolean	`false`	Producer fixes based on review
Debate	`agents`	AgentName[]	—	Debating agents (min 2)
	`rounds`	number	`2`	Number of debate rounds
	`moderator`	AgentName	`none`	Synthesizes final conclusion
Consensus	`agents`	AgentName[]	—	Participating agents (min 2)
	`maxRounds`	number	`2`	Voting rounds
	`synthesizer`	AgentName	`auto`	Creates final output
Agentic	`agent`	AgentName	`claude`	Agent to use for exploration
	`tools`	string[]	all	Available tools (view, glob, grep, bash, write, edit)
Plan	`agent`	AgentName	`claude`	Agent to analyze task
Build	`agent`	AgentName	`claude`	Agent to implement

Model Selection

Pick specific models for each agent. Aliases like sonnet, opus, haiku always point to the latest version. Specific versions like claude-sonnet-4-20250514 are pinned.

# TUI
/model                            # Open model selection panel

# CLI
puzldai model show                # Show current models for all agents
puzldai model list                # List all available models
puzldai model list claude         # List models for specific agent
puzldai model set claude opus     # Set model for an agent
puzldai model clear claude        # Reset to CLI default

# Per-task override
puzldai run "task" -m opus        # Override model for this run
puzldai agent -a claude -m haiku  # Interactive mode with specific model

Compare Mode

Run the same prompt on multiple agents and compare results side-by-side.

Three views: side-by-side, expanded, or stacked.

# TUI
/compare claude,gemini "explain async/await"
/sequential                    # Toggle: run one-at-a-time
/pick                          # Toggle: select best response

# CLI
puzldai compare "task"                          # Default: claude,gemini
puzldai compare "task" -a claude,gemini,codex   # Specify agents
puzldai compare "task" -s                       # Sequential mode
puzldai compare "task" -p                       # Pick best response