Puzld MCP

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 Modegives 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/RAGstores decisions and code for future context.Observation Layerlogs everything for DPO fine-tuning. One framework that grows with your AI workflow.

- 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.

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

# 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

Pick specific models for each agent. Aliases likesonnet,opus,haikualways point to the latest version. Specific versions likeclaude-sonnet-4-20250514are 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

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

Three views:side-by-side,expanded, orstacked.

# 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

Chain multiple agents together for complex tasks. Each agent handles a specific step.

puzldai run "build a REST API" -P "gemini:analyze,claude:code,gemini:review" puzldai run "task" -P "claude:plan,codex:code" -i # Interactive: pause between steps

Save pipelines as reusable templates. Run them anywhere with a single command.

Three views:side-by-side,expanded, orstacked.

# TUI /workflow code-review "my code here" /workflows # Manage templates (interactive) /interactive # Toggle: pause between steps # CLI puzldai run "task" -T code-review puzldai run "task" -T code-review -i # Interactive mode puzldai template list # List all templates puzldai template show my-flow # Show template details puzldai template create my-flow -P "claude:plan,codex:code" puzldai template delete my-flow # Delete template

Describe the goal. AI analyzes the task, builds a multi-step plan, and executes it automatically using the best agents for each step.

With/executeenabled, results display in3 view modes: side-by-side, expanded, or stacked.

# TUI /autopilot "build a todo app with authentication" /planner claude # Set planner agent /execute # Toggle auto-execution on/off # CLI puzldai autopilot "task" # Generate plan only puzldai autopilot "task" -x # Generate and execute puzldai autopilot "task" -p claude # Use specific agent as planner

Get multiple agents to work together through correction, debate, or consensus.

One agent produces, another reviews. Optionally fix based on feedback.

# TUI /correct claude gemini "write a sorting algorithm" # CLI puzldai correct "task" --producer claude --reviewer gemini puzldai correct "task" --producer claude --reviewer gemini --fix

Agents debate a topic across multiple rounds. Optional moderator summarizes.

# TUI /debate claude,gemini "Is functional programming better than OOP?" # CLI puzldai debate "topic" -a claude,gemini puzldai debate "topic" -a claude,gemini -r 3 -m ollama # 3 rounds + moderator

Agents propose solutions, vote on them, and synthesize a final answer.

# TUI /consensus claude,gemini,ollama "best database for this use case" # CLI puzldai consensus "task" -a claude,gemini,ollama puzldai consensus "task" -a claude,gemini -r 3 -s claude # 3 rounds + synthesizer

All collaboration modes support3 view modes: side-by-side, expanded, and stacked.

Configure rounds, moderator, and synthesizer in/settings.

LLMs explore your codebase using tools, then propose file edits with permission prompts (like Claude Code). PuzldAI acts as the execution layer — the LLM explores and proposes, you approve what gets executed.

# TUI - Use @agent syntax to trigger agentic mode @claude fix the bug in src/utils.ts @gemini add error handling to api/routes.ts @ollama create a hello world script # Or use commands /plan @claude refactor the auth system # Plan only (no execution) /build @claude implement the login form # Full implementation with tools

- Allow— Execute this tool call
- Allow from directory— Auto-approve reads from this directory
- Allow all reads— Auto-approve all file reads
- Deny— Skip this tool call
- Esc— Cancel entire operation

- Colored status dots: ● green (done), yellow (running), red (error), gray (pending)
- Tree-style result display with truncation
- Ctrl+Sto expand/collapse full output
- You describe the task with@agent
- LLM explores codebase using tools (view, glob, grep)
- Each tool call shows a permission prompt
- LLM proposes file edits (write, edit)
- You approve or deny each change
- PuzldAI applies approved changes

Consensus → Agentic workflow:Run consensus first, then continue with an agent. The consensus result is automatically injected as context:

/consensus claude,gemini "best approach for auth" # Choose "Continue" @claude implement this # Has consensus context

PuzldAI includes a memory system that stores conversations, decisions, and code patterns for future retrieval.

- conversation— Q&A pairs from sessions
- decision— Accepted file edits and explanations
- code— Code snippets and patterns
- pattern— Reusable solutions

- Observations from/agenticare automatically saved to memory
- When you accept file edits, the decision is stored for future context
- Semantic search retrieves relevant memories for new prompts
- Uses SQLite FTS5 (zero dependencies) or Ollama embeddings when available

- nomic-embed-text(recommended)
- mxbai-embed-large
- all-minilm

All/agenticinteractions are logged for training data generation:

- Inputs:Prompts, injected context, agent/model used
- Outputs:LLM responses, proposed files, explanations
- Decisions:Which files were accepted/rejected
- Edits:User modifications to proposed content

import { exportObservations, exportPreferencePairs } from 'puzldai/observation'; // Export all observations as JSONL exportObservations({ outputPath: 'observations.jsonl', format: 'jsonl' }); // Export DPO training pairs (chosen vs rejected) exportPreferencePairs({ outputPath: 'preferences.jsonl', format: 'jsonl' });

- accept_reject— User accepted some files, rejected others
- user_edit— User modified the LLM's proposed content
- full_reject— User rejected all proposed files

Index your codebase for semantic search and automatic context injection.

# TUI /index # Open indexing panel /index search "auth" # Search indexed code # CLI puzld index # Index current directory puzld index --quick # Skip embeddings (faster) puzld index --search "handleLogin" puzld index --context "fix auth bug" puzld index --config # Show detected config files puzld index --graph # Show dependency graph

- Functions, classes, interfaces, types
- Import/export relationships
- File dependencies with tsconfig path alias support

Project instructions (auto-injected into prompts):

- AGENTS.md— Project-wide instructions
- CLAUDE.md,CODEX.md— Agent-specific instructions
- .cursorrules,copilot-instructions.md— IDE rules
- .puzldai/agents/*.md— Per-agent instructions

When you run/agentic, project instructions are automatically injected into the prompt.

/compare claude,gemini "task" Compare agents side-by-side /autopilot "task" AI-planned workflow /workflow code-review "code" Run saved workflow /workflows Manage templates /correct claude gemini "task" Cross-agent correction /debate claude,gemini "topic" Multi-agent debate /consensus claude,gemini "task" Build consensus @claude "task" Agentic mode with Claude @gemini "task" Agentic mode with Gemini /plan @claude "task" Plan mode (analyze, no execution) /build @claude "task" Build mode (full tool access) /index Codebase indexing options /index search "query" Search indexed code /session Start new session /resume Resume previous session /settings Open settings panel /changelog Show version history /agent claude Switch agent /model Model selection panel /router ollama Set routing agent /planner claude Set autopilot planner /sequential Toggle: compare one-at-a-time /pick Toggle: select best from compare /execute Toggle: auto-run autopilot plans /interactive Toggle: pause between steps /help All commands

puzldai # Launch TUI puzldai run "task" # Single task puzldai run "task" -a claude # Force agent puzldai run "task" -m opus # Override model puzldai run "task" -P "..." # Pipeline puzldai run "task" -T template # Use template puzldai run "task" -i # Interactive: pause between steps puzldai compare "task" # Compare (default: claude,gemini) puzldai compare "task" -a a,b,c # Specify agents puzldai compare "task" -s # Sequential mode puzldai compare "task" -p # Pick best response puzldai autopilot "task" # Generate plan puzldai autopilot "task" -x # Plan + execute puzldai autopilot "task" -p claude # Use specific planner puzldai correct "task" --producer claude --reviewer gemini puzldai correct "task" --producer claude --reviewer gemini --fix puzldai debate "topic" -a claude,gemini -r 3 -m ollama puzldai consensus "task" -a claude,gemini -r 3 -s claude puzldai session list # List sessions puzldai session new # Create new session puzldai check # Agent status puzldai agent # Interactive agent mode puzldai agent -a claude # Force specific agent puzldai agent -m sonnet # With specific model puzldai model show # Show current models puzldai model list # List available models puzldai model set claude opus # Set model for agent puzldai model clear claude # Reset to CLI default puzldai serve # API server puzldai serve -p 8080 # Custom port puzldai serve -w # With web terminal puzldai template list # List templates puzldai template show <name> # Show template details puzldai template create <name> -P "..." -d "desc" puzldai template edit <name> # Edit template puzldai template delete <name> # Delete template puzldai index # Index codebase puzldai index --quick # Skip embeddings puzldai index --search "query" # Search indexed code puzldai index --context "task" # Get relevant context puzldai index --config # Show project config

{ "defaultAgent": "auto", "fallbackAgent": "claude", "routerModel": "llama3.2", "adapters": { "claude": { "enabled": true, "path": "claude", "model": "sonnet" }, "gemini": { "enabled": true, "path": "gemini", "model": "gemini-2.5-pro" }, "codex": { "enabled": false, "path": "codex", "model": "gpt-5.1-codex" }, "ollama": { "enabled": true, "model": "llama3.2" }, "mistral": { "enabled": true, "path": "vibe" } } }

User Input (@claude "fix bug") │ ▼ ┌─────────┐ ┌────────────┐ ┌──────────┐ │ CLI/TUI │────▶│ Orchestrator│────▶│ Adapters │ └─────────┘ └────────────┘ └──────────┘ │ │ ┌─────────────┼─────────────┐ │ ▼ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌──────────────┐ │ Router │ │ Memory │ │ Agents │ │ (Ollama) │ │ (RAG) │ │ Claude │ └───────────┘ └───────────┘ │ Gemini │ │ │ │ Codex │ ▼ ▼ │ Ollama │ ┌───────────┐ ┌───────────┐ │ Mistral │ │ Indexing │ │Observation│ └──────────────┘ │ (AST/FTS) │ │ Logger │ └───────────┘ └───────────┘ │ │ ▼ ▼ ┌───────────────────────────────┐ │ Agent Loop │ │ LLM ──▶ Tool Call ──▶ Result │ │ ▲ │ │ │ │ │ ┌─────▼─────┐ │ │ │ │ │ Permission│ │ │ │ │ │ Prompts │ │ │ │ │ └───────────┘ │ │ │ └──────────────────────┘ │ └───────────────────────────────┘ │ │ ▼ ▼ ┌───────────┐ ┌───────────┐ │ Diff │ │ Export │ │ Review │ │ (DPO) │ └───────────┘ └───────────┘

PuzldAI doesn't handle your AI credentials directly. Instead, it orchestrates the official CLI tools you already have installed:

- No credential exposure— Your tokens stay with the official CLIs
- No piggybacking— We don't borrow OAuth client IDs or reverse-engineer auth endpoints
- No terms violations— We use CLIs exactly as their creators intended
- Always up-to-date— When CLIs update their auth, you get it automatically
- Your auth, your control— Log in once per CLI, PuzldAI just orchestrates

Some tools bypass official CLIs to call APIs directly using piggybacked credentials or unofficial OAuth flows. PuzldAI takes a different approach: we wrap the tools you trust, nothing more.

git clone https://github.com/MedChaouch/Puzld.ai.git cd Puzld.ai bun install bun run build npm link puzldai

Pull requests welcome! Please ensure your changes pass the build before submitting.

Agent-native developer Q&A API with MCP + A2A endpoints for citations, job pickup, and answer submission.

Unified MCP & skill management gateway with progressive disclosure. Manages multiple MCP servers as Agent Apps, loading tool schemas on demand for 99% context token savings. Shared across Claude Code, Codex, OpenCode and more.

Open-source, self-hosted AI gateway with built-in MCP client and server support for connecting MCP tools to AI applications.

Integrate with the Flowise API to create predictions and manage chatflows and assistants.

Unified MCP gateway that gives AI agents access to 100+ tools, marketplace MCPs, and custom MCP servers through simple search and execute workflows.

a complete and intuitive SDK for building MCP Servers, MCP Agents, and LLM integrations (OpenAI, Claude, Gemini) with minimal effort. It abstracts all the complexity of the MCP protocol, provides an intelligent agent with automatic model routing, and includes a universal client for external APIs all through a single, simple, and powerful interface. Perfect for chatbots, enterprise automation, internal system integrations, and rapid development of MCP-based ecosystems.

Meta-MCP gateway: search ~75k MCP servers from the public registries via five meta-tools and call any of them on the fly — local-first, with SSRF guard and stdio allowlist.

A Node.js server for AI agents to discover, install, and manage new capabilities on demand via the MCP protocol.

The Ultimate Control Plane for MCP Unlock the full power of Model Context Protocol with zero friction. One-Click GPT Integration: Bridge the gap between MCP servers and ChatGPT/LLMs instantly. No more manual config hunting. Pro-Level Orchestration: Manage, monitor, and toggle multiple MCP tools from a single, intuitive dashboard. Secure by Design: Built-in support for complex auth flows and 2FA, making enterprise-grade tool integration seamless. Streamlined Debugging: Test queries and inspect tool responses in real-time without leaving the hub. Stop wrestling with JSON configs. Start building agentic workflows that actually work.